docs: complete documentation system (250+ files)

- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
--- a/docs/_templates/API设计-模板.md
+++ b/docs/_templates/API设计-模板.md
@@ -0,0 +1,475 @@
+# [模块名称] - API设计
+
+> **基础路径：** `/api/v1/模块名`  
+> **端点数量：** X个  
+> **认证要求：** JWT Token  
+> **最后更新：** YYYY-MM-DD
+
+---
+
+## 📋 API概览
+
+| 端点 | 方法 | 说明 | 认证 |
+|------|------|------|------|
+| `/api/v1/xxx/resources` | GET | 获取资源列表 | ✅ |
+| `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ✅ |
+| `/api/v1/xxx/resources` | POST | 创建资源 | ✅ |
+| `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ✅ |
+| `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ✅ |
+
+---
+
+## 📚 API详细设计
+
+### 1. 获取资源列表
+
+**端点：** `GET /api/v1/xxx/resources`
+
+**用途：** 获取当前用户的资源列表（分页）
+
+**请求参数：**
+
+**Query参数：**
+```typescript
+{
+  page?: number;        // 页码，默认1
+  pageSize?: number;    // 每页数量，默认10，最大100
+  status?: string;      // 筛选：状态（active/inactive）
+  keyword?: string;     // 搜索关键词
+  sortBy?: string;      // 排序字段（createdAt/updatedAt）
+  sortOrder?: 'asc' | 'desc';  // 排序方向，默认desc
+}
+```
+
+**请求示例：**
+```bash
+GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
+Authorization: Bearer <token>
+```
+
+**成功响应：** `200 OK`
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "id": 1,
+        "userId": 123,
+        "fieldName": "示例",
+        "description": "描述",
+        "status": "active",
+        "createdAt": "2025-11-06T10:00:00.000Z",
+        "updatedAt": "2025-11-06T10:00:00.000Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 10,
+      "total": 100,
+      "totalPages": 10
+    }
+  },
+  "message": "获取成功"
+}
+```
+
+**错误响应：**
+```json
+// 401 Unauthorized
+{
+  "success": false,
+  "error": {
+    "code": "UNAUTHORIZED",
+    "message": "未授权，请先登录"
+  }
+}
+
+// 400 Bad Request
+{
+  "success": false,
+  "error": {
+    "code": "INVALID_PARAMS",
+    "message": "参数错误",
+    "details": [
+      { "field": "pageSize", "message": "最大不能超过100" }
+    ]
+  }
+}
+```
+
+---
+
+### 2. 获取资源详情
+
+**端点：** `GET /api/v1/xxx/resources/:id`
+
+**用途：** 获取指定资源的详细信息
+
+**路径参数：**
+- `id` (必填): 资源ID
+
+**请求示例：**
+```bash
+GET /api/v1/xxx/resources/123
+Authorization: Bearer <token>
+```
+
+**成功响应：** `200 OK`
+```json
+{
+  "success": true,
+  "data": {
+    "id": 123,
+    "userId": 456,
+    "fieldName": "示例",
+    "description": "详细描述",
+    "status": "active",
+    "createdAt": "2025-11-06T10:00:00.000Z",
+    "updatedAt": "2025-11-06T10:00:00.000Z",
+    // 额外的关联数据
+    "user": {
+      "id": 456,
+      "name": "用户名"
+    }
+  },
+  "message": "获取成功"
+}
+```
+
+**错误响应：**
+```json
+// 404 Not Found
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "资源不存在"
+  }
+}
+
+// 403 Forbidden
+{
+  "success": false,
+  "error": {
+    "code": "FORBIDDEN",
+    "message": "无权访问此资源"
+  }
+}
+```
+
+---
+
+### 3. 创建资源
+
+**端点：** `POST /api/v1/xxx/resources`
+
+**用途：** 创建新资源
+
+**请求体：**
+```json
+{
+  "fieldName": "资源名称",      // 必填，长度2-200
+  "description": "描述",        // 可选，最大5000字
+  "status": "active"            // 可选，默认active
+}
+```
+
+**验证规则：**
+- `fieldName`: 必填，2-200字符，不能包含特殊字符
+- `description`: 可选，最大5000字符
+- `status`: 可选，有效值：active, inactive
+
+**请求示例：**
+```bash
+POST /api/v1/xxx/resources
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "fieldName": "新资源",
+  "description": "这是一个新资源"
+}
+```
+
+**成功响应：** `201 Created`
+```json
+{
+  "success": true,
+  "data": {
+    "id": 124,
+    "userId": 456,
+    "fieldName": "新资源",
+    "description": "这是一个新资源",
+    "status": "active",
+    "createdAt": "2025-11-06T10:00:00.000Z",
+    "updatedAt": "2025-11-06T10:00:00.000Z"
+  },
+  "message": "创建成功"
+}
+```
+
+**错误响应：**
+```json
+// 422 Unprocessable Entity
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "参数验证失败",
+    "details": [
+      { "field": "fieldName", "message": "字段名称不能为空" },
+      { "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
+    ]
+  }
+}
+
+// 409 Conflict
+{
+  "success": false,
+  "error": {
+    "code": "ALREADY_EXISTS",
+    "message": "该资源已存在"
+  }
+}
+```
+
+---
+
+### 4. 更新资源
+
+**端点：** `PUT /api/v1/xxx/resources/:id`
+
+**用途：** 更新指定资源（完整更新）
+
+**路径参数：**
+- `id` (必填): 资源ID
+
+**请求体：**
+```json
+{
+  "fieldName": "更新后的名称",
+  "description": "更新后的描述",
+  "status": "inactive"
+}
+```
+
+**请求示例：**
+```bash
+PUT /api/v1/xxx/resources/123
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "fieldName": "更新后的名称",
+  "description": "更新后的描述"
+}
+```
+
+**成功响应：** `200 OK`
+```json
+{
+  "success": true,
+  "data": {
+    "id": 123,
+    "fieldName": "更新后的名称",
+    "description": "更新后的描述",
+    "updatedAt": "2025-11-06T11:00:00.000Z"
+  },
+  "message": "更新成功"
+}
+```
+
+**错误响应：**
+```json
+// 404 Not Found
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "资源不存在"
+  }
+}
+
+// 403 Forbidden
+{
+  "success": false,
+  "error": {
+    "code": "FORBIDDEN",
+    "message": "无权修改此资源"
+  }
+}
+```
+
+---
+
+### 5. 删除资源
+
+**端点：** `DELETE /api/v1/xxx/resources/:id`
+
+**用途：** 删除指定资源（软删除）
+
+**路径参数：**
+- `id` (必填): 资源ID
+
+**请求示例：**
+```bash
+DELETE /api/v1/xxx/resources/123
+Authorization: Bearer <token>
+```
+
+**成功响应：** `200 OK`
+```json
+{
+  "success": true,
+  "data": null,
+  "message": "删除成功"
+}
+```
+
+**错误响应：**
+```json
+// 404 Not Found
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "资源不存在"
+  }
+}
+
+// 403 Forbidden
+{
+  "success": false,
+  "error": {
+    "code": "FORBIDDEN",
+    "message": "无权删除此资源"
+  }
+}
+
+// 409 Conflict
+{
+  "success": false,
+  "error": {
+    "code": "CANNOT_DELETE",
+    "message": "该资源有关联数据，无法删除"
+  }
+}
+```
+
+---
+
+## 🔐 认证与权限
+
+### 认证方式
+所有API都需要JWT Token认证：
+```
+Authorization: Bearer <token>
+```
+
+### 权限检查
+- 用户只能访问自己的资源
+- ADMIN角色可以访问所有资源
+
+---
+
+## 📊 错误码汇总
+
+| 错误码 | HTTP状态 | 说明 |
+|--------|---------|------|
+| UNAUTHORIZED | 401 | 未授权 |
+| FORBIDDEN | 403 | 无权限 |
+| NOT_FOUND | 404 | 资源不存在 |
+| VALIDATION_ERROR | 422 | 参数验证失败 |
+| ALREADY_EXISTS | 409 | 资源已存在 |
+| INTERNAL_ERROR | 500 | 服务器错误 |
+
+---
+
+## 🚀 使用示例
+
+### JavaScript/TypeScript
+```typescript
+// 获取资源列表
+const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+  },
+});
+const data = await response.json();
+
+// 创建资源
+const response = await fetch('/api/v1/xxx/resources', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    fieldName: '新资源',
+    description: '描述',
+  }),
+});
+```
+
+### cURL
+```bash
+# 获取列表
+curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
+  -H "Authorization: Bearer <token>"
+
+# 创建资源
+curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"fieldName":"新资源","description":"描述"}'
+```
+
+---
+
+## ⚠️ 注意事项
+
+**性能优化：**
+- 列表接口必须支持分页，默认pageSize=10，最大100
+- 避免返回过多关联数据，按需加载
+- 大量数据导出使用异步任务
+
+**安全性：**
+- 所有接口必须验证JWT Token
+- 必须检查资源归属（用户只能操作自己的资源）
+- 敏感字段不要返回（如密码）
+
+**向后兼容：**
+- API变更使用版本号（/api/v2）
+- 不要删除已有字段，只能标记为deprecated
+- 新增字段必须有默认值
+
+---
+
+## 🔗 相关文档
+
+**规范：**
+- [API设计规范](../../04-开发规范/02-API设计规范.md)
+- [API路由总览](../../04-开发规范/04-API路由总览.md)
+
+**数据库：**
+- [本模块数据库设计](./01-数据库设计.md)
+
+---
+
+**最后更新：** YYYY-MM-DD  
+**维护人：** 技术架构师
+
+
+
+
+
+
+
+
+
+
+
+
+
+