---
url: /docs/api-docs/v1/admin/users.md
---
# user（C 端用户管理）— 10 action

> 前缀：`/api/v1/admin/user/`（⚠️ 勿与 P0 `/api/v1/admin/users` admin 账号列表混淆）
> 权限：`USER_READ`（list/detail）· `USER_BAN`（ban/unban）· `USER_WRITE`（其余）— 仅 **super + operator**，it 一律 403
> 代码：`src/app/admin/interface/api/user_mgmt.py` + `application/usecase/user_*.py`

## 3.3.1 list —— 用户列表

`GET /api/v1/admin/user/list` · 权限 `USER_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `keyword` | string | ⬜ | — | phone / nickname 子串匹配 |
| `status` | string | ⬜ | — | 用户状态过滤 |
| `role` | string | ⬜ | — | 角色过滤 |
| `registered_from` | string | ⬜ | — | ISO 日期（含） |
| `registered_to` | string | ⬜ | — | ISO 日期（含） |

**响应 data**：`{ total, page, page_size, items: [UserSummary] }`

`UserSummary` 字段（⚠️ `phone` **脱敏** `138****1234`）：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 用户 id |
| `phone` | string | 脱敏手机号 |
| `nickname` | string | null | 昵称 |
| `role` | string | `normal` | `vip` | `svip` |
| `status` | string | `active` | `banned` | `deleted` |
| `is_online` | bool | 是否在线 |
| `registered_at` | string | ISO 注册时间 |
| `banned_until` | string | null | 封禁截止 |

**错误码**：`40201001` page/page\_size < 1 / 日期格式非法。

## 3.3.2 detail —— 用户详情

`GET /api/v1/admin/user/detail/{user_id}` · 权限 `USER_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `user` | object | UserSummary 全字段 + `phone`（**不脱敏** — 管理员视角）+ `ban_reason` + `must_change_password` + `deactivation_started_at` |
| `orders` | array | 近期订单 |
| `withdrawals` | array | 近期提现 |
| `login_devices` | array | 登录设备（含 `platform` 等） |

**错误码**：`40201101`（404）用户不存在。

## 3.3.3 ban —— 封禁用户

`POST /api/v1/admin/user/ban` · 权限 `USER_BAN`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `user_id` | string | ✅ | — | 目标用户 |
| `reason` | string | ✅ | — | 封禁原因 |
| `duration_days` | int | ⬜ | 7 | 封禁天数 |
| `note` | string | ⬜ | — | 备注（audit） |
| `force_kick` | bool | ⬜ | false | 在线用户强制踢出（在线且 false → `40201103`） |

**响应 data**：`{ "success": true, "banned_until": "<ISO>" }`

**错误码**：

| code | 场景 |
|---|---|
| `40201101` | 用户不存在（404） |
| `40201102` | 重复封禁（已封禁） |
| `40201103` | 在线用户需 `force_kick=true` 强制踢出 |
| `40201001` | 参数非法 |

## 3.3.4 unban —— 解封

`POST /api/v1/admin/user/unban` · 权限 `USER_BAN`

**请求 body**：`{ user_id✅, note? }`

**响应 data**：`{ "success": true }`

**错误码**：`40201101`（404）。

## 3.3.5 promote / 3.3.6 demote —— 提升 / 降级角色

`POST /api/v1/admin/user/promote` · `POST /api/v1/admin/user/demote` · 权限 `USER_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `user_id` | string | ✅ | 目标用户 |
| `target_role` | string | ✅ | 目标角色（promote 升 / demote 降） |
| `note` | string | ⬜ | 备注（audit） |

**响应 data**：`{ "success": true, "new_role": "<role>" }`

**错误码**：`40201101`（404）；`40201001` 角色非法 / 方向不符。

## 3.3.7 reset-password —— 重置用户密码

`POST /api/v1/admin/user/reset-password` · 权限 `USER_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `user_id` | string | ✅ | — | 目标用户 |
| `new_password` | string | ✅ | — | 新密码（scrypt 哈希落库） |
| `force_change_after_login` | bool | ⬜ | true | 下次登录强制改密 |

**响应 data**：`{ "success": true }`

**错误码**：`40201101`（404）；`40201001` 密码不符合策略。

## 3.3.8 delete —— 删除用户（⚠️ 高敏感）

`POST /api/v1/admin/user/delete` · 权限 `USER_WRITE` · **confirm\_text = `"DELETE"`**

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `user_id` | string | ✅ | 目标用户 |
| `reason` | string | ✅ | 删除原因 |
| `confirm_text` | string | ✅ | **必须逐字为 `"DELETE"`**，否则 `40201001`（400） |

**响应 data**：`{ "success": true, "deleted_at": "<ISO>" }`

**错误码**：

| code | 场景 |
|---|---|
| `40201101` | 用户不存在（404） |
| `40201104` | 有未完成订单（USER\_HAS\_PENDING\_ORDERS） |
| `40201105` | 注销流程未走完（USER\_DELETION\_INCOMPLETE） |
| `40201001` | confirm\_text 不匹配 / 参数非法 |

## 3.3.9 impersonate —— 模拟登录用户

`POST /api/v1/admin/user/impersonate` · 权限 `USER_WRITE`

**请求 body**：`{ user_id✅, reason✅ }`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `impersonate_token` | string | 模拟 token（以该用户身份调 C 端接口） |
| `expires_at` | string | ISO 过期时间（短时效） |

**错误码**：`40201101`（404）；`40201001` reason 缺失。
⚠️ audit `ADMIN_IMPERSONATE` **必写**（每次模拟全程留痕）。

## 3.3.10 invite —— 邀请用户（预置账号）

`POST /api/v1/admin/user/invite` · 权限 `USER_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `phone` | string | ✅ | — | 被邀请手机号 |
| `role` | string | ⬜ | `normal` | 预置角色 |
| `note` | string | ⬜ | — | 备注 |

**响应 data**：`{ "invite_code": "<code>", "expires_at": "<ISO>" }`

**错误码**：`40201001` 手机号格式 / role 非法。

***

## P0 legacy：admin 账号列表

`GET /api/v1/admin/users` · 鉴权 `require_role("super", "operator")`（P0 判定，非权限位）

**Query**：`page` / `page_size` / `role` / `status`

**响应 data**：`{ items, total, page, pageSize }`（⚠️ 此 P0 端点为 camelCase `pageSize`）

***

**本域错误码汇总**：`40201101`-`40201105`（§6.3）。通用失败见 [admin 总览](/api-docs/v1/admin/)。