specops 0.2.4 → 0.3.0

package/.opencode/templates/codebase/architecture.md

@@ -0,0 +1,255 @@
+# 架构模板
+
+`.planning/codebase/ARCHITECTURE.md` 的模板 - 记录概念层面的代码组织。
+
+**用途：** 记录代码在概念层面的组织方式。与 STRUCTURE.md（展示物理文件位置）互补。
+
+---
+
+## 文件模板
+
+```markdown
+# 架构
+
+**分析日期：** [YYYY-MM-DD]
+
+## 模式概览
+
+**整体：** [模式名称：例如 "单体 CLI"、"Serverless API"、"全栈 MVC"]
+
+**关键特征：**
+- [特征 1：例如 "单一可执行文件"]
+- [特征 2：例如 "无状态请求处理"]
+- [特征 3：例如 "事件驱动"]
+
+## 分层
+
+[描述概念层及其职责]
+
+**[层名称]：**
+- 用途：[这一层做什么]
+- 包含：[代码类型：例如 "路由处理器"、"业务逻辑"]
+- 依赖：[使用什么：例如 "仅数据层"]
+- 被使用：[什么使用它：例如 "API 路由"]
+
+**[层名称]：**
+- 用途：[这一层做什么]
+- 包含：[代码类型]
+- 依赖：[使用什么]
+- 被使用：[什么使用它]
+
+## 数据流
+
+[描述典型的请求/执行生命周期]
+
+**[流程名称]（例如 "HTTP 请求"、"CLI 命令"、"事件处理"）：**
+
+1. [入口点：例如 "用户运行命令"]
+2. [处理步骤：例如 "路由器匹配路径"]
+3. [处理步骤：例如 "控制器验证输入"]
+4. [处理步骤：例如 "服务执行逻辑"]
+5. [输出：例如 "返回响应"]
+
+**状态管理：**
+- [状态如何处理：例如 "无状态 - 无持久状态"、"每请求数据库"、"内存缓存"]
+
+## 关键抽象
+
+[整个代码库中使用的核心概念/模式]
+
+**[抽象名称]：**
+- 用途：[它代表什么]
+- 示例：[例如 "UserService、ProjectService"]
+- 模式：[例如 "单例"、"工厂"、"仓储"]
+
+**[抽象名称]：**
+- 用途：[它代表什么]
+- 示例：[具体示例]
+- 模式：[使用的模式]
+
+## 入口点
+
+[执行从哪里开始]
+
+**[入口点]：**
+- 位置：[简述：例如 "src/index.ts"、"API Gateway 触发"]
+- 触发方式：[什么调用它：例如 "CLI 调用"、"HTTP 请求"]
+- 职责：[它做什么：例如 "解析参数，路由到命令"]
+
+## 错误处理
+
+**策略：** [错误如何处理：例如 "异常冒泡到顶层处理器"、"每路由错误中间件"]
+
+**模式：**
+- [模式：例如 "在控制器层 try/catch"]
+- [模式：例如 "向用户返回错误码"]
+
+## 横切关注点
+
+[影响多个层的方面]
+
+**日志：**
+- [方法：例如 "Winston logger，每请求注入"]
+
+**验证：**
+- [方法：例如 "API 边界使用 Zod schema"]
+
+**认证：**
+- [方法：例如 "受保护路由使用 JWT 中间件"]
+
+---
+
+*架构分析：[date]*
+*主要模式变更时更新*
+```
+
+<good_examples>
+```markdown
+# 架构
+
+**分析日期：** 2025-01-20
+
+## 模式概览
+
+**整体：** 带插件系统的 CLI 应用
+
+**关键特征：**
+- 带子命令的单一可执行文件
+- 基于插件的可扩展性
+- 基于文件的状态（无数据库）
+- 同步执行模型
+
+## 分层
+
+**命令层：**
+- 用途：解析用户输入并路由到适当的处理器
+- 包含：命令定义、参数解析、帮助文本
+- 位置：`src/commands/*.ts`
+- 依赖：服务层提供业务逻辑
+- 被使用：CLI 入口点（`src/index.ts`）
+
+**服务层：**
+- 用途：核心业务逻辑
+- 包含：FileService、TemplateService、InstallService
+- 位置：`src/services/*.ts`
+- 依赖：文件系统工具、外部工具
+- 被使用：命令处理器
+
+**工具层：**
+- 用途：共享辅助函数和抽象
+- 包含：文件 I/O 封装、路径解析、字符串格式化
+- 位置：`src/utils/*.ts`
+- 依赖：仅 Node.js 内置模块
+- 被使用：服务层
+
+## 数据流
+
+**CLI 命令执行：**
+
+1. 用户运行：`specops new-project`
+2. Commander 解析参数和标志
+3. 调用命令处理器（`src/commands/new-project.ts`）
+4. 处理器调用服务方法（`src/services/project.ts` → `create()`）
+5. 服务读取模板、处理文件、写入输出
+6. 结果输出到控制台
+7. 进程以状态码退出
+
+**状态管理：**
+- 基于文件：所有状态存放在 `.planning/` 目录
+- 无持久内存状态
+- 每次命令执行独立
+
+## 关键抽象
+
+**Service：**
+- 用途：封装某个领域的业务逻辑
+- 示例：`src/services/file.ts`、`src/services/template.ts`、`src/services/project.ts`
+- 模式：类单例（作为模块导入，不实例化）
+
+**Command：**
+- 用途：CLI 命令定义
+- 示例：`src/commands/new-project.ts`、`src/commands/plan-phase.ts`
+- 模式：Commander.js 命令注册
+
+**Template：**
+- 用途：可复用的文档结构
+- 示例：PROJECT.md、PLAN.md 模板
+- 模式：带替换变量的 Markdown 文件
+
+## 入口点
+
+**CLI 入口：**
+- 位置：`src/index.ts`
+- 触发方式：用户运行 `specops <command>`
+- 职责：注册命令、解析参数、显示帮助
+
+**命令：**
+- 位置：`src/commands/*.ts`
+- 触发方式：CLI 匹配的命令
+- 职责：验证输入、调用服务、格式化输出
+
+## 错误处理
+
+**策略：** 抛出异常，在命令层捕获，记录日志并退出
+
+**模式：**
+- 服务抛出带描述性消息的 Error
+- 命令处理器捕获，将错误输出到 stderr，exit(1)
+- 验证错误在执行前显示（快速失败）
+
+## 横切关注点
+
+**日志：**
+- Console.log 用于正常输出
+- Console.error 用于错误
+- Chalk 用于彩色输出
+
+**验证：**
+- Zod schema 用于配置文件解析
+- 命令处理器中的手动验证
+- 无效输入时快速失败
+
+**文件操作：**
+- FileService 对 fs-extra 的抽象
+- 所有路径在操作前验证
+- 原子写入（临时文件 + 重命名）
+
+---
+
+*架构分析：2025-01-20*
+*主要模式变更时更新*
+```
+</good_examples>
+
+<guidelines>
+**ARCHITECTURE.md 中应包含的内容：**
+- 整体架构模式（单体、微服务、分层等）
+- 概念层及其关系
+- 数据流/请求生命周期
+- 关键抽象和模式
+- 入口点
+- 错误处理策略
+- 横切关注点（日志、认证、验证）
+
+**不应包含的内容：**
+- 详尽的文件列表（那是 STRUCTURE.md 的内容）
+- 技术选型（那是 STACK.md 的内容）
+- 逐行代码走读（参考代码阅读）
+- 特定功能的实现细节
+
+**欢迎包含文件路径：**
+包含文件路径作为抽象的具体示例。使用反引号格式：`src/services/user.ts`。这使架构文档在 Claude 规划时可操作。
+
+**填写此模板时：**
+- 阅读主入口点（index、server、main）
+- 通过阅读导入/依赖识别分层
+- 追踪典型的请求/命令执行流程
+- 记录反复出现的模式（services、controllers、repositories）
+- 保持描述在概念层面，而非机械层面
+
+**在阶段规划中的用途：**
+- 添加新功能时（它适合哪一层？）
+- 重构时（了解当前模式）
+- 识别代码放置位置（哪一层处理 X？）
+- 了解组件之间的依赖关系
+</guidelines>

package/.opencode/templates/codebase/concerns.md

@@ -0,0 +1,310 @@
+# 代码库关注点模板
+
+`.planning/codebase/CONCERNS.md` 的模板 - 记录已知问题和需要注意的区域。
+
+**用途：** 提供关于代码库的可操作警告。聚焦于"修改代码时需要注意什么"。
+
+---
+
+## 文件模板
+
+```markdown
+# 代码库关注点
+
+**分析日期：** [YYYY-MM-DD]
+
+## 技术债务
+
+**[区域/组件]：**
+- 问题：[什么是捷径/变通方案]
+- 原因：[为什么这样做]
+- 影响：[因此什么会出问题或退化]
+- 修复方案：[如何正确解决]
+
+**[区域/组件]：**
+- 问题：[什么是捷径/变通方案]
+- 原因：[为什么这样做]
+- 影响：[因此什么会出问题或退化]
+- 修复方案：[如何正确解决]
+
+## 已知 Bug
+
+**[Bug 描述]：**
+- 症状：[发生了什么]
+- 触发条件：[如何复现]
+- 变通方案：[临时缓解措施（如有）]
+- 根因：[如果已知]
+- 阻塞于：[如果在等待某些东西]
+
+**[Bug 描述]：**
+- 症状：[发生了什么]
+- 触发条件：[如何复现]
+- 变通方案：[临时缓解措施（如有）]
+- 根因：[如果已知]
+
+## 安全考虑
+
+**[需要安全关注的区域]：**
+- 风险：[可能出什么问题]
+- 当前缓解措施：[目前有什么保护]
+- 建议：[应该添加什么]
+
+**[需要安全关注的区域]：**
+- 风险：[可能出什么问题]
+- 当前缓解措施：[目前有什么保护]
+- 建议：[应该添加什么]
+
+## 性能瓶颈
+
+**[慢操作/端点]：**
+- 问题：[什么慢]
+- 测量值：[实际数据："500ms p95"、"2s 加载时间"]
+- 原因：[为什么慢]
+- 改进路径：[如何加速]
+
+**[慢操作/端点]：**
+- 问题：[什么慢]
+- 测量值：[实际数据]
+- 原因：[为什么慢]
+- 改进路径：[如何加速]
+
+## 脆弱区域
+
+**[组件/模块]：**
+- 脆弱原因：[什么使它容易出问题]
+- 常见故障：[通常会出什么问题]
+- 安全修改方式：[如何修改而不破坏]
+- 测试覆盖：[是否有测试？有什么缺口？]
+
+**[组件/模块]：**
+- 脆弱原因：[什么使它容易出问题]
+- 常见故障：[通常会出什么问题]
+- 安全修改方式：[如何修改而不破坏]
+- 测试覆盖：[是否有测试？有什么缺口？]
+
+## 扩展限制
+
+**[资源/系统]：**
+- 当前容量：[数据："100 req/sec"、"10k 用户"]
+- 极限：[在哪里会崩溃]
+- 达到极限时的症状：[会发生什么]
+- 扩展路径：[如何增加容量]
+
+## 有风险的依赖
+
+**[包/服务]：**
+- 风险：[例如 "已弃用"、"无人维护"、"即将有破坏性变更"]
+- 影响：[如果它失败会破坏什么]
+- 迁移计划：[替代方案或升级路径]
+
+## 缺失的关键功能
+
+**[功能缺口]：**
+- 问题：[缺少什么]
+- 当前变通方案：[用户如何应对]
+- 阻塞：[没有它什么无法完成]
+- 实现复杂度：[粗略工作量估计]
+
+## 测试覆盖缺口
+
+**[未测试区域]：**
+- 未测试内容：[具体功能]
+- 风险：[什么可能在不知不觉中出问题]
+- 优先级：[高/中/低]
+- 测试难度：[为什么还没有测试]
+
+---
+
+*关注点审计：[date]*
+*问题修复或发现新问题时更新*
+```
+
+<good_examples>
+```markdown
+# 代码库关注点
+
+**分析日期：** 2025-01-20
+
+## 技术债务
+
+**React 组件中的数据库查询：**
+- 问题：15+ 个页面组件中直接使用 Supabase 查询，而非 server actions
+- 文件：`app/dashboard/page.tsx`、`app/profile/page.tsx`、`app/courses/[id]/page.tsx`、`app/settings/page.tsx`（以及 `app/` 中的另外 11 个）
+- 原因：MVP 阶段的快速原型开发
+- 影响：无法正确实现 RLS，向客户端暴露数据库结构
+- 修复方案：将所有查询移至 `app/actions/` 中的 server actions，添加适当的 RLS 策略
+
+**手动 webhook 签名验证：**
+- 问题：3 个不同端点中复制粘贴的 Stripe webhook 验证代码
+- 文件：`app/api/webhooks/stripe/route.ts`、`app/api/webhooks/checkout/route.ts`、`app/api/webhooks/subscription/route.ts`
+- 原因：每个 webhook 都是临时添加的，没有抽象
+- 影响：新 webhook 容易遗漏验证（安全风险）
+- 修复方案：创建共享的 `lib/stripe/validate-webhook.ts` 中间件
+
+## 已知 Bug
+
+**订阅更新的竞态条件：**
+- 症状：成功支付后用户显示为"免费"层级 5-10 秒
+- 触发条件：Stripe 结账重定向后快速导航，webhook 处理之前
+- 文件：`app/checkout/success/page.tsx`（重定向处理器）、`app/api/webhooks/stripe/route.ts`（webhook）
+- 变通方案：Stripe webhook 最终会更新状态（自愈）
+- 根因：Webhook 处理比用户导航慢，没有乐观 UI 更新
+- 修复：在 `app/checkout/success/page.tsx` 中重定向后添加轮询
+
+**登出后会话状态不一致：**
+- 症状：登出后用户被重定向到 /dashboard 而非 /login
+- 触发条件：通过移动端导航按钮登出（桌面端正常）
+- 文件：`components/MobileNav.tsx`（约第 45 行，登出处理器）
+- 变通方案：手动导航到 /login 可以正常工作
+- 根因：移动端导航组件没有 await supabase.auth.signOut()
+- 修复：在 `components/MobileNav.tsx` 的登出处理器中添加 await
+
+## 安全考虑
+
+**管理员角色仅在客户端检查：**
+- 风险：管理员仪表板页面从 Supabase 客户端检查 isAdmin，没有服务端验证
+- 文件：`app/admin/page.tsx`、`app/admin/users/page.tsx`、`components/AdminGuard.tsx`
+- 当前缓解措施：无（依赖 UI 隐藏）
+- 建议：在 `middleware.ts` 中为管理员路由添加中间件，服务端验证角色
+
+**未验证的文件上传：**
+- 风险：用户可以上传任何文件类型到头像存储桶（无大小/类型验证）
+- 文件：`components/AvatarUpload.tsx`（上传处理器）
+- 当前缓解措施：Supabase 存储桶限制为 2MB（在仪表板中配置）
+- 建议：在 `lib/storage/validate.ts` 中添加文件类型验证（仅 image/*）
+
+## 性能瓶颈
+
+**/api/courses 端点：**
+- 问题：获取所有课程及嵌套的课时和作者
+- 文件：`app/api/courses/route.ts`
+- 测量值：50+ 课程时 p95 响应时间 1.2s
+- 原因：N+1 查询模式（每个课程单独查询课时）
+- 改进路径：在 `lib/db/courses.ts` 中使用 Prisma include 预加载课时，添加 Redis 缓存
+
+**仪表板初始加载：**
+- 问题：挂载时 5 个串行 API 调用的瀑布流
+- 文件：`app/dashboard/page.tsx`
+- 测量值：慢速 3G 下 3.5s 才可交互
+- 原因：每个组件独立获取自己的数据
+- 改进路径：转换为 Server Component，使用单次并行获取
+
+## 脆弱区域
+
+**认证中间件链：**
+- 文件：`middleware.ts`
+- 脆弱原因：4 个不同的中间件函数按特定顺序运行（auth -> role -> subscription -> logging）
+- 常见故障：中间件顺序变更会破坏一切，难以调试
+- 安全修改方式：修改顺序前添加测试，在注释中记录依赖关系
+- 测试覆盖：中间件链无集成测试（仅有单元测试）
+
+**Stripe webhook 事件处理：**
+- 文件：`app/api/webhooks/stripe/route.ts`
+- 脆弱原因：包含 12 种事件类型的巨大 switch 语句，共享事务逻辑
+- 常见故障：添加新事件类型时未处理，错误时部分数据库更新
+- 安全修改方式：将每个事件处理器提取到 `lib/stripe/handlers/*.ts`
+- 测试覆盖：12 种事件类型中仅 3 种有测试
+
+## 扩展限制
+
+**Supabase 免费层级：**
+- 当前容量：500MB 数据库、1GB 文件存储、2GB 带宽/月
+- 极限：预计约 5000 用户后达到限制
+- 达到极限时的症状：429 速率限制错误，数据库写入失败
+- 扩展路径：升级到 Pro（$25/月）扩展到 8GB 数据库、100GB 存储
+
+**服务端渲染阻塞：**
+- 当前容量：约 50 个并发用户后开始变慢
+- 极限：Vercel Hobby 计划（10s 函数超时，100GB-hrs/月）
+- 达到极限时的症状：课程页面 504 网关超时
+- 扩展路径：升级到 Vercel Pro（$20/月），添加边缘缓存
+
+## 有风险的依赖
+
+**react-hot-toast：**
+- 风险：无人维护（最后更新 18 个月前），React 19 兼容性未知
+- 影响：Toast 通知失效，无优雅降级
+- 迁移计划：切换到 sonner（积极维护，类似 API）
+
+## 缺失的关键功能
+
+**支付失败处理：**
+- 问题：订阅支付失败时没有重试机制或用户通知
+- 当前变通方案：用户手动重新输入支付信息（如果他们注意到的话）
+- 阻塞：无法留住过期卡片的用户，没有催款流程
+- 实现复杂度：中等（Stripe webhooks + 邮件流程 + UI）
+
+**课程进度跟踪：**
+- 问题：没有持久化状态记录已完成的课时
+- 当前变通方案：用户手动跟踪进度
+- 阻塞：无法显示完成百分比，无法推荐下一课时
+- 实现复杂度：低（添加 completed_lessons 关联表）
+
+## 测试覆盖缺口
+
+**支付流程端到端：**
+- 未测试内容：完整的 Stripe 结账 -> webhook -> 订阅激活流程
+- 风险：支付处理可能静默失败（已发生过两次）
+- 优先级：高
+- 测试难度：需要 Stripe 测试固定数据和 webhook 模拟设置
+
+**错误边界行为：**
+- 未测试内容：组件抛出错误时应用的行为
+- 风险：用户看到白屏，没有错误报告
+- 优先级：中
+- 测试难度：需要在测试环境中故意触发错误
+
+---
+
+*关注点审计：2025-01-20*
+*问题修复或发现新问题时更新*
+```
+</good_examples>
+
+<guidelines>
+**CONCERNS.md 中应包含的内容：**
+- 有明确影响和修复方案的技术债务
+- 有复现步骤的已知 bug
+- 安全缺口和缓解建议
+- 有测量数据的性能瓶颈
+- 容易出问题的脆弱代码
+- 有数据的扩展限制
+- 需要关注的依赖
+- 阻塞工作流的缺失功能
+- 测试覆盖缺口
+
+**不应包含的内容：**
+- 没有证据的观点（"代码很乱"）
+- 没有解决方案的抱怨（"认证很烂"）
+- 未来功能想法（那是产品规划的内容）
+- 普通 TODO（那些放在代码注释中）
+- 运行良好的架构决策
+- 次要代码风格问题
+
+**填写此模板时：**
+- **始终包含文件路径** - 没有位置的关注点不可操作。使用反引号：`src/file.ts`
+- 测量值要具体（"500ms p95" 而非 "慢"）
+- 包含 bug 的复现步骤
+- 建议修复方案，而不仅仅是问题
+- 聚焦可操作的项目
+- 按风险/影响排列优先级
+- 问题解决后更新
+- 发现新问题时添加
+
+**语气指南：**
+- 专业，不情绪化（"N+1 查询模式" 而非 "糟糕的查询"）
+- 面向解决方案（"修复：添加索引" 而非 "需要修复"）
+- 聚焦风险（"可能暴露用户数据" 而非 "安全很差"）
+- 基于事实（"3.5s 加载时间" 而非 "非常慢"）
+
+**在阶段规划中的用途：**
+- 决定下一步做什么
+- 评估变更风险
+- 了解哪里需要小心
+- 确定改进优先级
+- 为新的 Claude 上下文提供入门信息
+- 规划重构工作
+
+**如何填充：**
+探索代理在代码库映射期间检测这些问题。欢迎手动添加人工发现的问题。这是活文档，不是抱怨清单。
+</guidelines>