specops 0.2.5 → 0.3.2

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>

package/.opencode/templates/codebase/conventions.md

@@ -0,0 +1,307 @@
+# 编码规范模板
+
+`.planning/codebase/CONVENTIONS.md` 的模板 - 记录编码风格和模式。
+
+**用途：** 记录本代码库中代码的编写方式。为 Claude 匹配现有风格提供规范性指南。
+
+---
+
+## 文件模板
+
+```markdown
+# 编码规范
+
+**分析日期：** [YYYY-MM-DD]
+
+## 命名模式
+
+**文件：**
+- [模式：例如 "所有文件使用 kebab-case"]
+- [测试文件：例如 "*.test.ts 与源文件并列"]
+- [组件：例如 "React 组件使用 PascalCase.tsx"]
+
+**函数：**
+- [模式：例如 "所有函数使用 camelCase"]
+- [异步：例如 "异步函数无特殊前缀"]
+- [处理器：例如 "事件处理器使用 handleEventName"]
+
+**变量：**
+- [模式：例如 "变量使用 camelCase"]
+- [常量：例如 "常量使用 UPPER_SNAKE_CASE"]
+- [私有：例如 "私有成员使用 _前缀" 或 "无前缀"]
+
+**类型：**
+- [接口：例如 "PascalCase，无 I 前缀"]
+- [类型：例如 "类型别名使用 PascalCase"]
+- [枚举：例如 "枚举名使用 PascalCase，值使用 UPPER_CASE"]
+
+## 代码风格
+
+**格式化：**
+- [工具：例如 "Prettier，配置在 .prettierrc"]
+- [行长度：例如 "最大 100 字符"]
+- [引号：例如 "字符串使用单引号"]
+- [分号：例如 "必须" 或 "省略"]
+
+**代码检查：**
+- [工具：例如 "ESLint，配置在 eslint.config.js"]
+- [规则：例如 "继承 airbnb-base，生产环境禁止 console"]
+- [运行：例如 "npm run lint"]
+
+## 导入组织
+
+**顺序：**
+1. [例如 "外部包（react、express 等）"]
+2. [例如 "内部模块（@/lib、@/components）"]
+3. [例如 "相对导入（.、..）"]
+4. [例如 "类型导入（import type {}）"]
+
+**分组：**
+- [空行：例如 "组之间空一行"]
+- [排序：例如 "每组内按字母排序"]
+
+**路径别名：**
+- [使用的别名：例如 "@/ 对应 src/、@components/ 对应 src/components/"]
+
+## 错误处理
+
+**模式：**
+- [策略：例如 "抛出错误，在边界处捕获"]
+- [自定义错误：例如 "继承 Error 类，命名为 *Error"]
+- [异步：例如 "使用 try/catch，不使用 .catch() 链"]
+
+**错误类型：**
+- [何时抛出：例如 "无效输入、缺少依赖"]
+- [何时返回：例如 "预期失败返回 Result<T, E>"]
+- [日志：例如 "抛出前记录带上下文的错误"]
+
+## 日志
+
+**框架：**
+- [工具：例如 "console.log、pino、winston"]
+- [级别：例如 "debug、info、warn、error"]
+
+**模式：**
+- [格式：例如 "带上下文对象的结构化日志"]
+- [何时：例如 "记录状态转换、外部调用"]
+- [何处：例如 "在服务边界记录，不在工具函数中"]
+
+## 注释
+
+**何时注释：**
+- [例如 "解释为什么，而非是什么"]
+- [例如 "记录业务逻辑、算法、边界情况"]
+- [例如 "避免显而易见的注释，如 // 计数器加一"]
+
+**JSDoc/TSDoc：**
+- [用法：例如 "公共 API 必须，内部可选"]
+- [格式：例如 "使用 @param、@returns、@throws 标签"]
+
+**TODO 注释：**
+- [模式：例如 "// TODO(username): 描述"]
+- [追踪：例如 "如有可用则链接到 issue 编号"]
+
+## 函数设计
+
+**大小：**
+- [例如 "保持在 50 行以内，提取辅助函数"]
+
+**参数：**
+- [例如 "最多 3 个参数，更多时使用对象"]
+- [例如 "在参数列表中解构对象"]
+
+**返回值：**
+- [例如 "显式返回，不使用隐式 undefined"]
+- [例如 "守卫子句提前返回"]
+
+## 模块设计
+
+**导出：**
+- [例如 "优先使用命名导出，React 组件使用默认导出"]
+- [例如 "从 index.ts 导出公共 API"]
+
+**桶文件：**
+- [例如 "使用 index.ts 重新导出公共 API"]
+- [例如 "避免循环依赖"]
+
+---
+
+*规范分析：[date]*
+*模式变更时更新*
+```
+
+<good_examples>
+```markdown
+# 编码规范
+
+**分析日期：** 2025-01-20
+
+## 命名模式
+
+**文件：**
+- 所有文件使用 kebab-case（command-handler.ts、user-service.ts）
+- *.test.ts 与源文件并列
+- index.ts 用于桶导出
+
+**函数：**
+- 所有函数使用 camelCase
+- 异步函数无特殊前缀
+- 事件处理器使用 handleEventName（handleClick、handleSubmit）
+
+**变量：**
+- 变量使用 camelCase
+- 常量使用 UPPER_SNAKE_CASE（MAX_RETRIES、API_BASE_URL）
+- 无下划线前缀（TypeScript 中无私有标记）
+
+**类型：**
+- 接口使用 PascalCase，无 I 前缀（User，而非 IUser）
+- 类型别名使用 PascalCase（UserConfig、ResponseData）
+- 枚举名使用 PascalCase，值使用 UPPER_CASE（Status.PENDING）
+
+## 代码风格
+
+**格式化：**
+- Prettier，配置在 .prettierrc
+- 100 字符行长度
+- 字符串使用单引号
+- 必须使用分号
+- 2 空格缩进
+
+**代码检查：**
+- ESLint，配置在 eslint.config.js
+- 继承 @typescript-eslint/recommended
+- 生产代码禁止 console.log（使用 logger）
+- 运行：npm run lint
+
+## 导入组织
+
+**顺序：**
+1. 外部包（react、express、commander）
+2. 内部模块（@/lib、@/services）
+3. 相对导入（./utils、../types）
+4. 类型导入（import type { User }）
+
+**分组：**
+- 组之间空一行
+- 每组内按字母排序
+- 类型导入在每组最后
+
+**路径别名：**
+- @/ 映射到 src/
+- 未定义其他别名
+
+## 错误处理
+
+**模式：**
+- 抛出错误，在边界处捕获（路由处理器、主函数）
+- 自定义错误继承 Error 类（ValidationError、NotFoundError）
+- 异步函数使用 try/catch，不使用 .catch() 链
+
+**错误类型：**
+- 无效输入、缺少依赖、不变量违反时抛出
+- 抛出前记录带上下文的错误：logger.error({ err, userId }, 'Failed to process')
+- 错误消息中包含原因：new Error('Failed to X', { cause: originalError })
+
+## 日志
+
+**框架：**
+- 从 lib/logger.ts 导出的 pino logger 实例
+- 级别：debug、info、warn、error（无 trace）
+
+**模式：**
+- 带上下文的结构化日志：logger.info({ userId, action }, 'User action')
+- 在服务边界记录，不在工具函数中
+- 记录状态转换、外部 API 调用、错误
+- 提交的代码中禁止 console.log
+
+## 注释
+
+**何时注释：**
+- 解释为什么，而非是什么：// 重试 3 次因为 API 有瞬时故障
+- 记录业务规则：// 用户必须在 24 小时内验证邮箱
+- 解释不明显的算法或变通方案
+- 避免显而易见的注释：// 将 count 设为 0
+
+**JSDoc/TSDoc：**
+- 公共 API 函数必须
+- 签名自解释的内部函数可选
+- 使用 @param、@returns、@throws 标签
+
+**TODO 注释：**
+- 格式：// TODO: 描述（无用户名，使用 git blame）
+- 如有 issue 则链接：// TODO: 修复竞态条件（issue #123）
+
+## 函数设计
+
+**大小：**
+- 保持在 50 行以内
+- 复杂逻辑提取辅助函数
+- 每个函数一个抽象层级
+
+**参数：**
+- 最多 3 个参数
+- 4+ 个参数使用选项对象：function create(options: CreateOptions)
+- 在参数列表中解构：function process({ id, name }: ProcessParams)
+
+**返回值：**
+- 显式 return 语句
+- 守卫子句提前返回
+- 预期失败使用 Result<T, E> 类型
+
+## 模块设计
+
+**导出：**
+- 优先使用命名导出
+- 仅 React 组件使用默认导出
+- 从 index.ts 桶文件导出公共 API
+
+**桶文件：**
+- index.ts 重新导出公共 API
+- 内部辅助函数保持私有（不从 index 导出）
+- 避免循环依赖（需要时从具体文件导入）
+
+---
+
+*规范分析：2025-01-20*
+*模式变更时更新*
+```
+</good_examples>
+
+<guidelines>
+**CONVENTIONS.md 中应包含的内容：**
+- 代码库中观察到的命名模式
+- 格式化规则（Prettier 配置、代码检查规则）
+- 导入组织模式
+- 错误处理策略
+- 日志方法
+- 注释规范
+- 函数和模块设计模式
+
+**不应包含的内容：**
+- 架构决策（那是 ARCHITECTURE.md 的内容）
+- 技术选型（那是 STACK.md 的内容）
+- 测试模式（那是 TESTING.md 的内容）
+- 文件组织（那是 STRUCTURE.md 的内容）
+
+**填写此模板时：**
+- 检查 .prettierrc、.eslintrc 或类似配置文件
+- 检查 5-10 个代表性源文件的模式
+- 寻找一致性：如果 80%+ 遵循某个模式，就记录它
+- 使用规范性语言："使用 X" 而非 "有时使用 Y"
+- 记录偏差："遗留代码使用 Y，新代码应使用 X"
+- 总计保持在约 150 行以内
+
+**在阶段规划中的用途：**
+- 编写新代码时（匹配现有风格）
+- 添加功能时（遵循命名模式）
+- 重构时（应用一致的规范）
+- 代码审查时（对照记录的模式检查）
+- 入门时（了解风格期望）
+
+**分析方法：**
+- 扫描 src/ 目录了解文件命名模式
+- 检查 package.json scripts 中的 lint/format 命令
+- 阅读 5-10 个文件识别函数命名、错误处理
+- 查找配置文件（.prettierrc、eslint.config.js）
+- 记录导入、注释、函数签名中的模式
+</guidelines>