specops 0.2.5 → 0.3.2

package/.opencode/templates/summary.md

@@ -0,0 +1,248 @@
+# 总结模板
+
+`.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` 的模板，用于阶段完成文档。
+
+---
+
+## 文件模板
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [主要类别: auth, payments, ui, api, database, infra, testing 等]
+tags: [可搜索的技术标签: jwt, stripe, react, postgres, prisma]
+
+# 依赖图
+requires:
+  - phase: [依赖的前置阶段]
+    provides: [该阶段构建的、本阶段使用的内容]
+provides:
+  - [本阶段构建/交付内容的列表]
+affects: [需要此上下文的阶段名称或关键词列表]
+
+# 技术追踪
+tech-stack:
+  added: [本阶段新增的库/工具]
+  patterns: [建立的架构/代码模式]
+
+key-files:
+  created: [创建的重要文件]
+  modified: [修改的重要文件]
+
+key-decisions:
+  - "决策 1"
+  - "决策 2"
+
+patterns-established:
+  - "模式 1: 描述"
+  - "模式 2: 描述"
+
+requirements-completed: []  # 必填 — 从本计划 `requirements` frontmatter 字段复制所有需求 ID。
+
+# 指标
+duration: X分钟
+completed: YYYY-MM-DD
+---
+
+# 阶段 [X]: [名称] 总结
+
+**[描述成果的实质性一句话 — 不要写 "阶段完成" 或 "实现完毕"]**
+
+## 执行表现
+
+- **耗时:** [时间] (如 23 分钟, 1小时15分)
+- **开始:** [ISO 时间戳]
+- **完成:** [ISO 时间戳]
+- **任务:** [完成数量]
+- **修改文件:** [数量]
+
+## 完成事项
+- [最重要的成果]
+- [第二个关键成果]
+- [第三个（如适用）]
+
+## 任务提交
+
+每个任务独立原子提交:
+
+1. **任务 1: [任务名称]** - `abc123f` (feat/fix/test/refactor)
+2. **任务 2: [任务名称]** - `def456g` (feat/fix/test/refactor)
+3. **任务 3: [任务名称]** - `hij789k` (feat/fix/test/refactor)
+
+**计划元数据:** `lmn012o` (docs: 完成计划)
+
+_注意: TDD 任务可能有多次提交 (test → feat → refactor)_
+
+## 创建/修改的文件
+- `path/to/file.ts` - 功能说明
+- `path/to/another.ts` - 功能说明
+
+## 做出的决策
+[关键决策及简要理由，或 "无偏差，按计划执行"]
+
+## 计划偏差
+
+[如果无偏差: "无偏差，完全按计划执行"]
+
+[如果有偏差:]
+
+### 自动修复的问题
+
+**1. [规则 X - 类别] 简要描述**
+- **发现于:** 任务 [N] ([任务名称])
+- **问题:** [什么问题]
+- **修复:** [做了什么]
+- **修改文件:** [文件路径]
+- **验证:** [如何验证]
+- **提交于:** [hash] (任务提交的一部分)
+
+[... 每个自动修复重复 ...]
+
+---
+
+**总偏差:** [N] 个自动修复 ([按规则分类])
+**对计划的影响:** [简要评估 — 如 "所有自动修复对正确性/安全性必要。无范围蔓延。"]
+
+## 遇到的问题
+[问题及解决方式，或 "无"]
+
+[注意: "计划偏差" 记录通过偏差规则自动处理的计划外工作。"遇到的问题" 记录计划内工作中需要解决的问题。]
+
+## 用户设置要求
+
+[如果生成了 USER-SETUP.md:]
+**外部服务需要手动配置。** 参见 [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md):
+- 需要添加的环境变量
+- 控制台配置步骤
+- 验证命令
+
+[如果没有 USER-SETUP.md:]
+无需用户设置，不涉及外部服务配置。
+
+## 下一阶段准备
+[为下一阶段准备好了什么]
+[阻塞或关注点]
+
+---
+*阶段: XX-name*
+*完成时间: [日期]*
+```
+
+<frontmatter_guidance>
+**用途:** 通过依赖图实现自动上下文组装。Frontmatter 使总结元数据可机器读取，让 plan-phase 能快速扫描所有总结并根据依赖关系选择相关内容。
+
+**快速扫描:** Frontmatter 在前 ~25 行，跨所有总结扫描成本低，无需读取完整内容。
+
+**依赖图:** `requires`/`provides`/`affects` 在阶段间创建显式链接，支持传递闭包的上下文选择。
+
+**子系统:** 主要分类 (auth, payments, ui, api, database, infra, testing) 用于检测相关阶段。
+
+**标签:** 可搜索的技术关键词 (库、框架、工具) 用于技术栈感知。
+
+**关键文件:** 重要文件用于 PLAN.md 中的 @context 引用。
+
+**模式:** 已建立的约定，未来阶段应保持。
+
+**填充:** Frontmatter 在 execute-plan.md 的总结创建阶段填充。参见 `<step name="create_summary">` 获取逐字段指导。
+</frontmatter_guidance>
+
+<one_liner_rules>
+一句话描述必须有实质内容:
+
+**好的:**
+- "使用 jose 库实现 JWT 认证及刷新令牌轮换"
+- "Prisma schema 含 User, Session 和 Product 模型"
+- "通过 Server-Sent Events 实现实时指标的仪表盘"
+
+**差的:**
+- "阶段完成"
+- "认证已实现"
+- "基础完毕"
+- "所有任务完成"
+
+一句话应该告诉别人实际交付了什么。
+</one_liner_rules>
+
+<example>
+```markdown
+# 阶段 1: 基础 总结
+
+**使用 jose 库实现 JWT 认证及刷新令牌轮换，Prisma User 模型，以及受保护的 API 中间件**
+
+## 执行表现
+
+- **耗时:** 28 分钟
+- **开始:** 2025-01-15T14:22:10Z
+- **完成:** 2025-01-15T14:50:33Z
+- **任务:** 5
+- **修改文件:** 8
+
+## 完成事项
+- 含邮箱/密码认证的 User 模型
+- 使用 httpOnly JWT cookie 的登录/登出端点
+- 检查令牌有效性的受保护路由中间件
+- 每次请求时的刷新令牌轮换
+
+## 创建/修改的文件
+- `prisma/schema.prisma` - User 和 Session 模型
+- `src/app/api/auth/login/route.ts` - 登录端点
+- `src/app/api/auth/logout/route.ts` - 登出端点
+- `src/middleware.ts` - 受保护路由检查
+- `src/lib/auth.ts` - 使用 jose 的 JWT 工具函数
+
+## 做出的决策
+- 使用 jose 而非 jsonwebtoken (ESM 原生, Edge 兼容)
+- 15 分钟访问令牌配合 7 天刷新令牌
+- 将刷新令牌存储在数据库中以支持撤销
+
+## 计划偏差
+
+### 自动修复的问题
+
+**1. [规则 2 - 缺失关键项] 添加 bcrypt 密码哈希**
+- **发现于:** 任务 2 (登录端点实现)
+- **问题:** 计划未指定密码哈希，存储明文将是严重安全漏洞
+- **修复:** 注册时添加 bcrypt 哈希，登录时比对，salt rounds 10
+- **修改文件:** src/app/api/auth/login/route.ts, src/lib/auth.ts
+- **验证:** 密码哈希测试通过，明文从未存储
+- **提交于:** abc123f (任务 2 提交)
+
+**2. [规则 3 - 阻塞] 安装缺失的 jose 依赖**
+- **发现于:** 任务 4 (JWT 令牌生成)
+- **问题:** jose 包不在 package.json 中，导入失败
+- **修复:** 运行 `npm install jose`
+- **修改文件:** package.json, package-lock.json
+- **验证:** 导入成功，构建通过
+- **提交于:** def456g (任务 4 提交)
+
+---
+
+**总偏差:** 2 个自动修复 (1 个缺失关键项, 1 个阻塞)
+**对计划的影响:** 两个自动修复对安全性和功能性都是必要的。无范围蔓延。
+
+## 遇到的问题
+- jsonwebtoken 的 CommonJS 导入在 Edge 运行时失败，切换到 jose (计划中的库变更，按预期工作)
+
+## 下一阶段准备
+- 认证基础完成，可以开始功能开发
+- 公开发布前需要用户注册端点
+
+---
+*阶段: 01-foundation*
+*完成时间: 2025-01-15*
+```
+</example>
+
+<guidelines>
+**Frontmatter:** 必填，完成所有字段。支持未来规划的自动上下文组装。
+
+**一句话:** 必须有实质内容。"使用 jose 库实现 JWT 认证及刷新令牌轮换" 而非 "认证已实现"。
+
+**决策部分:**
+- 执行期间做出的关键决策及理由
+- 提取到 STATE.md 的累积上下文
+- 如无偏差使用 "无偏差，按计划执行"
+
+**创建后:** STATE.md 更新位置、决策、问题。
+</guidelines>

package/.opencode/templates/user-setup.md

@@ -0,0 +1,311 @@
+# 用户设置模板
+
+`.planning/phases/XX-name/{phase}-USER-SETUP.md` 的模板，记录 Claude 无法自动化的、需要人工操作的配置。
+
+**用途:** 记录确实需要人工操作的设置任务，包括账户创建、控制台配置、密钥获取。Claude 会自动化一切可能的操作；此文件只记录剩余的人工任务。
+
+---
+
+## 文件模板
+
+```markdown
+# 阶段 {X}: 需要用户设置
+
+**生成时间:** [YYYY-MM-DD]
+**阶段:** {phase-name}
+**状态:** 未完成
+
+完成以下项目以使集成正常工作。Claude 已自动化所有可能的操作；这些项目需要人工访问外部控制台/账户。
+
+## 环境变量
+
+| 状态 | 变量 | 来源 | 添加到 |
+|------|------|------|--------|
+| [ ] | `ENV_VAR_NAME` | [服务控制台 → 路径 → 到 → 值] | `.env.local` |
+| [ ] | `ANOTHER_VAR` | [服务控制台 → 路径 → 到 → 值] | `.env.local` |
+
+## 账户设置
+
+[仅在需要创建新账户时填写]
+
+- [ ] **创建 [服务] 账户**
+  - URL: [注册 URL]
+  - 跳过条件: 已有账户
+
+## 控制台配置
+
+[仅在需要控制台配置时填写]
+
+- [ ] **[配置任务]**
+  - 位置: [服务控制台 → 路径 → 到 → 设置]
+  - 设置为: [所需值或配置]
+  - 备注: [重要细节]
+
+## 验证
+
+完成设置后，用以下命令验证:
+
+```bash
+# [验证命令]
+```
+
+预期结果:
+- [成功的表现]
+
+---
+
+**所有项目完成后:** 将文件顶部状态标记为 "已完成"。
+```
+
+---
+
+## 何时生成
+
+当计划 frontmatter 包含 `user_setup` 字段时生成 `{phase}-USER-SETUP.md`。
+
+**触发条件:** PLAN.md frontmatter 中存在 `user_setup` 且有内容。
+
+**位置:** 与 PLAN.md 和 SUMMARY.md 同目录。
+
+**时机:** 在 execute-plan.md 中任务完成后、SUMMARY.md 创建前生成。
+
+---
+
+## Frontmatter 结构
+
+在 PLAN.md 中，`user_setup` 声明需要人工操作的配置:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "支付处理需要 API 密钥"
+    env_vars:
+      - name: STRIPE_SECRET_KEY
+        source: "Stripe 控制台 → Developers → API keys → Secret key"
+      - name: STRIPE_WEBHOOK_SECRET
+        source: "Stripe 控制台 → Developers → Webhooks → Signing secret"
+    dashboard_config:
+      - task: "创建 webhook 端点"
+        location: "Stripe 控制台 → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed, customer.subscription.*"
+    local_dev:
+      - "运行: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+      - "使用 CLI 输出的 webhook secret 进行本地测试"
+```
+
+---
+
+## 自动化优先原则
+
+**USER-SETUP.md 只包含 Claude 确实无法完成的操作。**
+
+| Claude 能做的（不在 USER-SETUP 中） | Claude 不能做的（→ USER-SETUP） |
+|--------------------------------------|--------------------------------|
+| `npm install stripe` | 创建 Stripe 账户 |
+| 编写 webhook 处理代码 | 从控制台获取 API 密钥 |
+| 创建 `.env.local` 文件结构 | 复制实际的密钥值 |
+| 运行 `stripe listen` | 认证 Stripe CLI (浏览器 OAuth) |
+| 配置 package.json | 访问外部服务控制台 |
+| 编写任何代码 | 从第三方系统获取密钥 |
+
+**判断标准:** "这是否需要人工在浏览器中操作，访问 Claude 没有凭据的账户？"
+- 是 → USER-SETUP.md
+- 否 → Claude 自动完成
+
+---
+
+## 服务示例
+
+<stripe_example>
+```markdown
+# 阶段 10: 需要用户设置
+
+**生成时间:** 2025-01-14
+**阶段:** 10-monetization
+**状态:** 未完成
+
+完成以下项目以使 Stripe 集成正常工作。
+
+## 环境变量
+
+| 状态 | 变量 | 来源 | 添加到 |
+|------|------|------|--------|
+| [ ] | `STRIPE_SECRET_KEY` | Stripe 控制台 → Developers → API keys → Secret key | `.env.local` |
+| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe 控制台 → Developers → API keys → Publishable key | `.env.local` |
+| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe 控制台 → Developers → Webhooks → [端点] → Signing secret | `.env.local` |
+
+## 账户设置
+
+- [ ] **创建 Stripe 账户** (如需要)
+  - URL: https://dashboard.stripe.com/register
+  - 跳过条件: 已有 Stripe 账户
+
+## 控制台配置
+
+- [ ] **创建 webhook 端点**
+  - 位置: Stripe 控制台 → Developers → Webhooks → Add endpoint
+  - 端点 URL: `https://[your-domain]/api/webhooks/stripe`
+  - 需要发送的事件:
+    - `checkout.session.completed`
+    - `customer.subscription.created`
+    - `customer.subscription.updated`
+    - `customer.subscription.deleted`
+
+- [ ] **创建产品和价格** (如使用订阅层级)
+  - 位置: Stripe 控制台 → Products → Add product
+  - 创建每个订阅层级
+  - 复制 Price ID 到:
+    - `STRIPE_STARTER_PRICE_ID`
+    - `STRIPE_PRO_PRICE_ID`
+
+## 本地开发
+
+本地 webhook 测试:
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+使用 CLI 输出的 webhook signing secret (以 `whsec_` 开头)。
+
+## 验证
+
+完成设置后:
+
+```bash
+# 检查环境变量已设置
+grep STRIPE .env.local
+
+# 验证构建通过
+npm run build
+
+# 测试 webhook 端点 (应返回 400 签名错误，而非 500 崩溃)
+curl -X POST http://localhost:3000/api/webhooks/stripe \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+预期: 构建通过，webhook 返回 400 (签名验证正常工作)。
+
+---
+
+**所有项目完成后:** 将文件顶部状态标记为 "已完成"。
+```
+</stripe_example>
+
+<supabase_example>
+```markdown
+# 阶段 2: 需要用户设置
+
+**生成时间:** 2025-01-14
+**阶段:** 02-authentication
+**状态:** 未完成
+
+完成以下项目以使 Supabase Auth 正常工作。
+
+## 环境变量
+
+| 状态 | 变量 | 来源 | 添加到 |
+|------|------|------|--------|
+| [ ] | `NEXT_PUBLIC_SUPABASE_URL` | Supabase 控制台 → Settings → API → Project URL | `.env.local` |
+| [ ] | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase 控制台 → Settings → API → anon public | `.env.local` |
+| [ ] | `SUPABASE_SERVICE_ROLE_KEY` | Supabase 控制台 → Settings → API → service_role | `.env.local` |
+
+## 账户设置
+
+- [ ] **创建 Supabase 项目**
+  - URL: https://supabase.com/dashboard/new
+  - 跳过条件: 已有此应用的项目
+
+## 控制台配置
+
+- [ ] **启用邮箱认证**
+  - 位置: Supabase 控制台 → Authentication → Providers
+  - 启用: Email provider
+  - 配置: 确认邮件 (根据偏好开启/关闭)
+
+- [ ] **配置 OAuth 提供商** (如使用社交登录)
+  - 位置: Supabase 控制台 → Authentication → Providers
+  - Google: 添加来自 Google Cloud Console 的 Client ID 和 Secret
+  - GitHub: 添加来自 GitHub OAuth Apps 的 Client ID 和 Secret
+
+## 验证
+
+完成设置后:
+
+```bash
+# 检查环境变量
+grep SUPABASE .env.local
+
+# 验证连接 (在项目目录中运行)
+npx supabase status
+```
+
+---
+
+**所有项目完成后:** 将文件顶部状态标记为 "已完成"。
+```
+</supabase_example>
+
+<sendgrid_example>
+```markdown
+# 阶段 5: 需要用户设置
+
+**生成时间:** 2025-01-14
+**阶段:** 05-notifications
+**状态:** 未完成
+
+完成以下项目以使 SendGrid 邮件正常工作。
+
+## 环境变量
+
+| 状态 | 变量 | 来源 | 添加到 |
+|------|------|------|--------|
+| [ ] | `SENDGRID_API_KEY` | SendGrid 控制台 → Settings → API Keys → Create API Key | `.env.local` |
+| [ ] | `SENDGRID_FROM_EMAIL` | 你的已验证发件人邮箱地址 | `.env.local` |
+
+## 账户设置
+
+- [ ] **创建 SendGrid 账户**
+  - URL: https://signup.sendgrid.com/
+  - 跳过条件: 已有账户
+
+## 控制台配置
+
+- [ ] **验证发件人身份**
+  - 位置: SendGrid 控制台 → Settings → Sender Authentication
+  - 选项 1: 单一发件人验证 (快速，适合开发)
+  - 选项 2: 域名认证 (生产环境)
+
+- [ ] **创建 API Key**
+  - 位置: SendGrid 控制台 → Settings → API Keys → Create API Key
+  - 权限: Restricted Access → Mail Send (Full Access)
+  - 立即复制密钥 (只显示一次)
+
+## 验证
+
+完成设置后:
+
+```bash
+# 检查环境变量
+grep SENDGRID .env.local
+
+# 测试邮件发送 (替换为你的测试邮箱)
+curl -X POST http://localhost:3000/api/test-email \
+  -H "Content-Type: application/json" \
+  -d '{"to": "your@email.com"}'
+```
+
+---
+
+**所有项目完成后:** 将文件顶部状态标记为 "已完成"。
+```
+</sendgrid_example>
+
+---
+
+## 指南
+
+**绝不包含:** 实际的密钥值。Claude 能自动化的步骤（包安装、代码修改）。
+
+**命名:** `{phase}-USER-SETUP.md` 匹配阶段编号模式。
+**状态追踪:** 用户勾选复选框并在完成后更新状态行。
+**可搜索性:** `grep -r "USER-SETUP" .planning/` 可找到所有需要用户操作的阶段。