@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/09-templates/02-api-design.md

@@ -0,0 +1,408 @@
+# 接口设计：{项目/系统名}
+
+> **版本**: v1.0
+> **模板来源**: OpenAPI Specification (Swagger) v3.0、RESTful API 最佳实践、Google API Design Guide
+> **适用范围**: RESTful API、GraphQL、gRPC 接口设计
+> **生成模式**: API 概览 → 资源定义 → 端点设计 → 错误处理
+
+---
+
+## 1. API 概览
+
+### 1.1 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| API 名称 | |
+| 版本 | v1.0 |
+| 基础 URL | |
+| 认证方式 | JWT/OAuth2/API Key |
+| 数据格式 | JSON/Protobuf |
+
+### 1.2 设计原则
+
+- [ ] RESTful 风格
+- [ ] 资源导向设计
+- [ ] 统一的错误处理
+- [ ] 版本控制
+- [ ] 幂等性保证
+- [ ] 速率限制
+
+### 1.3 认证授权
+
+| 认证方式 | 说明 | 适用场景 |
+|---------|------|---------|
+| API Key | 通过 Header 传递 | 服务端调用 |
+| JWT | Bearer Token | 用户认证 |
+| OAuth2 | 授权码模式 | 第三方授权 |
+
+**请求头示例**：
+```http
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+---
+
+## 2. 资源定义
+
+### 2.1 资源列表
+
+| 资源名称 | 资源路径 | 描述 | 主要操作 |
+|---------|---------|------|---------|
+| | `/api/v1/{resource}` | | GET/POST/PUT/DELETE |
+
+### 2.2 资源模型
+
+#### {资源名称}
+
+```json
+{
+  "id": "string，资源唯一标识",
+  "name": "string，资源名称",
+  "description": "string，资源描述",
+  "status": "enum，资源状态",
+  "createdAt": "string，创建时间 (ISO8601)",
+  "updatedAt": "string，更新时间 (ISO8601)",
+  "metadata": "object，扩展元数据"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| id | string | 是 | 资源唯一标识 | uuid |
+| name | string | 是 | 资源名称 | |
+| status | enum | 是 | 状态：ACTIVE/INACTIVE/DELETED | |
+
+---
+
+## 3. 端点设计
+
+### 3.1 端点列表
+
+| 方法 | 端点 | 描述 | 认证 | 幂等 |
+|------|------|------|------|------|
+| GET | `/api/v1/{resource}` | 获取资源列表 | 是 | 是 |
+| GET | `/api/v1/{resource}/{id}` | 获取单个资源 | 是 | 是 |
+| POST | `/api/v1/{resource}` | 创建资源 | 是 | 否 |
+| PUT | `/api/v1/{resource}/{id}` | 更新资源 | 是 | 是 |
+| DELETE | `/api/v1/{resource}/{id}` | 删除资源 | 是 | 是 |
+
+### 3.2 端点详情
+
+#### GET /api/v1/{resource}
+
+**请求参数**：
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| page | query | integer | 否 | 页码，默认 1 |
+| pageSize | query | integer | 否 | 每页数量，默认 20 |
+| sortBy | query | string | 否 | 排序字段 |
+| order | query | string | 否 | 排序方向：asc/desc |
+
+**响应示例**：
+```json
+{
+  "data": [
+    {
+      "id": "uuid",
+      "name": "资源名称"
+    }
+  ],
+  "pagination": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5
+  }
+}
+```
+
+#### POST /api/v1/{resource}
+
+**请求体**：
+```json
+{
+  "name": "string，资源名称",
+  "description": "string，资源描述",
+  "metadata": {}
+}
+```
+
+**响应示例**：
+```json
+{
+  "id": "uuid",
+  "name": "资源名称",
+  "createdAt": "2026-03-27T10:00:00Z"
+}
+```
+
+---
+
+## 4. 错误处理
+
+### 4.1 错误响应格式
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "错误描述",
+    "details": [],
+    "timestamp": "2026-03-27T10:00:00Z",
+    "path": "/api/v1/resource"
+  }
+}
+```
+
+### 4.2 错误码定义
+
+| 错误码 | HTTP 状态码 | 说明 |
+|-------|-----------|------|
+| VALIDATION_ERROR | 400 | 请求参数验证失败 |
+| UNAUTHORIZED | 401 | 未认证 |
+| FORBIDDEN | 403 | 无权限 |
+| NOT_FOUND | 404 | 资源不存在 |
+| CONFLICT | 409 | 资源冲突 |
+| RATE_LIMITED | 429 | 请求频率超限 |
+| INTERNAL_ERROR | 500 | 服务器内部错误 |
+
+---
+
+## 5. 速率限制
+
+| 用户类型 | 限制 | 时间窗口 |
+|---------|------|---------|
+| 匿名用户 | 100 请求 | 1 分钟 |
+| 认证用户 | 1000 请求 | 1 分钟 |
+| VIP 用户 | 10000 请求 | 1 分钟 |
+
+**响应头**：
+```http
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1680000000
+```
+
+---
+
+## 6. 版本控制
+
+### 6.1 版本策略
+
+- URL 路径版本化：`/api/v1/`, `/api/v2/`
+- 向后兼容至少 2 个版本
+- 废弃通知周期：3 个月
+
+### 6.2 版本历史
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1.0 | | 初始版本 |
+
+---
+
+## 7. RPC 接口设计
+
+> 适用于 Dubbo、gRPC、Thrift 等 RPC 框架的接口设计
+
+### 7.1 RPC 接口概览
+
+| 字段 | 值 |
+|------|-----|
+| 服务名称 | |
+| 接口类型 | Facade/Service/Repository/Client |
+| 协议类型 | Dubbo/gRPC/Thrift/自定义 |
+| 服务分组 | |
+| 服务版本 | |
+
+### 7.2 接口定义
+
+#### 接口声明（语言无关）
+
+```
+interface XxxFacade {
+    Result method(Request request);
+    void notify(Event event);
+}
+```
+
+#### 接口方法列表
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| {method} | {params} | {return} | {description} |
+
+### 7.3 请求/响应模型
+
+#### 请求模型
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| {field} | {type} | 是/否 | {description} |
+
+#### 响应模型
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| {field} | {type} | {description} |
+
+### 7.4 服务提供者
+
+| 实现类 | 路径 | 说明 |
+|--------|------|------|
+| {ServiceImpl} | {path} | 服务实现 |
+
+### 7.5 服务引用
+
+| 引用方 | 引用方式 | 用途 |
+|--------|----------|------|
+| {project} | 依赖注入/客户端 | {purpose} |
+
+### 7.6 配置项
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| {service}.endpoint | String | 是 | - | 服务地址 |
+| {service}.timeout | Integer | 否 | 5000 | 超时时间(ms) |
+| {service}.retries | Integer | 否 | 2 | 重试次数 |
+
+### 7.7 多语言示例
+
+#### Java (Dubbo)
+
+```java
+@DubboReference(interfaceClass = XxxFacade.class)
+private XxxFacade xxxFacade;
+
+public Result call(Request request) {
+    return xxxFacade.method(request);
+}
+```
+
+#### Go (gRPC)
+
+```go
+client := pb.NewXxxFacadeClient(conn)
+resp, err := client.Method(ctx, &pb.Request{...})
+```
+
+#### Python (gRPC)
+
+```python
+stub = xxx_facade_pb2_grpc.XxxFacadeStub(channel)
+response = stub.Method(xxx_facade_pb2.Request(...))
+```
+
+### 7.8 RPC 最佳实践
+
+1. 设置合理的超时时间，避免长时间等待
+2. 实现重试机制，处理临时故障
+3. 使用服务分组和版本进行灰度发布
+4. 记录调用日志，便于问题排查
+5. 敏感信息使用环境变量，不要硬编码
+
+---
+
+## 8. 附录
+
+### 7.1 OpenAPI 规范
+
+```yaml
+openapi: 3.0.0
+info:
+  title: API 名称
+  version: 1.0.0
+  description: API 描述
+  contact:
+    name: API 支持团队
+    email: support@example.com
+servers:
+  - url: https://api.example.com/v1
+    description: 生产环境
+  - url: https://staging-api.example.com/v1
+    description: 预发环境
+paths:
+  /api/v1/resource:
+    get:
+      summary: 获取资源列表
+      tags:
+        - Resource
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Resource'
+                  pagination:
+                    $ref: '#/components/schemas/Pagination'
+        '401':
+          description: 未认证
+        '403':
+          description: 无权限
+        '500':
+          description: 服务器错误
+components:
+  schemas:
+    Resource:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+    Pagination:
+      type: object
+      properties:
+        total:
+          type: integer
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        totalPages:
+          type: integer
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+security:
+  - bearerAuth: []
+```
+
+### 7.2 SDK 生成
+
+- [ ] JavaScript/TypeScript SDK
+- [ ] Python SDK
+- [ ] Java SDK
+- [ ] Go SDK
+
+---
+
+**维护者**: 项目团队
+**进化分区**: 受控区
+**关联文档**: `knowledge/09-templates/01-architecture-design.md`, `knowledge/09-templates/03-database-design.md`

package/knowledge/09-templates/03-database-design.md

@@ -0,0 +1,313 @@
+# 数据库设计：{项目/系统名}
+
+> **版本**: v1.0
+> **模板来源**: 数据库设计最佳实践、SQL 标准、数据建模方法论
+> **适用范围**: 关系型数据库、NoSQL 数据库、数据仓库设计
+> **生成模式**: 概念模型 → 逻辑模型 → 物理模型 → 优化策略
+
+---
+
+## 1. 设计概述
+
+### 1.1 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 数据库类型 | MySQL/PostgreSQL/Oracle/MongoDB |
+| 版本 | |
+| 字符集 | UTF-8/UTF8MB4 |
+| 排序规则 | |
+| 存储引擎 | InnoDB/MyISAM |
+
+### 1.2 设计原则
+
+- [ ] 第三范式 (3NF)
+- [ ] 适当的反范式优化
+- [ ] 主键设计合理
+- [ ] 索引覆盖充分
+- [ ] 分区策略明确
+
+### 1.3 数据量预估
+
+| 表名 | 初始数据量 | 日增长量 | 年增长率 | 保留策略 |
+|------|-----------|---------|---------|---------|
+| | | | | |
+
+---
+
+## 2. 概念模型
+
+### 2.1 ER 图
+
+```mermaid
+erDiagram
+    ENTITY_A {
+        string id PK
+        string name
+        datetime created_at
+    }
+
+    ENTITY_B {
+        string id PK
+        string id_a FK
+        string description
+    }
+
+    ENTITY_A ||--o{ ENTITY_B : "has"
+```
+
+### 2.2 实体列表
+
+| 实体名称 | 说明 | 主键 | 外键 | 索引 |
+|---------|------|------|------|------|
+| | | | | |
+
+---
+
+## 3. 逻辑模型
+
+### 3.1 表结构
+
+#### {表名}
+
+**表说明**：
+
+| 属性 | 值 |
+|------|-----|
+| 表名 | |
+| 说明 | |
+| 数据量 | |
+| 更新频率 | |
+
+**字段定义**：
+
+| 字段名 | 类型 | 长度 | 必填 | 默认值 | 说明 |
+|-------|------|------|------|--------|------|
+| id | BIGINT | | YES | AUTO_INCREMENT | 主键 |
+| name | VARCHAR | 100 | YES | | 名称 |
+| status | TINYINT | | YES | 1 | 状态 |
+| created_at | DATETIME | | YES | CURRENT_TIMESTAMP | 创建时间 |
+| updated_at | DATETIME | | YES | ON UPDATE | 更新时间 |
+
+**索引设计**：
+
+| 索引名 | 字段 | 类型 | 说明 |
+|-------|------|------|------|
+| idx_name | name | NORMAL | 名称查询 |
+| uk_email | email | UNIQUE | 邮箱唯一 |
+
+### 3.2 表关系
+
+| 主表 | 从表 | 关系类型 | 外键字段 | 级联规则 |
+|------|------|---------|---------|---------|
+| | | 1:N / N:M | | CASCADE/SET NULL |
+
+---
+
+## 4. 物理模型
+
+### 4.1 DDL 脚本
+
+```sql
+CREATE TABLE `table_name` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键 ID',
+  `name` VARCHAR(100) NOT NULL COMMENT '名称',
+  `status` TINYINT DEFAULT 1 COMMENT '状态：1-正常，0-禁用',
+  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_name` (`name`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='表说明';
+```
+
+### 4.2 分区策略
+
+| 表名 | 分区类型 | 分区键 | 分区数 | 说明 |
+|------|---------|--------|-------|------|
+| | RANGE/LIST/HASH | | | |
+
+### 4.3 分库分表策略
+
+| 表名 | 分片键 | 分片算法 | 分片数 | 扩容策略 |
+|------|-------|---------|-------|---------|
+| | user_id | HASH | 16 | 翻倍扩容 |
+
+---
+
+## 5. 索引优化
+
+### 5.1 索引策略
+
+| 场景 | 索引类型 | 字段选择 |
+|------|---------|---------|
+| 主键查询 | PRIMARY KEY | id |
+| 等值查询 | BTREE | 高选择性字段 |
+| 范围查询 | BTREE | 有序字段 |
+| 全文搜索 | FULLTEXT | 文本字段 |
+| 地理查询 | SPATIAL | 坐标字段 |
+
+### 5.2 索引维护
+
+| 表名 | 索引名 | 大小 | 更新频率 | 维护策略 |
+|------|-------|------|---------|---------|
+| | | | 高频/低频 | 定期重建 |
+
+---
+
+## 6. 数据迁移
+
+### 6.1 迁移脚本
+
+```sql
+-- 升级脚本
+ALTER TABLE table_name ADD COLUMN new_column VARCHAR(100) COMMENT '新字段';
+
+-- 回滚脚本
+ALTER TABLE table_name DROP COLUMN new_column;
+```
+
+### 6.2 数据同步
+
+| 源表 | 目标表 | 同步方式 | 频率 | 说明 |
+|------|-------|---------|------|------|
+| | | 实时/定时 | | |
+
+---
+
+## 7. 备份与恢复
+
+### 7.1 备份策略
+
+| 备份类型 | 频率 | 保留时间 | 存储位置 |
+|---------|------|---------|---------|
+| 全量备份 | 每日 | 7 天 | |
+| 增量备份 | 每小时 | 24 小时 | |
+| 日志备份 | 实时 | 3 天 | |
+
+### 7.2 恢复策略
+
+| 场景 | RTO | RPO | 恢复步骤 |
+|------|-----|-----|---------|
+| 单表误删 | 15 分钟 | 5 分钟 | |
+| 数据库故障 | 1 小时 | 1 分钟 | |
+
+---
+
+## 8. 性能优化
+
+### 8.1 查询优化
+
+| 问题 SQL | 优化方案 | 预期提升 |
+|---------|---------|---------|
+| | 添加索引/改写 SQL | 10x |
+
+### 8.2 配置优化
+
+| 参数 | 当前值 | 建议值 | 说明 |
+|------|-------|-------|------|
+| innodb_buffer_pool_size | | | 缓冲池大小 |
+| max_connections | | | 最大连接数 |
+
+---
+
+## 9. 附录
+
+### 9.1 命名规范
+
+| 对象类型 | 命名规则 | 示例 |
+|---------|---------|------|
+| 表名 | 小写蛇形，复数 | `user_orders` |
+| 字段名 | 小写蛇形 | `created_at` |
+| 索引名 | `idx_{字段}` / `uk_{字段}` | `idx_name` |
+
+### 9.2 参考资料
+
+- [MySQL 官方文档](https://dev.mysql.com/doc/)
+- [SQL 性能优化指南](url)
+
+---
+
+## 10. 数据模型知识（环境知识）
+
+> 本章节用于记录项目中已有的数据模型，供 env-sync 生成知识文件时参考。
+
+### 10.1 模型基本信息
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 名称 | 是 | 模型名称 |
+| 类型 | 是 | DO/Entity/PO/DTO |
+| 表名 | 是 | 数据库表名 |
+| 数据库 | 否 | 数据库名称 |
+
+### 10.2 类型枚举
+
+| 类型 | 说明 |
+|------|------|
+| DO | 数据对象，与数据库表对应 |
+| Entity | 实体类，领域模型 |
+| PO | 持久化对象 |
+| DTO | 数据传输对象 |
+| TDO | 大数据表数据对象 |
+
+### 10.3 表结构定义
+
+| 字段 | 类型 | 可空 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| {column} | {type} | 是/否 | {default} | {description} |
+
+### 10.4 数据模型类（语言无关）
+
+```
+class XxxModel {
+    id: Long
+    name: String
+    status: Integer
+    createdAt: DateTime
+}
+```
+
+### 10.5 字段映射
+
+| 模型字段 | 数据库字段 | 类型 | 说明 |
+|----------|------------|------|------|
+| {field} | {column} | {type} | {description} |
+
+### 10.6 数据访问接口
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| findById | id | Model | 按 ID 查询 |
+| findByCondition | query | List | 条件查询 |
+| insert | model | int | 插入 |
+| update | model | int | 更新 |
+| delete | id | int | 删除 |
+
+### 10.7 业务含义
+
+| 字段 | 业务含义 | 取值范围 | 说明 |
+|------|----------|----------|------|
+| {field} | {meaning} | {range} | {description} |
+
+### 10.8 状态流转
+
+如果包含状态字段，描述状态流转：
+
+| 状态值 | 状态名 | 可流转到 | 说明 |
+|--------|--------|----------|------|
+| {value} | {name} | {next_states} | {description} |
+
+### 10.9 数据量级
+
+| 指标 | 值 | 说明 |
+|------|-----|------|
+| 预估数据量 | {count} | 数据规模 |
+| 增长速度 | {rate} | 日增量 |
+| 保留周期 | {period} | 数据保留时间 |
+
+---
+
+**维护者**: 项目团队
+**进化分区**: 受控区
+**关联文档**: `knowledge/09-templates/01-architecture-design.md`, `knowledge/09-templates/02-api-design.md`, `knowledge/09-templates/05-domain-business.md`