feat: 完成 NestJS 后端核心底座开发 (M1-M6) 和 Ant Design Vue 前端迁移

主要更新： 1. 后端核心底座完成 (M1-M6)： - 健康检查、指标监控、分布式锁 - 事件总线、队列系统、事务管理 - 安全守卫、多租户隔离、存储适配器 - 审计日志、配置管理、多语言支持 2. 前端迁移到 Ant Design Vue： - 从 Element Plus 迁移到 Ant Design Vue - 完善 system 模块 (role/menu/dept) - 修复依赖和配置问题 3. 文档完善： - AI 开发工作流文档 - 架构约束和开发规范 - 项目进度跟踪 4. 其他改进： - 修复编译错误和类型问题 - 完善测试用例 - 优化项目结构
2025-08-27 11:24:22 +08:00
parent be07b9ffec
commit 1cd5d3bdef
696 changed files with 36708 additions and 16868 deletions
--- a/admin/docs/src/wwjcloud/openapi/standards/restful.md
+++ b/admin/docs/src/wwjcloud/openapi/standards/restful.md
@@ -0,0 +1,505 @@
+# RESTful API 设计规范
+
+::: info API 设计规范
+
+本文档定义了 wwjcloud 框架的 RESTful API 设计规范，确保 API 的一致性、可读性和可维护性。
+
+:::
+
+## 基本原则
+
+### 🎯 设计原则
+
+- **资源导向**：API 应该围绕资源进行设计
+- **无状态**：每个请求都应该包含完整的信息
+- **统一接口**：使用标准的 HTTP 方法
+- **可缓存**：支持缓存机制
+- **分层系统**：支持分层架构
+
+### 📝 命名规范
+
+- **URL 使用小写字母**：`/api/member/list`
+- **单词间使用连字符**：`/api/user-profile`
+- **避免使用下划线**：不推荐 `/api/user_profile`
+- **使用复数形式**：`/api/members` 而不是 `/api/member`
+
+## HTTP 方法
+
+### 🔍 GET - 获取资源
+
+**用途：** 获取资源列表或单个资源
+
+```http
+# 获取资源列表
+GET /api/members
+
+# 获取单个资源
+GET /api/members/123
+
+# 获取资源的子资源
+GET /api/members/123/orders
+
+# 查询参数
+GET /api/members?page=1&size=10&status=active
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "获取成功",
+  "data": {
+    "list": [...],
+    "total": 100,
+    "page": 1,
+    "size": 10
+  },
+  "timestamp": 1640995200
+}
+```
+
+### ➕ POST - 创建资源
+
+**用途：** 创建新资源
+
+```http
+# 创建资源
+POST /api/members
+
+# 请求体
+{
+  "username": "john_doe",
+  "email": "john@example.com",
+  "status": 1
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "创建成功",
+  "data": {
+    "id": 123,
+    "username": "john_doe",
+    "email": "john@example.com",
+    "status": 1,
+    "create_time": 1640995200
+  },
+  "timestamp": 1640995200
+}
+```
+
+### ✏️ PUT - 更新资源
+
+**用途：** 完整更新资源
+
+```http
+# 更新资源
+PUT /api/members/123
+
+# 请求体
+{
+  "username": "john_doe_updated",
+  "email": "john_updated@example.com",
+  "status": 1
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 123,
+    "username": "john_doe_updated",
+    "email": "john_updated@example.com",
+    "status": 1,
+    "update_time": 1640995200
+  },
+  "timestamp": 1640995200
+}
+```
+
+### 🔄 PATCH - 部分更新
+
+**用途：** 部分更新资源
+
+```http
+# 部分更新资源
+PATCH /api/members/123
+
+# 请求体
+{
+  "status": 0
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 123,
+    "status": 0,
+    "update_time": 1640995200
+  },
+  "timestamp": 1640995200
+}
+```
+
+### 🗑️ DELETE - 删除资源
+
+**用途：** 删除资源
+
+```http
+# 删除资源
+DELETE /api/members/123
+
+# 批量删除
+DELETE /api/members?ids=123,124,125
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "删除成功",
+  "data": null,
+  "timestamp": 1640995200
+}
+```
+
+## URL 设计
+
+### 📋 资源命名
+
+**使用名词而非动词：**
+
+```http
+# ✅ 正确
+GET /api/members
+POST /api/members
+PUT /api/members/123
+DELETE /api/members/123
+
+# ❌ 错误
+GET /api/getMembers
+POST /api/createMember
+PUT /api/updateMember
+DELETE /api/deleteMember
+```
+
+### 🔗 嵌套资源
+
+**表示资源间的关系：**
+
+```http
+# 获取用户的订单
+GET /api/members/123/orders
+
+# 获取用户的特定订单
+GET /api/members/123/orders/456
+
+# 为用户创建订单
+POST /api/members/123/orders
+```
+
+### 🔍 查询参数
+
+**用于过滤、排序、分页：**
+
+```http
+# 过滤
+GET /api/members?status=active&type=vip
+
+# 排序
+GET /api/members?sort=create_time&order=desc
+
+# 分页
+GET /api/members?page=1&size=10
+
+# 搜索
+GET /api/members?keyword=john
+
+# 组合使用
+GET /api/members?status=active&page=1&size=10&sort=create_time&order=desc
+```
+
+## 状态码规范
+
+### ✅ 成功状态码
+
+```http
+200 OK              # 请求成功
+201 Created         # 资源创建成功
+204 No Content      # 请求成功，无返回内容
+```
+
+### ❌ 客户端错误
+
+```http
+400 Bad Request     # 请求参数错误
+401 Unauthorized    # 未授权访问
+403 Forbidden       # 禁止访问
+404 Not Found       # 资源不存在
+405 Method Not Allowed  # 方法不允许
+409 Conflict        # 资源冲突
+422 Unprocessable Entity  # 请求格式正确但语义错误
+```
+
+### 🔧 服务器错误
+
+```http
+500 Internal Server Error  # 服务器内部错误
+502 Bad Gateway        # 网关错误
+503 Service Unavailable # 服务不可用
+```
+
+## 请求头规范
+
+### 📋 常用请求头
+
+```http
+# 内容类型
+Content-Type: application/json
+
+# 授权信息
+Authorization: Bearer <token>
+
+# 接受的内容类型
+Accept: application/json
+
+# 用户代理
+User-Agent: wwjcloud-client/1.0.0
+
+# 语言设置
+Accept-Language: zh-CN,zh;q=0.9,en;q=0.8
+```
+
+### 🔐 认证头
+
+```http
+# JWT Token
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# API Key
+X-API-Key: your-api-key
+
+# 自定义认证
+X-Auth-Token: your-auth-token
+```
+
+## 响应格式
+
+### 📊 统一响应结构
+
+```typescript
+interface ApiResponse<T = any> {
+  code: number;        // 状态码
+  message: string;     // 消息
+  data: T;            // 数据
+  timestamp: number;   // 时间戳
+}
+```
+
+### 📝 响应示例
+
+**成功响应：**
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "id": 123,
+    "username": "john_doe",
+    "email": "john@example.com"
+  },
+  "timestamp": 1640995200
+}
+```
+
+**错误响应：**
+```json
+{
+  "code": 400,
+  "message": "请求参数错误",
+  "data": null,
+  "timestamp": 1640995200
+}
+```
+
+**列表响应：**
+```json
+{
+  "code": 200,
+  "message": "获取成功",
+  "data": {
+    "list": [
+      {
+        "id": 123,
+        "username": "john_doe",
+        "email": "john@example.com"
+      }
+    ],
+    "total": 100,
+    "page": 1,
+    "size": 10
+  },
+  "timestamp": 1640995200
+}
+```
+
+## 版本控制
+
+### 🔢 版本策略
+
+**URL 版本控制：**
+
+```http
+# 版本 1
+GET /api/v1/members
+
+# 版本 2
+GET /api/v2/members
+```
+
+**请求头版本控制：**
+
+```http
+GET /api/members
+Accept: application/vnd.wwjcloud.v1+json
+```
+
+### 📋 版本命名
+
+- **主版本**：重大变更，不兼容
+- **次版本**：新功能，向后兼容
+- **修订版本**：Bug 修复，向后兼容
+
+## 错误处理
+
+### 🚨 错误响应格式
+
+```json
+{
+  "code": 400,
+  "message": "请求参数错误",
+  "data": {
+    "errors": [
+      {
+        "field": "email",
+        "message": "邮箱格式不正确"
+      },
+      {
+        "field": "username",
+        "message": "用户名不能为空"
+      }
+    ]
+  },
+  "timestamp": 1640995200
+}
+```
+
+### 📝 错误码规范
+
+**业务错误码：**
+```typescript
+// 成功
+200: '操作成功'
+201: '创建成功'
+
+// 客户端错误
+400: '请求参数错误'
+401: '未授权访问'
+403: '禁止访问'
+404: '资源不存在'
+409: '资源冲突'
+
+// 服务器错误
+500: '服务器内部错误'
+502: '网关错误'
+503: '服务不可用'
+```
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **使用 HTTPS**：所有 API 都应该使用 HTTPS
+2. **参数验证**：严格验证所有输入参数
+3. **错误处理**：提供详细的错误信息
+4. **文档化**：提供完整的 API 文档
+5. **版本控制**：使用版本控制管理 API 变更
+6. **限流控制**：实现 API 限流机制
+7. **监控日志**：记录 API 调用日志
+
+### ❌ 避免做法
+
+1. **不要使用动词**：URL 应该使用名词
+2. **不要暴露内部错误**：不要返回敏感的错误信息
+3. **不要过度设计**：保持 API 简单易用
+4. **不要忽略缓存**：合理使用缓存机制
+5. **不要忽略安全**：实现适当的安全措施
+
+## 示例
+
+### 📋 完整的 API 示例
+
+**会员管理 API：**
+
+```http
+# 获取会员列表
+GET /api/v1/members?page=1&size=10&status=active
+
+# 获取单个会员
+GET /api/v1/members/123
+
+# 创建会员
+POST /api/v1/members
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "username": "john_doe",
+  "email": "john@example.com",
+  "status": 1
+}
+
+# 更新会员
+PUT /api/v1/members/123
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "username": "john_doe_updated",
+  "email": "john_updated@example.com",
+  "status": 1
+}
+
+# 删除会员
+DELETE /api/v1/members/123
+Authorization: Bearer <token>
+```
+
+## 下一步
+
+::: tip 深入学习
+
+1. **查看响应格式规范**：了解统一的响应格式
+2. **阅读错误码规范**：了解错误码定义
+3. **参考开发规范**：遵循开发规范
+4. **查看最佳实践**：学习最佳实践
+
+:::
+
+::: warning 注意事项
+
+- 严格遵循 RESTful 设计原则
+- 保持 API 的一致性和可读性
+- 提供完整的错误处理
+- 实现适当的安全措施
+
+:::