create-vibe-workflow 0.1.0 → 0.2.0

package/templates/skills/advanced/improve-codebase-architecture/SKILL.md.ejs

@@ -0,0 +1,172 @@
+# Improve Codebase Architecture — 代码架构优化
+
+> 使用此 skill 时：代码库变得难以修改、每次改东西都影响多个模块、新需求难以添加时。
+
+## 核心理念
+
+使用两个概念分析架构健康度：
+
+```text
+【Depth（深度）】— 一个模块的职责有多集中
+  浅（Shallow）  → 模块做了太多不同的事，没有清晰的抽象
+  深（Deep）     → 模块封装了复杂逻辑，对外暴露简单接口
+
+  目标：模块深而窄（内部复杂但接口简单）
+
+【Seam（接缝）】— 在不修改代码的情况下改变行为的地方
+  好的接缝 → 可以通过配置/注入/参数改变行为
+  坏的接缝 → 必须修改代码才能改变行为
+
+  目标：关键变化点都有清晰的接缝
+```
+
+### 判断方法
+
+```text
+深度检测：
+  问：这个模块的接口有几个方法？
+  问：用一个句子能说清这个模块的职责吗？
+  问：这个模块隐藏了多少复杂性？
+
+  如果：
+    - 接口方法 > 10 → 可能太浅
+    - 一句话说不清职责 → 可能太浅
+    - 调用者需要了解实现细节 → 可能太浅
+
+接缝检测：
+  问：要改变这个行为，需要修改什么文件？
+  问：想用 mock 替换这个依赖，需要改代码吗？
+  问：添加同类功能要改几个地方？
+
+  如果：
+    - 改行为必须改具体实现文件 → 没有接缝
+    - 难以 mock → 没有接缝
+    - 加同类功能要改 N 个文件（N > 1）→ 没有接缝
+```
+
+## 重构优先级矩阵
+
+| 对业务影响 | 架构问题严重 | 架构问题轻微 |
+|-----------|------------|------------|
+| **变更频繁** | **立即重构（P0）** | **计划重构** |
+| **变更稀少** | 监控，等变更时再重构 | 忽略 |
+
+### 优先级说明
+
+```text
+P0 — 立即重构
+  症状：
+    - 每次改这个功能都很痛苦
+    - 频繁出现 Bug
+    - 修改一处需要同步改多处
+
+  做法：
+    - 提取清晰抽象
+    - 建立接缝
+    - 写测试固定行为
+
+P1 — 计划重构
+  症状：
+    - 代码难以理解但暂时不改
+    - 测试写起来费劲
+
+  做法：
+    - 在 todolist 中加入重构任务
+    - 等有相关需求时顺便重构
+
+P2 — 监控
+  症状：
+    - 代码不够理想但很少改
+    - 没有实际的痛苦
+
+  做法：
+    - 不做主动重构
+    - 下次改时评估是否需要重构
+```
+
+## 常见架构问题及修复
+
+### 上帝对象（God Object）
+
+```text
+症状：
+  - 一个模块/类/文件 > 800 行
+  - 一个模块做了多件事
+  - 团队所有人都在改同一个模块
+
+修复：
+  1. 识别出独立的职责
+  2. 逐个提取为新模块
+  3. 原模块只做编排
+  4. 每个新模块有自己的测试
+```
+
+### 循环依赖
+
+```text
+症状：
+  - A → B → A (直接或间接)
+  - 初始化时需要特殊顺序
+  - 修改 A 导致 B 异常
+
+修复：
+  1. 提取共用的部分为第三个模块
+  2. 或使用依赖倒置（接口定义在调用方）
+  3. 或引入事件机制解耦
+```
+
+### 隐式依赖
+
+```text
+症状：
+  - 需要按特定顺序调用方法
+  - 依赖全局/单例状态
+  - 构造函数做了大量初始化
+
+修复：
+  1. 显式参数化依赖
+  2. 依赖注入（构造函数参数）
+  3. 消除隐式的"必须按顺序调用"的约束
+```
+
+### 散弹式修改（Shotgun Surgery）
+
+```text
+症状：
+  - 改一个需求需要改 N 个文件（N > 3）
+  - 改完后总有一两个文件忘记改
+
+修复：
+  1. 识别变化的原因
+  2. 使用策略模式、钩子或配置集中变化点
+  3. 新加同类功能不用改已有代码（开闭原则）
+```
+
+## 优化流程
+
+```text
+1. 识别痛点
+   - 哪些模块改起来最痛苦？
+   - 团队抱怨最多的是什么？
+   - 测试最难写的是什么？
+
+2. 分析根因
+   - 使用 Depth/Seam 分析
+   - 识别违反了什么原则
+
+3. 制定方案
+   - 提取接口
+   - 拆分职责
+   - 集中变化点
+   - 消除隐式依赖
+
+4. 分步实施
+   - 先加测试（固定当前行为）
+   - 小步重构（每次只提取一个职责）
+   - 每个步骤都保持可运行
+
+5. 验证
+   - 所有测试通过
+   - 行为不变
+   - 新需求实现起来更顺畅
+```

package/templates/skills/backend/backend-patterns/SKILL.md.ejs

@@ -0,0 +1,263 @@
+# Backend Patterns — 后端开发模式
+
+> 使用此 skill 时：设计 API、实现业务逻辑、组织服务层代码时。
+
+## API 设计模式
+
+### RESTful 命名规范
+
+```text
+资源命名（名词复数）：
+  GET    /resources          → 列表
+  GET    /resources/:id      → 详情
+  POST   /resources          → 创建
+  PUT    /resources/:id      → 全量更新
+  PATCH  /resources/:id      → 部分更新
+  DELETE /resources/:id      → 删除
+
+子资源：
+  GET    /resources/:id/sub-resources
+  POST   /resources/:id/sub-resources
+
+动作（非 CRUD）：
+  POST   /resources/:id/{action}    → 如 archive、approve
+
+筛选/排序/分页（查询参数）：
+  GET /resources?status=active&sort=-createdAt&page=1&limit=20
+```
+
+### 统一响应格式
+
+```text
+成功响应：
+{
+  "success": true,
+  "data": { ... },
+  "error": null,
+  "meta": {                     // 分页时
+    "total": 100,
+    "page": 1,
+    "limit": 20
+  }
+}
+
+错误响应：
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "用户友好的错误描述",
+    "details": [                // 验证错误时包含字段级错误
+      { "field": "email", "message": "邮箱格式不正确" }
+    ]
+  }
+}
+```
+
+### HTTP 状态码使用
+
+```text
+200 — 成功（GET、PATCH）
+201 — 创建成功（POST）
+204 — 无内容（DELETE）
+400 — 请求参数错误（验证失败）
+401 — 未认证
+403 — 无权限
+404 — 资源不存在
+409 — 冲突（如重复创建）
+422 — 业务逻辑错误
+429 — 请求过频（限流）
+500 — 服务器内部错误
+```
+
+## 仓储模式（Repository Pattern）
+
+```text
+作用：将数据访问逻辑与业务逻辑分离
+
+结构：
+  [接口层] I{Entity}Repository
+    - findAll(filter, sort, page)
+    - findById(id)
+    - create(data)
+    - update(id, data)
+    - delete(id)
+
+  [实现层] {Entity}Repository
+    - 具体的数据访问实现（数据库/API/文件）
+    - 接口与实现一一对应
+
+  [业务层] {Entity}Service
+    - 只依赖接口，不依赖具体实现
+    - 测试时替换为 mock 实现
+
+规则：
+  - 仓储方法名用领域语言（如 `findActiveUsers` 而非 `findByStatus`）
+  - 仓储返回领域对象，不返回数据行
+  - 业务层不拼 SQL / 查询语句
+```
+
+## 服务层模式（Service Layer）
+
+```text
+作用：编排业务逻辑，协调多个仓储和外部服务
+
+职责：
+  - 业务规则验证
+  - 事务管理（跨仓储操作）
+  - 外部服务调用编排
+  - 事件发布/消息发送
+  - 缓存管理
+
+不做的：
+  - 不处理 HTTP 请求/响应
+  - 不直接暴露给外部
+
+典型结构：
+  Service {
+    constructor(repositories, services, events) {
+      // 依赖注入
+    }
+
+    async create(input) {
+      // 1. 校验业务规则
+      // 2. 写入数据库（可跨多个仓储）
+      // 3. 发送事件
+      // 4. 返回结果
+    }
+  }
+```
+
+## 中间件模式（Middleware Pattern）
+
+```text
+请求处理管道：
+  Request → [Middleware 1] → [Middleware 2] → ... → [Handler]
+
+常见中间件（按顺序）：
+  1. 请求日志（Request Logging）
+  2. 安全头（Security Headers）
+  3. CORS
+  4. 请求体解析（Body Parser）
+  5. 认证（Authentication）
+  6. 授权（Authorization）
+  7. 限流（Rate Limiting）
+  8. 请求验证（Request Validation）
+  9. 响应转换（Response Transform）
+
+中间件规则：
+  - 每个中间件只做一件事
+  - 可配置（通过工厂函数）
+  - 执行完毕后调用 next()
+  - 错误中间件四个参数（err, req, res, next）
+```
+
+## 错误处理模式
+
+```text
+统一错误层次：
+
+  基类 AppError
+    ├── ValidationError      — 输入验证失败
+    ├── AuthenticationError  — 认证失败（401）
+    ├── AuthorizationError   — 权限不足（403）
+    ├── NotFoundError        — 资源不存在（404）
+    ├── ConflictError        — 冲突（409）
+    └── InternalError        — 内部错误（500）
+
+全局错误处理中间件：
+  try {
+    await handler(req, res)
+  } catch (error) {
+    if (error instanceof AppError) {
+      // 已知错误 → 返回对应的状态码和消息
+    } else {
+      // 未知错误 → 记录日志，返回 500
+    }
+  }
+```
+
+## 认证与授权模式
+
+### JWT 认证流程
+
+```text
+登录：
+  1. 验证凭据（用户名/密码等）
+  2. 生成 Access Token（短期，15-60 分钟）
+  3. 生成 Refresh Token（长期，7-30 天）
+  4. 返回双 Token
+
+验证：
+  1. 从请求头提取 Token（Authorization: Bearer <token>）
+  2. 验证签名和过期时间
+  3. 提取用户信息
+  4. 注入请求上下文
+
+刷新：
+  1. 验证 Refresh Token
+  2. 生成新的 Access Token
+  3. 可选：轮换 Refresh Token
+```
+
+### RBAC 权限模型
+
+```text
+角色 → 权限 → 资源
+
+结构：
+  User → Role → Permission → Resource:Action
+
+示例：
+  "管理员" → "user:read", "user:write" → "用户模块"
+
+检查流程：
+  1. 获取用户角色
+  2. 获取角色关联的权限列表
+  3. 检查当前请求的 {资源:动作} 是否在权限列表中
+  4. 通过/拒绝
+```
+
+## 缓存模式
+
+```text
+Cache-Aside（旁路缓存）：
+  读：先查缓存 → 命中返回 / 未命中查 DB → 写入缓存 → 返回
+  写：先写 DB → 使缓存失效 / 更新缓存
+
+缓存失效策略：
+  - 基于时间（TTL）
+  - 基于事件（数据变更时主动失效）
+  - 基于版本（数据带版本号，版本变化时重新加载）
+
+什么该缓存：
+  - 频繁读取不频繁修改的数据
+  - 计算开销大的结果
+  - 聚合/统计结果
+
+什么不该缓存：
+  - 实时性要求极高的数据
+  - 频繁变化的数据（缓存命中率低）
+  - 用户敏感的私有数据（除非小心处理）
+```
+
+## 后台任务模式
+
+```text
+适用场景：
+  耗时操作（文件处理、邮件发送）
+  定时任务（报表生成、数据清理）
+  异步消息（事件驱动处理）
+
+方案：
+  - 轻量级：内存队列 + Worker
+  - 生产级：消息队列（如 RabbitMQ、Redis Streams）
+  - 定时任务：Cron/Scheduler
+
+设计要点：
+  - 任务可重试（幂等性）
+  - 失败有死信队列
+  - 有监控和告警
+  - 不影响主请求路径
+```

package/templates/skills/database/database-migrations/SKILL.md.ejs

@@ -0,0 +1,202 @@
+# Database Migrations — 数据库迁移模式
+
+> 使用此 skill 时：设计数据模型变更、安排迁移执行、处理回滚时。
+
+## 安全变更原则
+
+### 黄金法则
+
+```text
+1. 每次迁移可回滚（有 up 必有 down）
+2. 迁移不破坏已有数据
+3. 兼容性先行（旧代码 + 新模式 能正常工作）
+4. 不阻塞读写（生产环境零停机）
+5. 小步提交（一个迁移只做一件事）
+```
+
+### 变更影响评估
+
+每次迁移前评估：
+
+```text
+[ ] 新字段是否可为 NULL？（旧数据不需要回填）
+[ ] 添加 NOT NULL 字段前是否已回填数据？
+[ ] 重命名列是否会中断正在运行的应用？
+[ ] 修改列类型是否需要显式 CAST？
+[ ] 删除列/表是否确认没有引用？
+[ ] 添加索引是否会长时间锁表？
+[ ] 大数据表操作是否有性能影响预估？
+```
+
+## 零停机迁移模式
+
+### 安全模式：三段式迁移
+
+```text
+场景：重构一个表（拆分字段、修改类型）
+
+阶段一：添加（向前兼容）
+  1. 添加新列（可为 NULL）
+  2. 启动双写（新旧列都写入）
+  3. 回填旧数据到新列
+
+阶段二：切换（应用层切换）
+  1. 部署新版本，应用读取新列
+  2. 确认稳定后停用旧列读取
+  3. 停止双写
+
+阶段三：清理
+  1. 验证新列数据完整
+  2. 删除旧列
+  3. 清理不再使用的索引
+```
+
+### 大表索引创建
+
+```text
+CREATE INDEX CONCURRENTLY — 不阻塞写入
+  适用于：生产环境、大表
+
+  CREATE INDEX CONCURRENTLY idx_name ON table(column);
+  -- 然后：ALTER TABLE ... 关联索引
+
+  注意：
+  - 耗时更长（两阶段构建）
+  - 如果失败需要清理（DROP INDEX）
+  - 不能在事务中执行
+
+DROP INDEX CONCURRENTLY — 不阻塞写入
+  DROP INDEX CONCURRENTLY idx_name
+```
+
+### 修改列类型
+
+```text
+安全做法：
+  1. 添加新列（可为 NULL）
+  2. 双写（应用层同时维护新旧列）
+  3. 回填旧数据
+  4. 切换读取到新列
+  5. 验证通过后删除旧列
+
+直接修改的替代：
+  ALTER TABLE ... ALTER COLUMN ... TYPE ... USING ...
+  但会锁表和重写整表！
+
+除非是 VARCHAR(n) 增加长度等不影响存储格式的修改。
+```
+
+## 迁移文件规范
+
+### 命名规则
+
+```text
+格式：{YYYYMMDD}_{HHMM}_{描述}.{ext}
+
+示例：
+  20250401_0001_create_users.{ext}
+  20250402_0830_add_email_to_users.{ext}
+  20250403_1200_create_orders_index.{ext}
+
+描述规则：
+  - 动词开头：create、add、alter、rename、drop
+  - 小写 + 下划线
+  - 15-50 字符
+```
+
+### 迁移文件模板
+
+```text
+-- up: 正向迁移
+-- 描述：添加 email 字段到 users 表
+
+ALTER TABLE users
+  ADD COLUMN email text;
+
+-- 注意：email 字段可为 NULL，旧数据不需要处理
+
+-- down: 回滚迁移
+ALTER TABLE users
+  DROP COLUMN IF EXISTS email;
+```
+
+## Seed 数据 vs 迁移数据
+
+| 类型 | 用途 | 说明 |
+|------|------|------|
+| **Seed 数据** | 开发/测试环境基础数据 | 角色、权限、配置项、演示数据 |
+| **迁移数据** | 生产环境数据转换 | 数据回填、格式转换、数据清洗 |
+
+### Seed 数据规范
+
+```text
+特点：
+  - 可重复运行（幂等）
+  - 只在开发/测试环境运行
+  - 不包含生产敏感数据
+
+常见内容：
+  - 管理员账号（开发用）
+  - 角色/权限数据
+  - 配置项
+  - 演示用的示例数据
+```
+
+### 迁移数据规范
+
+```text
+特点：
+  - 只运行一次（和迁移绑定）
+  - 在应用代码部署前运行
+  - 必须可回滚
+
+常见内容：
+  - 新字段的默认值回填
+  - 数据格式转换
+  - 数据去重/清洗
+  - 表拆分/合并的数据迁移
+```
+
+## 回滚策略
+
+```text
+自动回滚：
+  - 每个迁移有对应的 down 脚本
+  - 回滚按时间逆序执行
+
+手动回滚：
+  - 确认当前版本 → 执行逆序迁移
+  - 验证数据完整性
+  - 更新迁移跟踪表
+
+回滚注意事项：
+  - 回滚会丢失数据（新增列的内容、转换后的数据）
+  - 回滚前确认应用版本也回退了
+  - 大数据表回滚可能耗时较长
+  - 有依赖的迁移（外键、视图）需按依赖顺序回滚
+
+灾难恢复：
+  - 保留回滚前的数据库快照（pg_dump）
+  - 先恢复快照，再执行迁移
+  - 验证数据完整性后切换
+```
+
+## 迁移运行策略
+
+```text
+CI/CD 集成：
+  - 部署流水线包含迁移步骤
+  - 自动执行未运行的迁移
+  - 迁移失败阻断后续部署
+
+生产环境操作：
+  - 非工作时间执行
+  - 执行前备份数据库
+  - 监控数据库性能（慢查询、锁等待）
+  - 准备回滚方案
+
+迁移跟踪表：
+  自动维护（通常由迁移库管理）
+  schema_migrations / _migrations
+  记录：版本号、文件名、执行时间、校验和
+```