specops 0.2.5 → 0.3.2

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>

package/.opencode/templates/codebase/stack.md

@@ -0,0 +1,186 @@
+# 技术栈模板
+
+`.planning/codebase/STACK.md` 的模板 - 记录技术基础。
+
+**用途：** 记录本代码库运行的技术。聚焦于"运行代码时执行的是什么"。
+
+---
+
+## 文件模板
+
+```markdown
+# 技术栈
+
+**分析日期：** [YYYY-MM-DD]
+
+## 语言
+
+**主要：**
+- [语言] [版本] - [使用场景：例如 "所有应用代码"]
+
+**次要：**
+- [语言] [版本] - [使用场景：例如 "构建脚本、工具"]
+
+## 运行时
+
+**环境：**
+- [运行时] [版本] - [例如 "Node.js 20.x"]
+- [其他要求（如有）]
+
+**包管理器：**
+- [管理器] [版本] - [例如 "npm 10.x"]
+- 锁文件：[例如 "存在 package-lock.json"]
+
+## 框架
+
+**核心：**
+- [框架] [版本] - [用途：例如 "Web 服务器"、"UI 框架"]
+
+**测试：**
+- [框架] [版本] - [例如 "Jest 用于单元测试"]
+- [框架] [版本] - [例如 "Playwright 用于端到端测试"]
+
+**构建/开发：**
+- [工具] [版本] - [例如 "Vite 用于打包"]
+- [工具] [版本] - [例如 "TypeScript 编译器"]
+
+## 关键依赖
+
+[仅包含对理解技术栈至关重要的依赖 - 限制在 5-10 个最重要的]
+
+**核心：**
+- [包] [版本] - [重要原因：例如 "认证"、"数据库访问"]
+- [包] [版本] - [重要原因]
+
+**基础设施：**
+- [包] [版本] - [例如 "Express 用于 HTTP 路由"]
+- [包] [版本] - [例如 "PostgreSQL 客户端"]
+
+## 配置
+
+**环境：**
+- [配置方式：例如 ".env 文件"、"环境变量"]
+- [关键配置：例如 "需要 DATABASE_URL、API_KEY"]
+
+**构建：**
+- [构建配置文件：例如 "vite.config.ts、tsconfig.json"]
+
+## 平台要求
+
+**开发：**
+- [操作系统要求或"任何平台"]
+- [额外工具：例如 "Docker 用于本地数据库"]
+
+**生产：**
+- [部署目标：例如 "Vercel"、"AWS Lambda"、"Docker 容器"]
+- [版本要求]
+
+---
+
+*技术栈分析：[date]*
+*主要依赖变更后更新*
+```
+
+<good_examples>
+```markdown
+# 技术栈
+
+**分析日期：** 2025-01-20
+
+## 语言
+
+**主要：**
+- TypeScript 5.3 - 所有应用代码
+
+**次要：**
+- JavaScript - 构建脚本、配置文件
+
+## 运行时
+
+**环境：**
+- Node.js 20.x（LTS）
+- 无浏览器运行时（仅 CLI 工具）
+
+**包管理器：**
+- npm 10.x
+- 锁文件：存在 `package-lock.json`
+
+## 框架
+
+**核心：**
+- 无（原生 Node.js CLI）
+
+**测试：**
+- Vitest 1.0 - 单元测试
+- tsx - 无需构建步骤的 TypeScript 执行
+
+**构建/开发：**
+- TypeScript 5.3 - 编译为 JavaScript
+- esbuild - Vitest 使用的快速转换
+
+## 关键依赖
+
+**核心：**
+- commander 11.x - CLI 参数解析和命令结构
+- chalk 5.x - 终端输出样式
+- fs-extra 11.x - 扩展文件系统操作
+
+**基础设施：**
+- Node.js 内置模块 - fs、path、child_process 用于文件操作
+
+## 配置
+
+**环境：**
+- 不需要环境变量
+- 仅通过 CLI 标志配置
+
+**构建：**
+- `tsconfig.json` - TypeScript 编译器选项
+- `vitest.config.ts` - 测试运行器配置
+
+## 平台要求
+
+**开发：**
+- macOS/Linux/Windows（任何有 Node.js 的平台）
+- 无外部依赖
+
+**生产：**
+- 作为 npm 包分发
+- 通过 npm install -g 全局安装
+- 在用户的 Node.js 安装上运行
+
+---
+
+*技术栈分析：2025-01-20*
+*主要依赖变更后更新*
+```
+</good_examples>
+
+<guidelines>
+**STACK.md 中应包含的内容：**
+- 语言和版本
+- 运行时要求（Node、Bun、Deno、浏览器）
+- 包管理器和锁文件
+- 框架选择
+- 关键依赖（限制在 5-10 个最重要的）
+- 构建工具
+- 平台/部署要求
+
+**不应包含的内容：**
+- 文件结构（那是 STRUCTURE.md 的内容）
+- 架构模式（那是 ARCHITECTURE.md 的内容）
+- package.json 中的每个依赖（仅关键的）
+- 实现细节（参考代码）
+
+**填写此模板时：**
+- 检查 package.json 中的依赖
+- 从 .nvmrc 或 package.json engines 记录运行时版本
+- 仅包含影响理解的依赖（不是每个工具库）
+- 仅在版本重要时指定版本（破坏性变更、兼容性）
+
+**在阶段规划中的用途：**
+- 添加新依赖时（检查兼容性）
+- 升级框架时（了解当前使用情况）
+- 选择实现方法时（必须与现有技术栈兼容）
+- 了解构建要求
+</guidelines>