specops 0.2.4 → 0.3.0

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>

package/.opencode/templates/codebase/integrations.md

@@ -0,0 +1,280 @@
+# 外部集成模板
+
+`.planning/codebase/INTEGRATIONS.md` 的模板 - 记录外部服务依赖。
+
+**用途：** 记录本代码库与哪些外部系统通信。聚焦于"我们代码之外依赖的东西"。
+
+---
+
+## 文件模板
+
+```markdown
+# 外部集成
+
+**分析日期：** [YYYY-MM-DD]
+
+## API 与外部服务
+
+**支付处理：**
+- [服务] - [用途：例如 "订阅计费、一次性支付"]
+  - SDK/客户端：[例如 "stripe npm 包 v14.x"]
+  - 认证：[例如 "STRIPE_SECRET_KEY 环境变量中的 API 密钥"]
+  - 使用的端点：[例如 "checkout sessions、webhooks"]
+
+**邮件/短信：**
+- [服务] - [用途：例如 "事务性邮件"]
+  - SDK/客户端：[例如 "sendgrid/mail v8.x"]
+  - 认证：[例如 "SENDGRID_API_KEY 环境变量中的 API 密钥"]
+  - 模板：[例如 "在 SendGrid 仪表板中管理"]
+
+**外部 API：**
+- [服务] - [用途]
+  - 集成方式：[例如 "通过 fetch 的 REST API"、"GraphQL 客户端"]
+  - 认证：[例如 "AUTH_TOKEN 环境变量中的 OAuth2 令牌"]
+  - 速率限制：[如适用]
+
+## 数据存储
+
+**数据库：**
+- [类型/提供商] - [例如 "Supabase 上的 PostgreSQL"]
+  - 连接：[例如 "通过 DATABASE_URL 环境变量"]
+  - 客户端：[例如 "Prisma ORM v5.x"]
+  - 迁移：[例如 "migrations/ 中的 prisma migrate"]
+
+**文件存储：**
+- [服务] - [例如 "AWS S3 用于用户上传"]
+  - SDK/客户端：[例如 "@aws-sdk/client-s3"]
+  - 认证：[例如 "AWS_* 环境变量中的 IAM 凭证"]
+  - 存储桶：[例如 "prod-uploads、dev-uploads"]
+
+**缓存：**
+- [服务] - [例如 "Redis 用于会话存储"]
+  - 连接：[例如 "REDIS_URL 环境变量"]
+  - 客户端：[例如 "ioredis v5.x"]
+
+## 认证与身份
+
+**认证提供商：**
+- [服务] - [例如 "Supabase Auth"、"Auth0"、"自定义 JWT"]
+  - 实现：[例如 "Supabase 客户端 SDK"]
+  - 令牌存储：[例如 "httpOnly cookies"、"localStorage"]
+  - 会话管理：[例如 "JWT 刷新令牌"]
+
+**OAuth 集成：**
+- [提供商] - [例如 "Google OAuth 用于登录"]
+  - 凭证：[例如 "GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET"]
+  - 作用域：[例如 "email、profile"]
+
+## 监控与可观测性
+
+**错误追踪：**
+- [服务] - [例如 "Sentry"]
+  - DSN：[例如 "SENTRY_DSN 环境变量"]
+  - 版本追踪：[例如 "通过 SENTRY_RELEASE"]
+
+**分析：**
+- [服务] - [例如 "Mixpanel 用于产品分析"]
+  - 令牌：[例如 "MIXPANEL_TOKEN 环境变量"]
+  - 追踪的事件：[例如 "用户操作、页面浏览"]
+
+**日志：**
+- [服务] - [例如 "CloudWatch"、"Datadog"、"无（仅 stdout）"]
+  - 集成：[例如 "AWS Lambda 内置"]
+
+## CI/CD 与部署
+
+**托管：**
+- [平台] - [例如 "Vercel"、"AWS Lambda"、"ECS 上的 Docker"]
+  - 部署：[例如 "main 分支推送时自动部署"]
+  - 环境变量：[例如 "在 Vercel 仪表板中配置"]
+
+**CI 流水线：**
+- [服务] - [例如 "GitHub Actions"]
+  - 工作流：[例如 "test.yml、deploy.yml"]
+  - 密钥：[例如 "存储在 GitHub 仓库密钥中"]
+
+## 环境配置
+
+**开发环境：**
+- 必需环境变量：[列出关键变量]
+- 密钥位置：[例如 ".env.local（已 gitignore）"、"1Password 保险库"]
+- Mock/桩服务：[例如 "Stripe 测试模式"、"本地 PostgreSQL"]
+
+**预发布环境：**
+- 环境特定差异：[例如 "使用预发布 Stripe 账户"]
+- 数据：[例如 "独立的预发布数据库"]
+
+**生产环境：**
+- 密钥管理：[例如 "Vercel 环境变量"]
+- 故障转移/冗余：[例如 "多区域数据库复制"]
+
+## Webhook 与回调
+
+**入站：**
+- [服务] - [端点：例如 "/api/webhooks/stripe"]
+  - 验证：[例如 "通过 stripe.webhooks.constructEvent 进行签名验证"]
+  - 事件：[例如 "payment_intent.succeeded、customer.subscription.updated"]
+
+**出站：**
+- [服务] - [触发条件]
+  - 端点：[例如 "用户注册时的外部 CRM webhook"]
+  - 重试逻辑：[如适用]
+
+---
+
+*集成审计：[date]*
+*添加/移除外部服务时更新*
+```
+
+<good_examples>
+```markdown
+# 外部集成
+
+**分析日期：** 2025-01-20
+
+## API 与外部服务
+
+**支付处理：**
+- Stripe - 订阅计费和一次性课程支付
+  - SDK/客户端：stripe npm 包 v14.8
+  - 认证：STRIPE_SECRET_KEY 环境变量中的 API 密钥
+  - 使用的端点：checkout sessions、customer portal、webhooks
+
+**邮件/短信：**
+- SendGrid - 事务性邮件（收据、密码重置）
+  - SDK/客户端：@sendgrid/mail v8.1
+  - 认证：SENDGRID_API_KEY 环境变量中的 API 密钥
+  - 模板：在 SendGrid 仪表板中管理（模板 ID 在代码中）
+
+**外部 API：**
+- OpenAI API - 课程内容生成
+  - 集成方式：通过 openai npm 包 v4.x 的 REST API
+  - 认证：OPENAI_API_KEY 环境变量中的 Bearer 令牌
+  - 速率限制：3500 请求/分钟（tier 3）
+
+## 数据存储
+
+**数据库：**
+- Supabase 上的 PostgreSQL - 主数据存储
+  - 连接：通过 DATABASE_URL 环境变量
+  - 客户端：Prisma ORM v5.8
+  - 迁移：prisma/migrations/ 中的 prisma migrate
+
+**文件存储：**
+- Supabase Storage - 用户上传（头像、课程材料）
+  - SDK/客户端：@supabase/supabase-js v2.x
+  - 认证：SUPABASE_SERVICE_ROLE_KEY 中的服务角色密钥
+  - 存储桶：avatars（公开）、course-materials（私有）
+
+**缓存：**
+- 当前无（所有数据库查询，无 Redis）
+
+## 认证与身份
+
+**认证提供商：**
+- Supabase Auth - 邮箱/密码 + OAuth
+  - 实现：Supabase 客户端 SDK，服务端会话管理
+  - 令牌存储：通过 @supabase/ssr 的 httpOnly cookies
+  - 会话管理：Supabase 处理的 JWT 刷新令牌
+
+**OAuth 集成：**
+- Google OAuth - 社交登录
+  - 凭证：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET（Supabase 仪表板）
+  - 作用域：email、profile
+
+## 监控与可观测性
+
+**错误追踪：**
+- Sentry - 服务端和客户端错误
+  - DSN：SENTRY_DSN 环境变量
+  - 版本追踪：通过 SENTRY_RELEASE 的 Git commit SHA
+
+**分析：**
+- 无（计划中：Mixpanel）
+
+**日志：**
+- Vercel 日志 - 仅 stdout/stderr
+  - 保留期：Pro 计划 7 天
+
+## CI/CD 与部署
+
+**托管：**
+- Vercel - Next.js 应用托管
+  - 部署：main 分支推送时自动部署
+  - 环境变量：在 Vercel 仪表板中配置（同步到 .env.example）
+
+**CI 流水线：**
+- GitHub Actions - 测试和类型检查
+  - 工作流：.github/workflows/ci.yml
+  - 密钥：不需要（仅公开仓库测试）
+
+## 环境配置
+
+**开发环境：**
+- 必需环境变量：DATABASE_URL、NEXT_PUBLIC_SUPABASE_URL、NEXT_PUBLIC_SUPABASE_ANON_KEY
+- 密钥位置：.env.local（已 gitignore），团队通过 1Password 保险库共享
+- Mock/桩服务：Stripe 测试模式、Supabase 本地开发项目
+
+**预发布环境：**
+- 使用独立的 Supabase 预发布项目
+- Stripe 测试模式
+- 同一 Vercel 账户，不同环境
+
+**生产环境：**
+- 密钥管理：Vercel 环境变量
+- 数据库：Supabase 生产项目，每日备份
+
+## Webhook 与回调
+
+**入站：**
+- Stripe - /api/webhooks/stripe
+  - 验证：通过 stripe.webhooks.constructEvent 进行签名验证
+  - 事件：payment_intent.succeeded、customer.subscription.updated、customer.subscription.deleted
+
+**出站：**
+- 无
+
+---
+
+*集成审计：2025-01-20*
+*添加/移除外部服务时更新*
+```
+</good_examples>
+
+<guidelines>
+**INTEGRATIONS.md 中应包含的内容：**
+- 代码通信的外部服务
+- 认证模式（密钥存放位置，而非密钥本身）
+- 使用的 SDK 和客户端库
+- 环境变量名称（而非值）
+- Webhook 端点和验证方法
+- 数据库连接模式
+- 文件存储位置
+- 监控和日志服务
+
+**不应包含的内容：**
+- 实际 API 密钥或密钥（绝对不要写入）
+- 内部架构（那是 ARCHITECTURE.md 的内容）
+- 代码模式（那是 PATTERNS.md 的内容）
+- 技术选型（那是 STACK.md 的内容）
+- 性能问题（那是 CONCERNS.md 的内容）
+
+**填写此模板时：**
+- 检查 .env.example 或 .env.template 中的必需环境变量
+- 查找 SDK 导入（stripe、@sendgrid/mail 等）
+- 检查路由/端点中的 webhook 处理器
+- 记录密钥管理位置（而非密钥本身）
+- 记录环境特定差异（开发/预发布/生产）
+- 包含每个服务的认证模式
+
+**在阶段规划中的用途：**
+- 添加新的外部服务集成
+- 调试认证问题
+- 了解应用外部的数据流
+- 搭建新环境
+- 审计第三方依赖
+- 规划服务中断或迁移
+
+**安全提示：**
+记录密钥存放在哪里（环境变量、Vercel 仪表板、1Password），绝不记录密钥是什么。
+</guidelines>