@chongyan/autospec 1.0.2 → 1.0.4

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

@@ -1,408 +0,0 @@
-# 接口设计：{项目/系统名}
-
-> **版本**: 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

@@ -1,313 +0,0 @@
-# 数据库设计：{项目/系统名}
-
-> **版本**: 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`