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 总览。