speccore 8.3.290 → 8.3.296

package/templates/api-design-example.md

@@ -0,0 +1,338 @@
+# API 设计规范示例
+
+> 本文件为 RESTful API 设计规范示例，供新项目参考。
+> 复制到项目后按需修改，或作为 `.speccore/RULES/api-design.md` 的素材。
+
+---
+
+## 1. 基础规范
+
+### 1.1 URL 设计
+
+- **全部小写**，使用短横线 `-` 分隔单词
+- **资源名用复数**：`/users` `/orders` `/products`
+- **避免动词**：用 HTTP 方法表达动作，不要写 `/getUsers` `/createOrder`
+- **嵌套不超过 3 层**：`/users/{id}/orders/{orderId}/items` ✅，`/users/{id}/orders/{orderId}/items/{itemId}/reviews/{reviewId}` ❌
+
+```
+GET    /users              # 列表
+GET    /users/{id}         # 详情
+POST   /users              # 创建
+PUT    /users/{id}         # 全量更新
+PATCH  /users/{id}         # 部分更新
+DELETE /users/{id}         # 删除
+```
+
+### 1.2 HTTP 状态码
+
+| 状态码 | 场景 | 说明 |
+|:---|:---|:---|
+| `200` | 成功 | GET/PUT/PATCH/DELETE 成功 |
+| `201` | 创建成功 | POST 创建资源成功 |
+| `204` | 无内容 | DELETE 成功，不返回 body |
+| `400` | 参数错误 | 请求参数校验失败 |
+| `401` | 未认证 | Token 缺失或过期 |
+| `403` | 无权限 | 已登录但无权访问 |
+| `404` | 不存在 | 资源不存在 |
+| `409` | 冲突 | 资源已存在或状态冲突 |
+| `422` | 业务规则冲突 | 请求语法正确但业务规则不允许 |
+| `429` | 限流 | 请求过于频繁 |
+| `500` | 系统错误 | 服务端未捕获异常 |
+
+### 1.3 请求/响应格式
+
+**请求头必备：**
+```
+Content-Type: application/json
+Authorization: Bearer {token}
+X-Request-Id: {uuid}          # 链路追踪 ID
+X-Client-Version: 1.2.0       # 客户端版本（可选）
+```
+
+**统一响应体：**
+```json
+{
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": { ... },
+  "traceId": "req-abc123",
+  "timestamp": "2026-09-10T12:00:00Z"
+}
+```
+
+**错误响应体：**
+```json
+{
+  "success": false,
+  "code": "BIZ_001",
+  "message": "参数校验失败",
+  "details": [
+    { "field": "phone", "message": "手机号格式不正确" }
+  ],
+  "traceId": "req-abc123",
+  "timestamp": "2026-09-10T12:00:00Z"
+}
+```
+
+---
+
+## 2. 分页规范
+
+**请求：**
+```
+GET /users?page=1&pageSize=20&sort=createdAt,desc&sort=name,asc
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": {
+    "list": [ ... ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 20,
+      "total": 156,
+      "totalPages": 8,
+      "hasNext": true,
+      "hasPrev": false
+    }
+  }
+}
+```
+
+**规则：**
+- `page` 从 1 开始，不是 0
+- `pageSize` 默认 20，最大 100
+- `sort` 支持多字段，格式 `字段名,asc|desc`
+- 不分页接口必须显式声明，默认都分页
+
+---
+
+## 3. 鉴权规范
+
+### 3.1 Token 机制
+
+- **Access Token：** JWT，有效期 2 小时，放在 `Authorization: Bearer {token}`
+- **Refresh Token：** 有效期 7 天，用于换取新的 Access Token
+- **Token 刷新：** 返回 401 时，客户端用 Refresh Token 换取新 Access Token，重试原请求
+
+### 3.2 接口鉴权分级
+
+| 级别 | 说明 | 示例 |
+|:---|:---|:---|
+| `public` | 无需登录 | 登录接口、注册接口、公开数据 |
+| `user` | 需登录 | 查看自己的订单、修改个人资料 |
+| `admin` | 需管理员权限 | 用户管理、系统配置 |
+| `super` | 需超级管理员 | 删除组织、修改全局配置 |
+
+### 3.3 权限校验顺序
+
+1. 校验 Token 有效性（是否过期、是否被吊销）
+2. 校验接口访问权限（该角色能否访问此接口）
+3. 校验数据权限（该用户能否操作此数据）
+4. 记录审计日志（谁、什么时间、访问了什么）
+
+---
+
+## 4. 版本控制
+
+### 4.1 URL 路径版本（推荐）
+
+```
+/v1/users
+/v2/users
+```
+
+### 4.2 Header 版本（备选）
+
+```
+Accept: application/json; version=2.0
+```
+
+**规则：**
+- 主版本号变更（v1 → v2）才改 URL，内部迭代不改
+- 老版本保留至少 6 个月，给客户端迁移时间
+- 版本文档必须说明各版本差异和废弃计划
+
+---
+
+## 5. 文件上传
+
+### 5.1 直接上传（小文件 < 5MB）
+
+```
+POST /files
+Content-Type: multipart/form-data
+
+file: (binary)
+folder: avatars        # 业务目录
+```
+
+### 5.2 预签名上传（大文件 > 5MB）
+
+```
+POST /files/presign
+{
+  "filename": "report.pdf",
+  "size": 10485760,
+  "mimeType": "application/pdf"
+}
+
+# 返回预签名 URL，客户端直传 OSS/S3
+{
+  "success": true,
+  "data": {
+    "uploadUrl": "https://oss.example.com/...",
+    "fileUrl": "https://cdn.example.com/files/xxx.pdf",
+    "expiresAt": "2026-09-10T12:05:00Z"
+  }
+}
+```
+
+**规则：**
+- 限制文件类型（白名单）
+- 限制文件大小（单文件最大 50MB）
+- 图片自动压缩、生成缩略图
+- 敏感文件（身份证、营业执照）加密存储
+
+---
+
+## 6. 幂等性设计
+
+### 6.1 幂等键（Idempotency-Key）
+
+```
+POST /orders
+Idempotency-Key: {uuid}
+
+{
+  "productId": 123,
+  "quantity": 2
+}
+```
+
+**规则：**
+- 客户端生成唯一键，服务端缓存结果 24 小时
+- 相同幂等键重复请求，返回相同结果（不重复执行业务）
+- 适用于：支付、下单、转账等关键操作
+
+### 6.2 乐观锁（Version）
+
+```
+PUT /users/{id}
+{
+  "name": "张三",
+  "version": 5
+}
+```
+
+- 更新时校验 `version`，不一致返回 `409 Conflict`
+- 适用于：并发修改同一资源的场景
+
+---
+
+## 7. 批量操作
+
+### 7.1 批量查询
+
+```
+GET /users?ids=1,2,3,4,5
+```
+
+- `ids` 最多 100 个
+- 超过 100 个返回 `400`，提示分批查询
+
+### 7.2 批量创建/更新/删除
+
+```
+POST /users/batch
+{
+  "items": [
+    { "name": "张三", "phone": "13800138001" },
+    { "name": "李四", "phone": "13800138002" }
+  ]
+}
+```
+
+**规则：**
+- 批量最多 100 条
+- 部分失败返回 `207 Multi-Status`，明细说明每条结果
+- 全部失败返回 `400`，不执行任何操作（事务回滚）
+
+---
+
+## 8. 限流与熔断
+
+### 8.1 限流规则
+
+| 级别 | 阈值 | 说明 |
+|:---|:---|:---|
+| IP 级 | 100 次/分钟 | 防止单 IP 刷接口 |
+| 用户级 | 1000 次/分钟 | 正常用户足够，异常行为拦截 |
+| 接口级 | 根据业务设定 | 如短信接口 5 次/小时 |
+
+### 8.2 熔断策略
+
+- 错误率 > 50% 持续 1 分钟 → 熔断 30 秒
+- 熔断期间返回 `503`，提示"服务暂不可用"
+- 熔断恢复后，先放行少量请求探测，正常后全开
+
+---
+
+## 9. 接口文档规范
+
+### 9.1 文档必备内容
+
+每个接口文档必须包含：
+1. **接口描述** — 一句话说明功能
+2. **请求方法 + URL** — 含路径参数说明
+3. **请求头** — 必填头列表
+4. **请求参数** — Query / Body / Path，含类型、必填、示例、约束
+5. **响应体** — 成功 + 失败示例
+6. **错误码** — 该接口可能返回的所有错误码
+7. **权限要求** — public / user / admin / super
+8. **幂等性** — 是否幂等，幂等键要求
+
+### 9.2 示例模板
+
+```markdown
+### 创建订单
+
+**接口描述：** 用户创建新订单
+
+**请求：**
+```
+POST /v1/orders
+Authorization: Bearer {token}
+Idempotency-Key: {uuid}
+```
+
+**请求体：**
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|:---|:---|:---:|:---|:---|
+| productId | long | ✅ | 商品 ID | 123 |
+| quantity | int | ✅ | 数量，1~99 | 2 |
+| remark | string | ❌ | 订单备注，≤200字 | "请尽快发货" |
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": {
+    "orderId": "ORD-20260910-001",
+    "status": "PENDING_PAYMENT",
+    "totalAmount": 19900,
+    "createdAt": "2026-09-10T12:00:00Z"
+  }
+}
+```
+
+**错误码：**
+| 错误码 | 说明 |
+|:---|:---|
+| BIZ_001 | productId 不存在 |
+| BIZ_005 | 库存不足 |
+| BIZ_003 | 重复提交（相同幂等键） |
+```

package/templates/ci/github-actions.yml

@@ -0,0 +1,44 @@
+# SpecCore CI — GitHub Actions
+# Copy this file to your project: .github/workflows/speccore-ci.yml
+
+name: SpecCore Validate
+
+on:
+  push:
+    branches: [main, feature/*]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install SpecCore
+        run: npm install -g speccore
+
+      - name: Validate Specs
+        run: |
+          speccore validate --full
+          if [ $? -ne 0 ]; then
+            echo "⚠️ Spec validation failed. Please fix the issues above."
+            exit 1
+          fi
+
+      - name: Check Project Health
+        run: speccore doctor
+
+      - name: Progress Report
+        run: speccore progress --format=json > progress.json
+
+      - name: Upload Progress Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: spec-progress
+          path: progress.json

package/templates/database-example.md

@@ -0,0 +1,223 @@
+# 数据库设计规范示例
+
+> 本文件为数据库设计规范示例，涵盖命名、字段、索引、分表等经典规则。
+> 复制到项目后按需修改，或作为 `.speccore/RULES/database.md` 的素材。
+
+---
+
+## 1. 命名规范
+
+### 1.1 表命名
+
+| 规则 | 示例 | 说明 |
+|:---|:---|:---|
+| 小写 + 下划线 | `user_profile` | 全部小写，单词间用 `_` 分隔 |
+| 复数形式 | `orders` `users` | 表名用复数 |
+| 业务前缀 | `oms_order` `cms_article` | 多模块项目加前缀区分 |
+| 禁用保留字 | — | 不要用 `order` `group` `key` 等 SQL 保留字 |
+
+### 1.2 字段命名
+
+| 规则 | 正例 | 反例 |
+|:---|:---|:---|
+| 小写 + 下划线 | `created_at` | `createdAt` `Created_At` |
+| 外键格式 | `user_id` `order_id` | `uid` `oid` |
+| 布尔字段 | `is_deleted` `is_active` | `deleted` `active` |
+| 状态字段 | `status` + 枚举说明 | `state`（模糊） |
+| 时间字段 | `created_at` `updated_at` | `create_time`（不一致） |
+
+### 1.3 索引命名
+
+| 类型 | 命名格式 | 示例 |
+|:---|:---|:---|
+| 主键 | `pk_表名` | `pk_users` |
+| 唯一索引 | `uk_表名_字段` | `uk_users_phone` |
+| 普通索引 | `idx_表名_字段` | `idx_orders_user_id` |
+| 联合索引 | `idx_表名_字段1_字段2` | `idx_orders_user_id_status` |
+
+---
+
+## 2. 字段设计规范
+
+### 2.1 必备字段（每张表必须有）
+
+| 字段名 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `id` | `BIGINT UNSIGNED` | 自增 | 主键，建议使用雪花 ID |
+| `created_at` | `DATETIME(3)` | `CURRENT_TIMESTAMP(3)` | 创建时间，毫秒精度 |
+| `updated_at` | `DATETIME(3)` | `CURRENT_TIMESTAMP(3)` | 更新时间，ON UPDATE 自动更新 |
+| `created_by` | `BIGINT UNSIGNED` | `NULL` | 创建人 ID |
+| `updated_by` | `BIGINT UNSIGNED` | `NULL` | 更新人 ID |
+| `deleted_at` | `DATETIME(3)` | `NULL` | 软删除时间，NULL 表示未删除 |
+| `deleted_by` | `BIGINT UNSIGNED` | `NULL` | 删除人 ID |
+| `version` | `INT UNSIGNED` | `0` | 乐观锁版本号 |
+
+### 2.2 常用字段类型选择
+
+| 场景 | 推荐类型 | 不推荐 | 说明 |
+|:---|:---|:---|:---|
+| 主键 | `BIGINT UNSIGNED` | `INT` | 防止溢出 |
+| 金额 | `BIGINT`（分） | `DECIMAL` `FLOAT` | 整数存储，避免精度问题 |
+| 手机号 | `VARCHAR(20)` | `BIGINT` | 支持国际号码、国家码 |
+| 邮箱 | `VARCHAR(128)` | `TEXT` | 有长度限制，可建索引 |
+| 用户名 | `VARCHAR(64)` | `TEXT` | — |
+| 密码 | `VARCHAR(255)` | `CHAR(32)` | 需兼容 bcrypt 等哈希长度 |
+| 状态枚举 | `TINYINT UNSIGNED` | `VARCHAR` | 节省空间，配合代码枚举 |
+| 大文本 | `TEXT` | `VARCHAR(65535)` | 文章、评论等内容 |
+| JSON 数据 | `JSON` | `TEXT` | MySQL 5.7+ / PostgreSQL 原生支持 |
+| IP 地址 | `VARBINARY(16)` | `VARCHAR(45)` | 兼容 IPv4/IPv6 |
+| 时间戳 | `DATETIME(3)` | `TIMESTAMP` | DATETIME 无时区歧义，范围更大 |
+
+### 2.3 字段约束
+
+- **NOT NULL 优先：** 尽量不让字段为 NULL，用默认值代替
+- **状态字段必须有注释：** 说明每个值的含义
+- **JSON 字段必须定义结构：** 即使类型是 JSON，也要在文档中定义字段结构
+- **大字段单独表：** TEXT/BLOB 超过 1KB 建议拆到副表
+
+---
+
+## 3. 索引设计规范
+
+### 3.1 索引原则
+
+1. **where 条件字段必建索引** — 特别是高频查询条件
+2. **联合索引最左前缀** — `(a, b, c)` 可以覆盖 `a` `a,b` `a,b,c`，但不能覆盖 `b` `c`
+3. **覆盖索引优先** — 查询字段都在索引中，避免回表
+4. **索引不是越多越好** — 单表索引不超过 5 个，联合索引字段不超过 4 个
+5. **区分度低的字段放前面** — 性别（区分度 2）放前面，创建时间（区分度高）放后面
+6. **冗余索引清理** — `(a)` 和 `(a,b)` 并存时，`(a)` 是冗余的
+
+### 3.2 索引示例
+
+```sql
+-- 用户表
+CREATE TABLE users (
+  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+  phone VARCHAR(20) NOT NULL,
+  email VARCHAR(128),
+  username VARCHAR(64) NOT NULL,
+  status TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '1-正常 2-冻结 3-注销',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  deleted_at DATETIME(3) DEFAULT NULL,
+  
+  UNIQUE KEY uk_users_phone (phone),
+  UNIQUE KEY uk_users_email (email),
+  UNIQUE KEY uk_users_username (username),
+  KEY idx_users_status_created (status, created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
+```
+
+### 3.3 索引禁忌
+
+- ❌ 不要在低区分度字段上单独建索引（如 `status` 只有 2 个值）
+- ❌ 不要对频繁更新的字段建索引（更新成本 = 数据更新 + 索引更新）
+- ❌ 不要在 WHERE 条件中对字段做函数运算（如 `WHERE DATE(created_at) = '2026-09-10'`）
+- ❌ 不要用 `SELECT *`，只查需要的字段，尽量覆盖索引
+
+---
+
+## 4. 分表分库策略
+
+### 4.1 何时分表
+
+| 条件 | 策略 |
+|:---|:---|
+| 单表数据 > 500 万 | 水平分表 |
+| 单表数据 > 1 亿 | 水平分库 + 分表 |
+| 字段数 > 50 | 垂直拆分（大字段拆副表） |
+| 冷热数据明显 | 归档表（近 3 个月热数据 + 历史归档表） |
+
+### 4.2 分表路由键选择
+
+| 场景 | 路由键 | 说明 |
+|:---|:---|:---|
+| 用户相关数据 | `user_id` | 按用户维度分片，查询集中在单分片 |
+| 订单数据 | `order_id` 或 `user_id` | 订单号含时间戳可直接路由 |
+| 时间序列数据 | `created_at` | 按时间范围分片，便于归档清理 |
+| 地理位置数据 | `region_code` | 按地区分片，就近访问 |
+
+### 4.3 分表示例
+
+```sql
+-- 订单表按 user_id % 128 分片
+-- 物理表：order_000 ~ order_127
+-- 路由规则：order_{user_id % 128}
+
+CREATE TABLE order_000 (
+  id BIGINT UNSIGNED PRIMARY KEY,
+  order_no VARCHAR(32) NOT NULL,
+  user_id BIGINT UNSIGNED NOT NULL,
+  total_amount BIGINT NOT NULL COMMENT '金额（分）',
+  status TINYINT UNSIGNED NOT NULL,
+  created_at DATETIME(3) NOT NULL,
+  
+  UNIQUE KEY uk_order_no (order_no),
+  KEY idx_user_id_created (user_id, created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+---
+
+## 5. 软删除与数据归档
+
+### 5.1 软删除实现
+
+```sql
+-- 查询时默认过滤软删除数据
+SELECT * FROM users WHERE deleted_at IS NULL;
+
+-- 需要包含已删除数据时显式指定
+SELECT * FROM users WHERE deleted_at IS NOT NULL;
+```
+
+### 5.2 数据归档策略
+
+| 数据类型 | 保留时间 | 归档方式 |
+|:---|:---|:---|
+| 操作日志 | 90 天 | 超过后迁移到归档表或 OSS |
+| 订单数据 | 3 年 | 冷数据归档到历史库 |
+| 系统日志 | 30 天 | ELK 设置过期策略 |
+| 审计日志 | 3 年 | 单独存储，不可删除 |
+
+---
+
+## 6. SQL 编写规范
+
+### 6.1 SELECT
+
+- 必须指定字段，禁止 `SELECT *`
+- 分页查询必须带 `ORDER BY`，否则结果不稳定
+- 大批量查询使用 `LIMIT + 游标`，避免深分页 `OFFSET 1000000`
+
+### 6.2 INSERT/UPDATE/DELETE
+
+- INSERT 必须指定字段名：`INSERT INTO t (a, b) VALUES (?, ?)`
+- UPDATE 必须带 WHERE 条件，禁止全表更新
+- DELETE 必须带 WHERE 条件，生产环境建议用软删除代替
+
+### 6.3 事务
+
+- 事务尽量短，不要在事务中调外部接口
+- 更新多个表时，按相同顺序加锁，避免死锁
+- 批量操作使用 `INSERT ... ON DUPLICATE KEY UPDATE` 或 `REPLACE INTO`
+
+---
+
+## 7. 数据库评审清单
+
+新建或修改表时必须检查：
+
+- [ ] 表名符合命名规范（小写 + 下划线 + 复数）
+- [ ] 包含必备字段（id, created_at, updated_at, deleted_at, version）
+- [ ] 主键使用 BIGINT UNSIGNED
+- [ ] 金额字段用 BIGINT（分）存储
+- [ ] 状态字段有注释说明每个值的含义
+- [ ] 外键字段建立索引
+- [ ] WHERE 条件字段建立索引
+- [ ] 联合索引符合最左前缀原则
+- [ ] 单表索引数量 ≤ 5
+- [ ] 表和字段都有 COMMENT 注释
+- [ ] 字符集使用 utf8mb4
+- [ ] 引擎使用 InnoDB