product-playbook 1.0.0

package/i18n/zh-CN/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-CN/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-CN/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 不需要完美安全性，但基础不可少） | |
+```