create-vibe-workflow 0.1.0 → 0.2.0

package/dist/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/dist/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
+  记录：版本号、文件名、执行时间、校验和
+```

package/dist/templates/skills/database/postgres-patterns/SKILL.md.ejs

@@ -0,0 +1,235 @@
+# PostgreSQL Patterns — PostgreSQL 数据库模式
+
+> 使用此 skill 时：设计表结构、编写查询、优化数据库性能时。
+
+## 索引策略
+
+### 索引类型选择
+
+```text
+B-Tree（默认）：
+  适用：等值查询、范围查询、排序
+  不适用：全文搜索、数组包含
+
+Hash：
+  适用：等值查询（性能略高于 B-Tree）
+  不适用：范围查询、排序
+  注意：不记录大小，重建时需 REINDEX
+
+GiST：
+  适用：全文搜索、地理空间、范围重叠
+  示例：tsvector、geometry、timerange
+
+GIN：
+  适用：包含查询（数组、JSONB、全文搜索）
+  示例：JSONB 的 @> 操作符、数组的 @> 操作符
+
+BRIN：
+  适用：与物理存储顺序相关的大表（如时间序列）
+  优点：索引体积极小
+  注意：数据插入顺序须与索引列顺序接近
+```
+
+### 索引设计检查清单
+
+```text
+是否真正需要？
+  [ ] 这个查询是频繁执行的吗？
+  [ ] 表大到不用索引会慢吗？（<1000 行不需要）
+  [ ] 这个查询会随着数据增长变慢吗？
+
+索引列选择：
+  [ ] WHERE 子句中的列优先
+  [ ] JOIN 的关联列必须索引
+  [ ] ORDER BY 的列考虑包含在索引中
+  [ ] 高选择性的列优先（唯一值多）
+
+避免过度索引：
+  [ ] 不要为低频查询建索引
+  [ ] 不要重复索引（复合索引的前缀列不需要单独索引）
+  [ ] 写密集的表索引尽量少（每个索引增加写入开销）
+  [ ] 定期用 pg_stat_user_indexes 检查未使用索引
+
+复合索引：
+  [ ] = 条件的列放前面
+  [ ] 范围条件的列放后面
+  [ ] 查询条件中有多个 = 列时，任意顺序均可
+  [ ] 考虑 INCLUDE 列（覆盖索引）
+```
+
+## 数据类型选择
+
+```text
+【数值型】
+  整数：
+    smallint (2B, ±32K) → 枚举/状态码
+    integer   (4B, ±2B)  → 默认选择
+    bigint    (8B)       → 自增 ID 超 2B 时
+
+  小数：
+    numeric(p,s)  → 精确计算（金额）
+    double precision → 科学计算（允许小误差）
+
+【文本型】
+  text          → 没有长度限制，性能与 varchar 相同
+  varchar(n)    → 有长度约束时（如邮箱限制 254 字符）
+  citext        → 不区分大小写的文本（扩展）
+
+  选择规则：默认用 text，需要约束长度时用 varchar(n)
+
+【时间型】
+  timestamptz   → 首选（带时区，存储为 UTC）
+  timestamp     → 不需要时区时
+  date          → 只需要日期时
+  time          → 只需要时间时
+  interval      → 时间间隔
+
+【JSON vs JSONB】
+  json          → 只存不查（保留原格式、键顺序）
+  jsonb         → 需要查询/索引（二进制格式，去重键）
+
+  总结：90% 场景用 jsonb，只有日志归档等只存不查场景用 json
+
+【数组】
+  适用：标签、分类等有限集合
+  注意：数组查询不能利用普通 B-Tree 索引（需 GIN）
+```
+
+## 查询优化
+
+### N+1 查询检测
+
+```text
+症状：一次查询后循环内执行 N 次查询
+
+识别：
+  - 日志中出现大量相似查询
+  - 翻页/列表接口慢
+
+// ❌ N+1
+for each user {
+    query("SELECT * FROM orders WHERE user_id = ?", user.id)
+}
+
+// ✅ 批量查询
+userIds = users.map(u => u.id)
+orders = query("SELECT * FROM orders WHERE user_id = ANY(?)", [userIds])
+// 在应用层关联
+```
+
+### JOIN vs 子查询
+
+```text
+【优先 JOIN】
+  适用：
+    - 需要返回父表和子表的列
+    - 关联表行数不多
+
+  注意：
+    - JOIN 的表都应有索引
+    - 避免大表的 CROSS JOIN
+
+【子查询（EXISTS）】
+  适用：
+    - 只需要检查是否存在
+    - 关联条件是聚合结果
+
+  注意：
+    - EXISTS 找到第一条即停止，比 IN 快
+    - NOT EXISTS 比 NOT IN 安全（NOT IN 遇到 NULL 行为异常）
+
+总结：
+  90% 的关联查询用 JOIN
+  存在性检查用 EXISTS
+  聚合子查询用 CTE 或 LATERAL JOIN
+```
+
+### 分页策略
+
+```text
+【OFFSET/LIMIT】— 简单但大偏移量慢
+  适用：小数据集、前几页
+  问题：OFFSET 越大越慢（需要扫描并丢弃前面的行）
+
+  优化：用复合索引 + 覆盖索引减轻
+
+【游标分页（Keyset Pagination）】— 大数据集推荐
+  适用：无限滚动、实时数据
+  原理：用 WHERE 条件代替 OFFSET
+
+  SELECT * FROM users
+  WHERE createdAt < :lastCreatedAt OR (createdAt = :lastCreatedAt AND id < :lastId)
+  ORDER BY createdAt DESC, id DESC
+  LIMIT 20
+
+  优点：无论翻到第几页，性能恒定
+  缺点：不能直接跳转到特定页
+```
+
+### EXPLAIN 分析
+
+```text
+EXPLAIN ANALYZE {query};
+
+关键指标：
+  - seq scan → 考虑加索引
+  - rows 估算偏差大 → 更新统计信息（ANALYZE）
+  - actual time 大 → 确认瓶颈
+
+常见问题：
+  - 类型不匹配导致隐式转换 → 索引失效
+  - OR 条件 → 考虑 UNION ALL
+  - IN 子句大量值 → 考虑临时表或 ANY
+```
+
+## 约束与数据完整性
+
+```text
+NOT NULL — 默认用，除非真有理由允许 NULL
+UNIQUE — 保证业务唯一性（用户名、邮箱）
+CHECK — 业务规则（age > 0, status IN ('a','b','c')）
+FOREIGN KEY — 引用完整性（注意：会加锁）
+EXCLUDE — 排他约束（时间范围不重叠）
+
+注意：
+  - 外键约束创建和维护有开销
+  - 批量导入时可先禁用约束，导入后重建验证
+  - CHECK 约束比应用层验证更可靠
+```
+
+## Row-Level Security（RLS）
+
+```text
+适用：多租户隔离（每个用户只能看到自己的数据）
+
+实现：
+  1. 启用行级安全：ALTER TABLE {table} ENABLE ROW LEVEL SECURITY
+  2. 创建策略：允许/禁止特定操作
+
+示例：多租户隔离
+  CREATE POLICY tenant_isolation ON orders
+    USING (tenant_id = current_setting('app.tenant_id')::int)
+
+规则：
+  - RLS 应用层不可绕过
+  - 性能影响很小（查询只加一次过滤）
+  - 管理员应有一个绕过 RLS 的角色
+```
+
+## 连接池
+
+```text
+为什么需要连接池？
+  - 建立连接开销大（TCP + TLS + 认证）
+  - 数据库并发连接数有限
+
+配置要点：
+  - 池大小 = 2 × CPU 核心数 + 磁盘数（经验公式）
+  - 不是越大越好（过多连接→上下文切换→性能下降）
+  - 设置超时：连接超时、查询超时、闲置超时
+
+连接耗尽处理：
+  - 优先保证关键路径的连接
+  - 非关键操作降级（缓存结果 / 返回降级响应）
+  - 监控连接池使用率
+```