game_server/docs/API文档.md

API 文档

用户管理接口

创建用户账户

管理员创建用户账户

接口地址： POST /api/admin/accounts

请求头：

Content-Type: application/json
Authorization: Bearer {token}

请求参数：

{
  "userType": "ADMIN",           // 必填，用户类型：ADMIN 或 AGENT
  "username": "newuser",         // 必填，用户名，3-64字符，只能包含字母、数字、下划线
  "password": "123456",          // 必填，密码，6-128字符
  "status": "ENABLED",           // 可选，状态：ENABLED 或 DISABLED，默认ENABLED
  "pointsBalance": 0             // 可选，积分余额（仅AGENT类型），默认0
}

成功响应（200）：

{
  "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 - 参数验证失败：

{
  "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 - 用户名已存在：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 409,
  "error": "Conflict",
  "message": "用户名已存在"
}

401 Unauthorized - 未授权：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 401,
  "error": "Unauthorized",
  "message": "访问被拒绝"
}

403 Forbidden - 权限不足：

{
  "timestamp": "2025-08-24T18:30:00.000",
  "status": 403,
  "error": "Forbidden",
  "message": "权限不足，无法创建用户"
}

用户自注册接口

接口地址： POST /api/users

请求头：

Content-Type: application/json

请求参数：

{
  "userType": "AGENT",           // 必填，用户类型：只能为 AGENT
  "username": "newagent",        // 必填，用户名，3-64字符
  "password": "123456",          // 必填，密码，6-128字符
  "pointsBalance": 0             // 可选，积分余额，默认0
}

成功响应（201）：

{
  "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. 简化的用户模型，去除了角色和显示名称等复杂字段

使用示例

创建管理员用户：

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

创建代理用户：

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
  }'

用户自注册：

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "AGENT",
    "username": "newuser",
    "password": "User123!"
  }'