product-playbook 1.0.0

package/i18n/zh-TW/references/07b-tasks-tickets.md

@@ -0,0 +1,215 @@
+# 開發銜接 — TASKS.md + TICKETS.md
+
+## 📄 TASKS.md 模板
+
+功能拆解的核心原則：
+- 從 MVP 必須有（P0）的功能出發
+- 每個 Task 對應一個 User Story
+- Phase 之間有明確的依賴關係：Phase N+1 依賴 Phase N 的產出
+- 每個 Task 包含驗收標準，Claude Code 可以自我檢查
+
+```markdown
+# [產品名稱] — 開發任務清單
+
+## Phase 0：專案初始化
+> 目標：建立可運行的空白專案骨架
+
+- [ ] **T0.1** 初始化專案（`scripts/setup.sh` 或手動）
+  - 驗收：
+    - [ ] `npm run dev` / `python manage.py runserver` 等指令可啟動
+    - [ ] `.gitignore` 已建立，包含 `.env`、`.env.local`、`node_modules/`、`.product-playbook-progress.md` 等敏感檔案
+    - [ ] `.env.example` 已建立（只有 key 名稱，沒有實際值）
+- [ ] **T0.2** 設定 linter + formatter
+  - 驗收：lint 通過無錯誤
+- [ ] **T0.3** 建立資料庫 + 執行初始 migration
+  - 驗收：資料庫可連接，基礎 table 已建立
+- [ ] **T0.4** 建立基礎路由結構
+  - 驗收：所有主要頁面路由可訪問（回傳空白頁面即可）
+
+## Phase 1：核心流程（Aha Moment 路徑）
+> 目標：讓用戶可以走完從進入到 Aha Moment 的最短路徑
+> 對應 User Story：[US-001, US-002, ...]
+
+- [ ] **T1.1** [功能名稱]
+  - User Story：身為 [Persona]，我想要 [行為]，以便 [價值]
+  - 驗收標準：
+    - [ ] [可測試的具體條件 1]
+    - [ ] [可測試的具體條件 2]
+  - 技術備註：[需要的 API / 第三方服務 / 特殊邏輯]
+
+- [ ] **T1.2** [功能名稱]
+  - User Story：...
+  - 驗收標準：...
+
+> **Phase 1 完成檢查點**：用戶可以完成 [Aha Moment 行為]。如果不行，不要進入 Phase 2。
+
+## Phase 2：完整 MVP
+> 目標：補全 MVP 範圍中所有 P0 功能
+> 對應 User Story：[US-003, US-004, ...]
+
+- [ ] **T2.1** [功能名稱]
+  - ...
+
+> **Phase 2 完成檢查點**：所有 P0 User Story 的驗收標準都通過。
+
+## Phase 3：品質與體驗
+> 目標：錯誤處理、邊界情境、載入狀態、基礎安全性
+
+- [ ] **T3.1** 全域錯誤處理
+- [ ] **T3.2** 表單驗證 + 邊界情境
+- [ ] **T3.3** 載入狀態 + 空狀態
+- [ ] **T3.4** 安全性檢查（依 `references/08-security-checklist.md` 逐項確認）
+  - 驗收：
+    - [ ] OWASP Top 10 相關項目已處理（輸入驗證、認證、XSS 防護、CSRF 防護）
+    - [ ] 安全性 Headers 已設定（CSP、X-Frame-Options、HSTS 等）
+    - [ ] CORS 政策已配置（不使用 wildcard *）
+    - [ ] 敏感 API 端點有 Rate Limiting
+    - [ ] API 錯誤回應不洩漏內部資訊
+- [ ] **T3.5** 響應式設計（如果是 Web）
+
+## Phase 4：部署
+> 目標：可以讓外部用戶訪問
+
+- [ ] **T4.1** 環境變數管理
+- [ ] **T4.2** 部署配置
+- [ ] **T4.3** 基礎監控 + 日誌
+```
+
+---
+
+## 📄 TICKETS.md 模板
+
+TICKETS.md 是根據 TASKS.md 中的功能拆解，產出可直接在專案管理工具中開票的結構化內容。每張票包含 PM 開票所需的完整資訊。
+
+> **設計目標**：PM 可以直接將每張票的內容複製到 Jira / Asana / Linear 等工具中開票，後續版本將支援透過 API 自動開票。
+
+```markdown
+# [產品名稱] — 開票清單
+
+> 產出時間：[時間戳]
+> 對應 TASKS.md 版本：[版本/時間]
+> 共 [N] 張票
+
+---
+
+## 票務總覽
+
+| 票號 | 標題 | Phase | 優先級 | 預估工時 | 依賴 |
+|------|------|-------|--------|---------|------|
+| TKT-001 | [標題] | Phase 0 | P0 | [X]h | — |
+| TKT-002 | [標題] | Phase 1 | P0 | [X]h | TKT-001 |
+| ... | | | | | |
+
+---
+
+## TKT-001：[標題]
+
+**Phase**：Phase 0 — 專案初始化
+**對應 Task**：T0.1
+**優先級**：P0
+**預估工時**：[X] 小時
+**依賴**：無
+**指派對象**：[角色/團隊，例如：後端工程師]
+
+### 描述
+
+[用 1-3 段文字描述這張票要完成什麼，包含業務背景和技術目標]
+
+### User Story
+
+身為 [Persona]，我想要 [行為]，以便 [價值]
+
+### 驗收標準
+
+- [ ] [可測試的具體條件 1]
+- [ ] [可測試的具體條件 2]
+- [ ] [可測試的具體條件 3]
+
+### 技術備註
+
+- [實作注意事項]
+- [需要的 API / 第三方服務]
+- [相關檔案路徑或模組]
+
+### 標籤建議
+
+`[Phase 0]` `[backend]` `[setup]`
+
+---
+
+## TKT-002：[標題]
+
+[同上格式，逐張展開]
+```
+
+### 開票規則
+
+1. **票號對應 Task**：每個 TASKS.md 中的 Task 對應一張票（TKT-001 ↔ T0.1），粒度過大的 Task 可拆為多張票
+2. **優先級繼承**：Phase 0-1 預設 P0，Phase 2 預設 P1，Phase 3-4 預設 P2，可根據 RICE 分數調整
+3. **依賴關係**：明確標記票與票之間的前後依賴，避免工程師跳步開發
+4. **預估工時**：根據 Task 粒度原則（1-4 小時），提供合理預估
+5. **標籤建議**：包含 Phase、技術領域（frontend / backend / database / infra）、功能模組
+
+### 專案管理工具串接（預留）
+
+> 以下為未來自動開票功能的預留接口設計，目前版本僅產出 TICKETS.md 供 PM 手動開票。
+
+TICKETS.md 的結構化格式已預留以下欄位，便於後續透過 API 自動匯入：
+
+| 欄位 | Jira 對應 | Asana 對應 | Linear 對應 |
+|------|----------|-----------|------------|
+| 票號 | Issue Key | Task ID | Issue ID |
+| 標題 | Summary | Task Name | Title |
+| 描述 | Description | Description | Description |
+| 優先級 | Priority | Custom Field | Priority |
+| 預估工時 | Story Points / Time Estimate | Custom Field | Estimate |
+| 依賴 | Linked Issues | Dependencies | Relations |
+| 標籤 | Labels + Components | Tags | Labels |
+| Phase | Epic | Section | Project |
+| 指派對象 | Assignee | Assignee | Assignee |
+| 驗收標準 | Acceptance Criteria (Description) | Subtasks | Sub-issues |
+
+---
+
+## 功能拆解邏輯
+
+將 MVP 功能轉換為 Task 的規則：
+
+### Phase 劃分原則
+
+```
+Phase 0：專案骨架（所有模式都必須有）
+  → 初始化、linter、DB、基礎路由
+
+Phase 1：Aha Moment 最短路徑（最重要）
+  → 從用戶進入到達 Aha Moment 所需的最少功能
+  → 只包含這條路徑上的 P0 功能
+
+Phase 2：完整 MVP
+  → 補全 Phase 1 沒有覆蓋的其他 P0 功能
+  → 支線流程、次要頁面
+
+Phase 3：品質與體驗
+  → 錯誤處理、邊界情境、載入/空狀態
+  → 安全性基礎、響應式設計
+
+Phase 4：部署
+  → 環境變數、部署配置、監控
+```
+
+### Task 粒度原則
+
+- 每個 Task 應該可以在 **1-4 小時** 內完成
+- 太大 → 拆成子 Task（T1.1a, T1.1b）
+- 太小 → 合併到相關 Task
+- 每個 Task 必須有至少一個可測試的驗收標準
+
+### User Story → Task 對應
+
+```
+一個 User Story 可能對應 1-3 個 Task：
+  US-001: 身為新用戶，我想要註冊帳號，以便開始使用
+    → T1.1: 註冊頁面 UI
+    → T1.2: 註冊 API + 資料驗證
+    → T1.3: Email 驗證流程（如果 MVP 需要）
+```

package/i18n/zh-TW/references/07c-architecture-setup.md

@@ -0,0 +1,197 @@
+# 開發銜接 — ARCHITECTURE.md + setup.sh
+
+## 📄 ARCHITECTURE.md 模板
+
+```markdown
+# [產品名稱] — 技術架構
+
+## 目錄結構
+
+[根據技術棧產出對應的目錄結構]
+
+## 資料庫設計
+
+[從 PRD 的 DB Schema 整合，轉為建表 SQL 或 ORM Model 定義]
+
+### ER 關係圖
+
+[Mermaid erDiagram]
+
+### 關鍵 Table 說明
+
+| Table | 說明 | 關鍵欄位 | 索引建議 |
+|-------|------|---------|---------|
+| | | | |
+
+## API 設計
+
+[根據 User Story 和功能規格，定義 RESTful API endpoints 或 GraphQL schema]
+
+### Endpoints 清單
+
+| 方法 | 路徑 | 說明 | 對應 Task |
+|------|------|------|----------|
+| GET | /api/v1/[resource] | [說明] | T1.1 |
+| POST | /api/v1/[resource] | [說明] | T1.2 |
+
+### 認證方式
+
+[JWT / Session / OAuth 等]
+
+## 第三方服務
+
+| 服務 | 用途 | 對應功能 |
+|------|------|---------|
+| | | |
+
+## 安全架構
+
+### CORS 配置
+
+| 設定項 | 值 | 說明 |
+|--------|---|------|
+| 允許的 Origins | [生產域名, localhost:port] | 不使用 wildcard * |
+| 允許的 Methods | GET, POST, PUT, DELETE | 依 API 實際需求 |
+| 允許的 Headers | Content-Type, Authorization | |
+| Credentials | true/false | 依認證方式決定 |
+
+### 安全性 Headers
+
+[根據產品需求，從 references/08-security-checklist.md §5 選擇適用的 Headers]
+
+### Rate Limiting 策略
+
+| 端點類型 | 限制 | 識別方式 |
+|---------|------|---------|
+| 一般 API | [X] req/min | IP + User ID |
+| 登入/註冊 | [X] req/min | IP |
+| 檔案上傳 | [X] req/min | User ID |
+
+### 敏感資料處理
+
+- 密鑰管理：[.env + 平台環境變數 / Secrets Manager]
+- 日誌規範：不記錄密碼、Token、個人資料
+- 資料加密：[傳輸中 TLS / 儲存時加密需求]
+
+> 完整安全性檢查清單見 `references/08-security-checklist.md`
+```
+
+---
+
+## 📄 .gitignore 模板
+
+```gitignore
+# 環境變數與密鑰
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# 產品規劃進度（可能包含敏感商業資訊）
+.product-playbook-progress.md
+
+# IDE 與作業系統
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# 依賴
+node_modules/
+__pycache__/
+*.pyc
+venv/
+
+# 建置產出
+dist/
+build/
+.next/
+```
+
+---
+
+## 📄 setup.sh 模板
+
+```bash
+#!/bin/bash
+# [產品名稱] — 專案初始化腳本
+# 使用方式：chmod +x scripts/setup.sh && ./scripts/setup.sh
+
+set -e
+
+echo "🚀 正在初始化 [產品名稱]..."
+
+# ===== 檢查前置條件 =====
+command -v [node/python/etc] >/dev/null 2>&1 || { echo "❌ 需要安裝 [runtime]"; exit 1; }
+
+# ===== 安裝依賴 =====
+echo "📦 安裝依賴..."
+[npm install / pip install -r requirements.txt / etc]
+
+# ===== 環境設定 =====
+if [ ! -f .env ]; then
+  echo "📝 建立 .env 檔案..."
+  cp .env.example .env
+  echo "⚠️  請編輯 .env 填入必要的環境變數"
+fi
+
+# ===== 資料庫初始化 =====
+echo "🗄️  初始化資料庫..."
+[migration commands]
+
+echo ""
+echo "✅ 初始化完成！"
+echo ""
+echo "下一步："
+echo "  1. 編輯 .env 填入環境變數"
+echo "  2. 啟動開發伺服器：[start command]"
+echo "  3. 開始開發：claude \"請讀取 CLAUDE.md 和 TASKS.md，開始執行 Phase 1\""
+```
+
+---
+
+## 使用者引導文字
+
+### 在 Claude Chat / Cowork 中
+
+產出開發交接包後，顯示以下引導：
+
+```
+📦 開發交接包已準備好！包含以下檔案：
+
+  CLAUDE.md        → Claude Code 的專案記憶（產品上下文 + 技術規範）
+  TASKS.md         → 開發任務清單（4 個 Phase，共 [N] 個 Task）
+  TICKETS.md       → 開票清單（共 [N] 張票，可直接在 Jira/Asana/Linear 開票）
+  docs/PRD.md      → 完整 PRD
+  docs/ARCHITECTURE.md → 技術架構（DB schema + API + 目錄結構）
+  docs/PRODUCT-SPEC.md → 產品規格摘要
+  scripts/setup.sh → 一鍵初始化腳本
+
+🔗 如何開始開發：
+
+  1. 下載並解壓到你的專案資料夾
+  2. 開啟終端機，進入專案資料夾
+  3. 啟動 Claude Code：
+     $ claude
+  4. 告訴 Claude Code 開始：
+     > 請讀取 CLAUDE.md 和 TASKS.md，開始執行 Phase 0
+
+💡 小提示：
+  - Claude Code 會自動讀取 CLAUDE.md，所以它已經知道整個產品上下文
+  - 每個 Phase 完成後，它會詢問你是否要進入下一個 Phase
+  - 如果要調整功能範圍，直接修改 TASKS.md 即可
+  - CLAUDE.md 中的「明確不做」清單會防止 Claude Code 做超出範圍的事
+```
+
+### 產出前的最終確認
+
+```
+在產出開發交接包前，我需要確認幾件事：
+
+1. 技術棧：[已確認 / 需要確認]
+2. 產品名稱（用於專案資料夾名稱）：[已確認 / 需要確認]
+3. 是否有其他技術限制或偏好？
+   - 例如：必須用某個 ORM、需要支援特定瀏覽器、有既有的 CI/CD 等
+```

package/i18n/zh-TW/references/08-security-checklist.md

@@ -0,0 +1,221 @@
+# 安全性檢查清單
+
+> 在產出開發交接包前載入。確保產品規劃階段已考慮關鍵安全性需求，避免安全性成為事後補救。
+
+## 🔐 安全架構快速檢查
+
+在產出開發交接包前，必須逐項確認以下安全性面向。每個面向標記 ✅（已在規劃中涵蓋）或 ❌（需要補充）。
+
+### 1. 認證與授權（Authentication & Authorization）
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| 認證方式已確定（JWT / Session / OAuth / Passkey） | | |
+| Token 儲存方式安全（HttpOnly Cookie，非 localStorage） | | |
+| Token 過期與刷新機制已設計 | | |
+| 密碼儲存使用 bcrypt / argon2（不用 MD5/SHA） | | |
+| 權限模型已定義（RBAC / ABAC / 簡單角色） | | |
+| API 端點都有對應的授權檢查 | | |
+| 登入失敗有暴力破解防護（鎖定 / 漸進延遲） | | |
+```
+
+**JWT 最佳實踐（如果選用 JWT）：**
+- 使用短效 Access Token（15-30 分鐘）+ 長效 Refresh Token
+- Refresh Token 存放在 HttpOnly Secure Cookie
+- 實作 Token Revocation（登出時使 Refresh Token 失效）
+- 不在 JWT payload 中存放敏感資訊
+
+### 2. CORS 政策（Cross-Origin Resource Sharing）
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| 已定義允許的 Origin 清單（不使用 *） | | |
+| 僅允許必要的 HTTP Methods | | |
+| 已設定 Access-Control-Allow-Credentials | | |
+| Preflight 快取時間合理（Access-Control-Max-Age） | | |
+```
+
+**CORS 配置模板：**
+```
+允許的 Origins：
+  - 生產環境：https://[your-domain.com]
+  - 開發環境：http://localhost:[port]
+
+允許的 Methods：GET, POST, PUT, DELETE, PATCH
+允許的 Headers：Content-Type, Authorization
+Credentials：true（如果使用 Cookie 認證）
+Max-Age：86400（24 小時）
+```
+
+### 3. 輸入驗證與消毒（Input Validation & Sanitization）
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| 所有 API 輸入都有 Server-side 驗證 | | |
+| 使用參數化查詢（Parameterized Query）防 SQL Injection | | |
+| 使用者輸入經過 Output Encoding 後才渲染到 HTML（防 XSS） | | |
+| 檔案上傳有類型 / 大小限制 | | |
+| URL / Redirect 目標有白名單驗證（防 Open Redirect） | | |
+```
+
+**驗證原則：**
+- 前端驗證是 UX，後端驗證是安全性 — 兩者都需要，但後端驗證不可省略
+- 使用 Schema Validation Library（如 Zod、Joi、Pydantic）統一驗證邏輯
+- 拒絕不符合預期格式的輸入，不要試圖「修復」用戶輸入
+
+### 4. CSRF 防護（Cross-Site Request Forgery）
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| 變更操作使用 POST/PUT/DELETE（非 GET） | | |
+| 實作 CSRF Token 或使用 SameSite Cookie | | |
+| 關鍵操作有二次確認機制 | | |
+```
+
+### 5. 安全性 Headers
+
+```
+| Header | 用途 | 建議值 |
+|--------|------|--------|
+| Content-Security-Policy (CSP) | 防 XSS、資料注入 | default-src 'self'; script-src 'self' |
+| X-Content-Type-Options | 防 MIME Sniffing | nosniff |
+| X-Frame-Options | 防 Clickjacking | DENY 或 SAMEORIGIN |
+| Strict-Transport-Security (HSTS) | 強制 HTTPS | max-age=31536000; includeSubDomains |
+| X-XSS-Protection | 瀏覽器 XSS 過濾 | 0（依賴 CSP 更可靠） |
+| Referrer-Policy | 控制 Referrer 資訊 | strict-origin-when-cross-origin |
+| Permissions-Policy | 限制瀏覽器功能 | camera=(), microphone=(), geolocation=() |
+```
+
+### 6. API 安全與 Rate Limiting
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| API 有全域 Rate Limiting（如 100 req/min/IP） | | |
+| 敏感端點有更嚴格的限制（登入 5 req/min、註冊 3 req/min） | | |
+| API 錯誤回應不洩漏內部資訊（堆疊追蹤、SQL 語句） | | |
+| API Versioning 策略已確定（/api/v1/） | | |
+| 大量資料端點有分頁（Pagination）限制 | | |
+```
+
+**Rate Limiting 設計建議：**
+```
+| 端點類型 | 建議限制 | 識別方式 |
+|---------|---------|---------|
+| 一般 API | 100 req/min | IP + User ID |
+| 登入/註冊 | 5 req/min | IP |
+| 密碼重設 | 3 req/hour | IP + Email |
+| 檔案上傳 | 10 req/min | User ID |
+| 搜尋/查詢 | 30 req/min | IP + User ID |
+```
+
+### 7. 防爬蟲與 Bot 防護
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| robots.txt 已配置（限制敏感路徑） | | |
+| 關鍵表單有 Bot 防護（reCAPTCHA / hCaptcha / Honeypot） | | |
+| API 有 User-Agent 檢查（可選） | | |
+| 敏感操作有行為分析（可選，進階） | | |
+```
+
+**分層防護策略：**
+1. **基礎層**：Rate Limiting + robots.txt — 所有產品都應該有
+2. **標準層**：+ CAPTCHA（註冊/登入）+ Honeypot 欄位 — B2C 產品建議
+3. **進階層**：+ 行為分析 + IP 信譽 + Device Fingerprint — 高風險產品
+
+### 8. 敏感資料保護
+
+```
+| 檢查項目 | 狀態 | 備註 |
+|---------|------|------|
+| 敏感資料在傳輸中加密（HTTPS/TLS） | | |
+| 敏感資料在儲存時加密（如需要） | | |
+| 密鑰和 Secrets 不存在程式碼中 | | |
+| .env 和敏感檔案已加入 .gitignore | | |
+| 日誌不記錄密碼、Token、信用卡號等 | | |
+| 有明確的資料保留與刪除政策（GDPR 如適用） | | |
+```
+
+**Secrets 管理建議：**
+- 開發環境：`.env` 檔案（不進版控）+ `.env.example`（只有 key 名稱，沒有值）
+- 生產環境：使用平台提供的環境變數管理（Vercel Environment Variables / Railway Variables / AWS Secrets Manager）
+- 不要在 commit message、PR description、issue 中提及 secrets
+
+### 9. .gitignore 安全模板
+
+```gitignore
+# 環境變數與密鑰
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# 產品規劃進度（可能包含敏感商業資訊）
+.product-playbook-progress.md
+
+# IDE 與作業系統
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# 依賴
+node_modules/
+__pycache__/
+*.pyc
+venv/
+
+# 建置產出
+dist/
+build/
+.next/
+```
+
+---
+
+## 🏷️ OWASP Top 10 快速對照
+
+| # | 風險 | 本產品是否相關 | 對應檢查項 |
+|---|------|-------------|-----------|
+| A01 | Broken Access Control | [是/否] | §1 認證與授權 |
+| A02 | Cryptographic Failures | [是/否] | §8 敏感資料保護 |
+| A03 | Injection（SQL / XSS / Command） | [是/否] | §3 輸入驗證 |
+| A04 | Insecure Design | [是/否] | 整體架構設計 |
+| A05 | Security Misconfiguration | [是/否] | §5 Headers + §2 CORS |
+| A06 | Vulnerable Components | [是/否] | 依賴管理（npm audit / pip audit） |
+| A07 | Authentication Failures | [是/否] | §1 認證與授權 |
+| A08 | Data Integrity Failures | [是/否] | §3 輸入驗證 + §8 資料保護 |
+| A09 | Logging & Monitoring Failures | [是/否] | §8 日誌規範 |
+| A10 | SSRF (Server-Side Request Forgery) | [是/否] | §3 URL 白名單驗證 |
+
+---
+
+## 📎 本檔案的整合時機
+
+| 觸發情境 | 整合動作 |
+|---------|---------|
+| 產出開發交接包前 | 執行安全性快速檢查，將結果整合進 CLAUDE.md 的「風險警示」和 ARCHITECTURE.md 的「安全架構」段落 |
+| 產出 PRD 時 | 將安全性相關檢查結果整合進 PRD §6「技術考量 → 安全性要求」 |
+| Pre-mortem 步驟 | 提示使用者考慮安全性失敗情境 |
+| 改版模式 S1 | 提示使用者提供既有產品的安全現況 |
+
+## 品質自檢
+
+```
+| 檢查項目 | ✅/❌ |
+|---------|------|
+| 認證方式已明確選定，不是留空的「待確認」 | |
+| 至少 3 個安全性 Headers 已規劃 | |
+| Rate Limiting 策略已針對產品特性調整（不是直接複製模板） | |
+| .gitignore 已包含所有敏感檔案 | |
+| OWASP Top 10 中標記為「相關」的項目都有對應措施 | |
+| 安全性措施的複雜度與產品階段匹配（MVP 不需要完美安全性，但基礎不可少） | |
+```