DEPLOYMENT_CHECKLIST.md

# Hugging Face Spaces 部署檢查清單

## 部署前檢查

### 必要檔案
- [ ] `Dockerfile` - Docker 建置配置
- [ ] `README.md` - Space 配置檔（包含 YAML front matter）
- [ ] `.dockerignore` - 排除不需要的檔案
- [ ] `.env.example` - 環境變數範例
- [ ] `DEPLOYMENT.md` - 部署指南

### 專案檔案
- [ ] `package.json` - 根目錄 workspace 配置
- [ ] `pnpm-lock.yaml` - 依賴鎖定檔
- [ ] `pnpm-workspace.yaml` - Workspace 配置
- [ ] `tsconfig.base.json` - TypeScript 基礎配置
- [ ] `tsconfig.json` - TypeScript 配置

### 後端檔案
- [ ] `artifacts/api-server/` - 完整後端程式碼
- [ ] `artifacts/api-server/src/index.ts` - 已移除背景 token refresh
- [ ] `artifacts/api-server/src/lib/localTempStorage.ts` - 本地暫存邏輯

### 前端檔案
- [ ] `artifacts/image-gen/` - 完整前端程式碼
- [ ] `artifacts/image-gen/dist/` - 建置後會自動生成

### 資料庫檔案
- [ ] `lib/db/` - 資料庫層
- [ ] `lib/db/package.json` - 已更新為 better-sqlite3
- [ ] `lib/db/drizzle.config.ts` - 已改為 SQLite 配置
- [ ] `lib/db/src/index.ts` - 已改為 SQLite 連接

### 共享庫
- [ ] `lib/api-client-react/` - React API 客戶端
- [ ] `lib/api-spec/` - OpenAPI 規格
- [ ] `lib/api-zod/` - Zod 驗證

## 環境變數設定

### 必要變數（在 Space Settings 中設定）
- [ ] `JWT_SECRET` - JWT 密鑰（至少 32 字元隨機字串）
- [ ] `ENCRYPTION_KEY` - 加密密鑰（必須是 32 字元）

### 可選變數
- [ ] `DATABASE_URL` - 資料庫路徑（預設：file:/data/sqlite.db）
- [ ] `TEMP_STORAGE_PATH` - 暫存路徑（預設：/app/temp-storage）
- [ ] `TURNSTILE_SOLVER_URL` - Turnstile 服務 URL（如有）

## Space 設定

### 基本設定
- [ ] Space SDK 選擇 "Docker"
- [ ] Space hardware 選擇 "CPU basic"（免費）
- [ ] License 設定為 "MIT"

### Persistent Storage
- [ ] 啟用 Persistent Storage
- [ ] 掛載路徑設定為 `/data`
- [ ] 確認容量足夠（免費版有限制）

## 建置檢查

### Docker 建置
- [ ] Dockerfile 語法正確
- [ ] 所有依賴都能正確安裝
- [ ] 前端建置成功
- [ ] 後端建置成功
- [ ] 暴露端口 7860

### 執行時檢查
- [ ] 伺服器能正常啟動
- [ ] 資料庫檔案能正確建立
- [ ] 暫存目錄能正確建立
- [ ] 日誌輸出正常

## 功能測試

### 基本功能
- [ ] 首頁能正常載入
- [ ] 用戶註冊功能正常
- [ ] 用戶登入功能正常
- [ ] 第一個用戶成為管理員

### 管理功能
- [ ] 能進入管理後台
- [ ] 能設定 geminigen.ai 憑證
- [ ] 能查看系統狀態
- [ ] 能管理用戶

### 圖像生成
- [ ] 能輸入提示詞
- [ ] 能選擇模型
- [ ] 能選擇風格和比例
- [ ] 能上傳參考圖像
- [ ] 能成功生成圖像
- [ ] 圖像能正常顯示

### 影片生成
- [ ] 能輸入提示詞
- [ ] 能選擇模型（Grok-3 / Veo 3.1）
- [ ] 能設定進階選項
- [ ] 能上傳參考圖像
- [ ] 能成功生成影片
- [ ] 進度追蹤正常
- [ ] 影片能正常播放

### 歷史記錄
- [ ] 圖像歷史能正常顯示
- [ ] 影片歷史能正常顯示
- [ ] 能刪除記錄
- [ ] 私密/公開過濾正常

## 效能檢查

### 資源使用
- [ ] CPU 使用率合理
- [ ] 記憶體使用率合理
- [ ] 磁碟空間足夠

### 回應時間
- [ ] 頁面載入速度可接受
- [ ] API 回應時間合理
- [ ] 圖像生成時間正常
- [ ] 影片生成時間正常

## 維護檢查

### 自動清理
- [ ] 舊檔案能自動清理（24 小時）
- [ ] 清理日誌正常輸出
- [ ] 磁碟空間不會持續增長

### 日誌監控
- [ ] 能在 Space Logs 查看日誌
- [ ] 錯誤日誌清晰可讀
- [ ] 無異常錯誤持續出現

### 備份
- [ ] 知道如何備份資料庫
- [ ] 知道如何還原資料庫
- [ ] 定期備份計畫已建立

## 安全檢查

### 憑證安全
- [ ] JWT_SECRET 是隨機生成的
- [ ] ENCRYPTION_KEY 是隨機生成的
- [ ] 不在程式碼中硬編碼敏感資訊
- [ ] .env 檔案已加入 .gitignore

### 存取控制
- [ ] 管理功能需要管理員權限
- [ ] 私密內容只有擁有者能查看
- [ ] API 端點有適當的認證

## 文件檢查

### 使用者文件
- [ ] README.md 說明清楚
- [ ] DEPLOYMENT.md 步驟完整
- [ ] .env.example 註解清楚

### 開發文件
- [ ] 程式碼註解充足
- [ ] 關鍵邏輯有說明
- [ ] 已知限制有記錄

## 部署後驗證

### 立即檢查
- [ ] Space 狀態為 "Running"
- [ ] 能訪問 Space URL
- [ ] 首頁正常顯示
- [ ] 無 JavaScript 錯誤

### 24 小時後檢查
- [ ] Space 仍在運行
- [ ] 資料庫資料保存正常
- [ ] 舊檔案已自動清理
- [ ] 無記憶體洩漏

### 一週後檢查
- [ ] 長期穩定性良好
- [ ] 磁碟空間使用穩定
- [ ] 無異常錯誤累積
- [ ] 用戶回饋正面

## 問題排查

### 常見問題
- [ ] 知道如何查看日誌
- [ ] 知道如何重啟 Space
- [ ] 知道如何還原資料
- [ ] 知道如何聯繫支援

### 緊急處理
- [ ] 有備份還原計畫
- [ ] 有降級方案
- [ ] 有聯繫管道

## 完成確認

- [ ] 所有檢查項目都已完成
- [ ] 所有功能都正常運作
- [ ] 文件都已更新
- [ ] 團隊成員都已知悉

---

**部署日期**: _______________

**部署人員**: _______________

**Space URL**: _______________

**備註**: