Refactor account management DTOs by removing displayName and role fields from AccountCreateRequest, AccountUpdateRequest, and AccountResponse, and updating related logic in AccountService. Adjust alwaysApply setting in zh.mdc to false.

2025-08-24 18:41:57 +08:00
parent f37159e1fc
commit 1b3ce1040a
31 changed files with 240 additions and 46 deletions
--- a/docs/API文档.md
+++ b/docs/API文档.md
@@ -0,0 +1,199 @@
+# API 文档
+
+## 用户管理接口
+
+### 创建用户账户
+
+#### 管理员创建用户账户
+
+**接口地址：** `POST /api/admin/accounts`
+
+**请求头：**
+```
+Content-Type: application/json
+Authorization: Bearer {token}
+```
+
+**请求参数：**
+```json
+{
+  "userType": "ADMIN",           // 必填，用户类型：ADMIN 或 AGENT
+  "username": "newuser",         // 必填，用户名，3-64字符，只能包含字母、数字、下划线
+  "password": "123456",          // 必填，密码，6-128字符
+  "status": "ENABLED",           // 可选，状态：ENABLED 或 DISABLED，默认ENABLED
+  "pointsBalance": 0             // 可选，积分余额（仅AGENT类型），默认0
+}
+```
+
+**成功响应（200）：**
+```json
+{
+  "id": 2,
+  "userType": "ADMIN",
+  "username": "newuser",
+  "status": "ENABLED",
+  "pointsBalance": 0,
+  "createdAt": "2025-08-24T18:30:00.000",
+  "updatedAt": "2025-08-24T18:30:00.000"
+}
+```
+
+**错误响应：**
+
+**400 Bad Request - 参数验证失败：**
+```json
+{
+  "timestamp": "2025-08-24T18:30:00.000",
+  "status": 400,
+  "error": "Bad Request",
+  "message": "Validation failed",
+  "details": [
+    {
+      "field": "username",
+      "message": "用户名长度必须在3-64字符之间"
+    },
+    {
+      "field": "password",
+      "message": "密码长度必须在6-128字符之间"
+    }
+  ]
+}
+```
+
+**409 Conflict - 用户名已存在：**
+```json
+{
+  "timestamp": "2025-08-24T18:30:00.000",
+  "status": 409,
+  "error": "Conflict",
+  "message": "用户名已存在"
+}
+```
+
+**401 Unauthorized - 未授权：**
+```json
+{
+  "timestamp": "2025-08-24T18:30:00.000",
+  "status": 401,
+  "error": "Unauthorized",
+  "message": "访问被拒绝"
+}
+```
+
+**403 Forbidden - 权限不足：**
+```json
+{
+  "timestamp": "2025-08-24T18:30:00.000",
+  "status": 403,
+  "error": "Forbidden",
+  "message": "权限不足，无法创建用户"
+}
+```
+
+#### 用户自注册接口
+
+**接口地址：** `POST /api/users`
+
+**请求头：**
+```
+Content-Type: application/json
+```
+
+**请求参数：**
+```json
+{
+  "userType": "AGENT",           // 必填，用户类型：只能为 AGENT
+  "username": "newagent",        // 必填，用户名，3-64字符
+  "password": "123456",          // 必填，密码，6-128字符
+  "pointsBalance": 0             // 可选，积分余额，默认0
+}
+```
+
+**成功响应（201）：**
+```json
+{
+  "id": 3,
+  "userType": "AGENT",
+  "username": "newagent",
+  "status": "ENABLED",
+  "pointsBalance": 0,
+  "createdAt": "2025-08-24T18:30:00.000",
+  "updatedAt": "2025-08-24T18:30:00.000"
+}
+```
+
+### 接口说明
+
+#### 权限要求
+- **管理员接口** (`/api/admin/accounts`)：需要管理员权限，可以创建ADMIN和AGENT类型用户
+- **用户接口** (`/api/users`)：公开接口，只能创建AGENT类型用户
+
+#### 参数说明
+
+**userType（用户类型）：**
+- `ADMIN`：管理员用户
+- `AGENT`：代理用户
+
+**username（用户名）：**
+- 长度：3-64字符
+- 格式：只能包含字母、数字、下划线
+- 唯一性：系统内必须唯一
+
+**password（密码）：**
+- 长度：6-128字符
+- 存储：使用BCrypt加密存储
+- 安全：建议包含大小写字母、数字和特殊字符
+
+**status（状态）：**
+- 可选值：`ENABLED`（启用）、`DISABLED`（禁用）
+- 默认值：`ENABLED`
+
+**pointsBalance（积分余额）：**
+- 仅AGENT类型用户可以设置
+- 类型：整数，不能为负数
+- 默认值：0
+
+#### 业务规则
+1. 用户名在系统内必须唯一
+2. 密码使用BCrypt加密存储，无法解密
+3. 创建成功后账户默认状态为ENABLED
+4. 只有管理员可以创建ADMIN类型用户
+5. 简化的用户模型，去除了角色和显示名称等复杂字段
+
+#### 使用示例
+
+**创建管理员用户：**
+```bash
+curl -X POST http://localhost:8080/api/admin/accounts \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-token" \
+  -d '{
+    "userType": "ADMIN",
+    "username": "admin001",
+    "password": "Admin123!"
+  }'
+```
+
+**创建代理用户：**
+```bash
+curl -X POST http://localhost:8080/api/admin/accounts \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-token" \
+  -d '{
+    "userType": "AGENT",
+    "username": "agent001",
+    "password": "Agent123!",
+    "pointsBalance": 1000
+  }'
+```
+
+**用户自注册：**
+```bash
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userType": "AGENT",
+    "username": "newuser",
+    "password": "User123!"
+  }'
+```