junhong_cmp_fiber/docs/account-management-refactor/API文档.md

# 账号管理 API 文档

## 统一认证接口 (`/api/auth/*`)

### 1. 登录

**路由**：`POST /api/auth/login`

**请求体**：
```json
{
  "username": "admin",      // 用户名或手机号（二选一）
  "phone": "13800000001",   //
  "password": "Password123" // 必填
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 86400,  // 24小时
    "user": {
      "id": 1,
      "username": "admin",
      "user_type": 1,
      "menus": [...],      // 菜单树
      "buttons": [...]     // 按钮权限
    }
  },
  "timestamp": 1638345600
}
```

### 2. 登出

**路由**：`POST /api/auth/logout`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

### 3. 刷新 Token

**路由**：`POST /api/auth/refresh-token`

**请求体**：
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 86400
  },
  "timestamp": 1638345600
}
```

### 4. 获取用户信息

**路由**：`GET /api/auth/me`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "phone": "13800000001",
    "user_type": 1,
    "shop_id": null,
    "enterprise_id": null,
    "status": 1,
    "menus": [...],
    "buttons": [...]
  },
  "timestamp": 1638345600
}
```

### 5. 修改密码

**路由**：`PUT /api/auth/password`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体**：
```json
{
  "old_password": "OldPassword123",
  "new_password": "NewPassword123"
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

---

## 账号管理接口 (`/api/admin/accounts/*`)

### 路由结构说明

**所有账号类型共享同一套接口**，通过请求体的 `user_type` 字段区分：
- `user_type: 2` - 平台用户
- `user_type: 3` - 代理账号（需提供 `shop_id`）
- `user_type: 4` - 企业账号（需提供 `enterprise_id`）

---

### 1. 创建账号

**路由**：`POST /api/admin/accounts`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体（平台账号）**：
```json
{
  "username": "platform_user",
  "phone": "13800000001",
  "password": "Password123",
  "user_type": 2  // 2=平台用户
}
```

**请求体（代理账号）**：
```json
{
  "username": "agent_user",
  "phone": "13800000002",
  "password": "Password123",
  "user_type": 3,  // 3=代理账号
  "shop_id": 10    // 必填
}
```

**请求体（企业账号）**：
```json
{
  "username": "enterprise_user",
  "phone": "13800000003",
  "password": "Password123",
  "user_type": 4,       // 4=企业账号
  "enterprise_id": 5    // 必填
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 100,
    "username": "platform_user",
    "phone": "13800000001",
    "user_type": 2,
    "status": 1,
    "created_at": "2025-02-02T10:00:00Z"
  },
  "timestamp": 1638345600
}
```

### 2. 查询账号列表

**路由**：`GET /api/admin/accounts?page=1&page_size=20&user_type=3&username=test&status=1`

**请求头**：
```
Authorization: Bearer {access_token}
```

**查询参数**：
- `page`：页码（默认 1）
- `page_size`：每页数量（默认 20，最大 100）
- `user_type`：账号类型（2=平台，3=代理，4=企业），不传则查询所有
- `username`：用户名（模糊搜索）
- `phone`：手机号（模糊搜索）
- `status`：状态（1=启用，2=禁用）

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 100,
        "username": "platform_user",
        "phone": "13800000001",
        "user_type": 2,
        "status": 1,
        "created_at": "2025-02-02T10:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  },
  "timestamp": 1638345600
}
```

### 3. 获取账号详情

**路由**：`GET /api/admin/accounts/:id`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 100,
    "username": "platform_user",
    "phone": "13800000001",
    "user_type": 2,
    "shop_id": null,
    "enterprise_id": null,
    "status": 1,
    "created_at": "2025-02-02T10:00:00Z",
    "updated_at": "2025-02-02T11:00:00Z"
  },
  "timestamp": 1638345600
}
```

### 4. 更新账号

**路由**：`PUT /api/admin/accounts/:id`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体**：
```json
{
  "username": "new_username",  // 可选
  "phone": "13900000001",      // 可选
  "status": 2                  // 可选（1=启用，2=禁用）
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 100,
    "username": "new_username",
    "phone": "13900000001",
    "status": 2,
    "updated_at": "2025-02-02T12:00:00Z"
  },
  "timestamp": 1638345600
}
```

### 5. 删除账号

**路由**：`DELETE /api/admin/accounts/:id`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

### 6. 修改账号密码

**路由**：`PUT /api/admin/accounts/:id/password`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体**：
```json
{
  "password": "NewPassword123"
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

### 7. 修改账号状态

**路由**：`PUT /api/admin/accounts/:id/status`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体**：
```json
{
  "status": 2  // 1=启用，2=禁用
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

### 8. 分配角色

**路由**：`POST /api/admin/accounts/:id/roles`

**请求头**：
```
Authorization: Bearer {access_token}
```

**请求体**：
```json
{
  "role_ids": [1, 2, 3]  // 角色 ID 数组，空数组表示清空所有角色
}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "account_id": 100,
      "role_id": 1,
      "created_at": "2025-02-02T12:00:00Z"
    },
    {
      "id": 2,
      "account_id": 100,
      "role_id": 2,
      "created_at": "2025-02-02T12:00:00Z"
    }
  ],
  "timestamp": 1638345600
}
```

### 9. 获取账号角色

**路由**：`GET /api/admin/accounts/:id/roles`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "role_name": "系统管理员",
      "role_code": "system_admin",
      "role_type": 2
    },
    {
      "id": 2,
      "role_name": "运营人员",
      "role_code": "operator",
      "role_type": 2
    }
  ],
  "timestamp": 1638345600
}
```

### 10. 移除角色

**路由**：`DELETE /api/admin/accounts/:account_id/roles/:role_id`

**请求头**：
```
Authorization: Bearer {access_token}
```

**响应**：
```json
{
  "code": 0,
  "msg": "success",
  "timestamp": 1638345600
}
```

---

## 错误码说明

### 认证相关

| 错误码 | 说明 |
|-------|------|
| 1001 | 缺失认证令牌 |
| 1002 | 无效或过期的令牌 |
| 1003 | 权限不足 |

### 账号管理相关

| 错误码 | 说明 |
|-------|------|
| 2001 | 用户名已存在 |
| 2002 | 手机号已存在 |
| 2003 | 账号不存在 |
| 2004 | 无权限操作该资源或资源不存在 |
| 2005 | 超级管理员不允许分配角色 |
| 2006 | 角色类型与账号类型不匹配 |

### 通用错误

| 错误码 | 说明 |
|-------|------|
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

---

## 权限说明

### 账号类型与权限

| 账号类型 | 值 | 可创建的账号类型 | 可访问的接口 |
|---------|---|---------------|------------|
| 超级管理员 | 1 | 所有 | 所有 |
| 平台用户 | 2 | 平台、代理、企业 | 所有账号管理 |
| 代理账号 | 3 | 自己店铺及下级店铺的代理、企业 | 自己店铺及下级的账号 |
| 企业账号 | 4 | 无 | **禁止访问账号管理** |

### 企业账号限制

企业账号访问账号管理接口会返回：
```json
{
  "code": 1003,
  "msg": "无权限访问账号管理功能",
  "timestamp": 1638345600
}
```

---

## 使用示例

### 创建不同类型账号

```javascript
// 1. 创建平台账号
POST /api/admin/accounts
{
  "username": "platform1",
  "phone": "13800000001",
  "password": "Pass123",
  "user_type": 2  // 平台用户
}

// 2. 创建代理账号
POST /api/admin/accounts
{
  "username": "agent1",
  "phone": "13800000002",
  "password": "Pass123",
  "user_type": 3,  // 代理账号
  "shop_id": 10    // 必填：归属店铺
}

// 3. 创建企业账号
POST /api/admin/accounts
{
  "username": "ent1",
  "phone": "13800000003",
  "password": "Pass123",
  "user_type": 4,       // 企业账号
  "enterprise_id": 5    // 必填：归属企业
}
```

### 查询不同类型账号

```javascript
// 1. 查询所有账号
GET /api/admin/accounts

// 2. 查询平台账号
GET /api/admin/accounts?user_type=2

// 3. 查询代理账号
GET /api/admin/accounts?user_type=3

// 4. 查询企业账号
GET /api/admin/accounts?user_type=4

// 5. 组合筛选（代理账号 + 启用状态）
GET /api/admin/accounts?user_type=3&status=1

// 6. 分页查询
GET /api/admin/accounts?page=2&page_size=50
```

---

## 相关文档

- [迁移指南](./迁移指南.md) - 接口迁移步骤
- [功能总结](./功能总结.md) - 重构内容和安全提升
- [OpenAPI 规范](../../docs/admin-openapi.yaml) - 机器可读的完整接口文档