game_server/docs/API文档.md

# 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!"
  }'
```