txagent-y/docs/dev/admin-api/ADMIN-API-04-用户管理.md

ADMIN-API-04 用户管理（USER-A）

共 6 个接口：USER-A01~06

状态枚举映射

user.status（用户状态）：

DB值	API响应值	说明
1	active	正常
2	banned	已封禁
3	deactivated	已注销

user.role（用户角色）：

DB值	API响应值	说明
1	user	普通用户
2	creator	创作者

---

USER-A01 用户列表查询

项目	说明
接口路径	GET /admin/api/v1/users
接口用途	搜索和查看平台所有用户
权限要求	运营专员/客服（客服只读）
涉及表	user

接口逻辑：

1. 校验管理员权限（permission_key: user:view）
2. 查询 user 表，支持多维度筛选（读）
3. 按 created_at 倒序，支持分页

请求参数（Query）：

字段	类型	必选	说明
keyword	string	否	搜索关键词（匹配 username / profile.display_name / _id）
role	string	否	角色筛选：user/creator
status	string	否	状态筛选：active/banned/deactivated
startDate	string	否	注册开始日期（YYYY-MM-DD）
endDate	string	否	注册结束日期（YYYY-MM-DD）
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	用户列表
list[].userId	string	用户ID
list[].username	string	用户名
list[].nickname	string	昵称
list[].avatar	url	头像
list[].role	string	角色：user/creator
list[].status	string	状态：active/banned/deactivated
list[].registeredAt	timestamp	注册时间
list[].lastLoginAt	timestamp	最后登录时间
pagination	object	分页信息

---

USER-A02 用户详情

项目	说明
接口路径	GET /admin/api/v1/users/:userId
接口用途	查看单个用户的完整信息
权限要求	运营专员/客服
涉及表	user, wallet, recharge_order, user_subscription, wallet_transaction, follow, report

接口逻辑：

1. 校验管理员权限（permission_key: user:view）
2. 查询 user 表 获取用户基本信息 + profile（读）
3. 查询 wallet 获取余额信息和 total_recharge（读）
4. 查询 user_subscription 统计订阅数（读）
5. 查询 wallet_transaction 获取最近消费流水（读）
6. 查询 follow 统计关注/粉丝数（读）
7. 查询 report 统计被举报次数（读）
8. 组装返回

路径参数：

字段	类型	必选	说明
userId	string	是	用户ID

请求参数： 无

响应数据：

字段	类型	说明
userId	string	用户ID
username	string	用户名
nickname	string	昵称
avatar	url	头像
bio	string	简介
gender	number	性别
role	string	角色：user/creator
status	string	状态：active/banned/deactivated
registeredAt	timestamp	注册时间
lastLoginAt	timestamp	最后登录时间
wallet	object	钱包信息
wallet.balance	number	余额（糖心币）
wallet.frozenBalance	number	冻结余额
wallet.totalRecharge	number	累计充值（糖心币）
stats	object	统计数据
stats.followerCount	number	粉丝数
stats.followingCount	number	关注数
stats.subscriptionCount	number	订阅数
stats.reportedCount	number	被举报次数
recentTransactions	array	最近10条消费流水
recentTransactions[].type	string	流水类型
recentTransactions[].amount	number	金额
recentTransactions[].createdAt	timestamp	时间

---

USER-A03 封禁用户

项目	说明
接口路径	POST /admin/api/v1/users/:userId/ban
接口用途	封禁违规用户
权限要求	运营专员
涉及表	user, user_device, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: user:ban）
2. 查询 user，校验 status=1（正常）（读）
3. 更新 user 的 status=2（已封禁）（更新）
4. 将 user_device 中该用户所有 is_active=1 的记录更新为 is_active=0（踢下线）（更新）
5. 写入 admin_operation_log（action: ban_user，detail 含封禁原因）（写）

[待确认] 创作者被封禁后，其内容和现有订阅用户的处理方式需产品方确认。当前建议：内容保持原状但不展示、现有订阅到期自然结束。

路径参数：

字段	类型	必选	说明
userId	string	是	用户ID

请求参数（Body）：

字段	类型	必选	说明
reason	string	是	封禁原因

响应数据：

字段	类型	说明
userId	string	用户ID
status	string	更新后状态：banned

---

USER-A04 解封用户

项目	说明
接口路径	POST /admin/api/v1/users/:userId/unban
接口用途	解除用户封禁
权限要求	运营专员
涉及表	user, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: user:ban）
2. 查询 user，校验 status=2（已封禁）（读）
3. 更新 user 的 status=1（正常）（更新）
4. 写入 admin_operation_log（action: unban_user）（写）

路径参数：

字段	类型	必选	说明
userId	string	是	用户ID

请求参数： 无

响应数据：

字段	类型	说明
userId	string	用户ID
status	string	更新后状态：active

---

USER-A05 创作者列表查询

项目	说明
接口路径	GET /admin/api/v1/creators
接口用途	专门查看创作者列表
权限要求	运营专员
涉及表	user, creator_profile, wallet

接口逻辑：

1. 校验管理员权限（permission_key: creator:view）
2. 查询 user 表（role=2），关联 creator_profile 和 wallet（读）
3. 支持按收入/粉丝数排序
4. 支持分页

请求参数（Query）：

字段	类型	必选	说明
keyword	string	否	搜索关键词
sortBy	string	否	排序字段：revenue/followers/subscribers/posts，默认 revenue
sortOrder	string	否	排序方向：asc/desc，默认 desc
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	创作者列表
list[].userId	string	用户ID
list[].nickname	string	昵称
list[].avatar	url	头像
list[].followerCount	number	粉丝数
list[].subscriberCount	number	订阅数
list[].totalRevenue	number	总收入（糖心币）
list[].postCount	number	内容数
list[].status	string	状态：active/banned
list[].registeredAt	timestamp	注册时间
pagination	object	分页信息

---

USER-A06 创作者详情

项目	说明
接口路径	GET /admin/api/v1/creators/:creatorId
接口用途	查看创作者的完整运营数据
权限要求	运营专员
涉及表	user, creator_profile, wallet, revenue_share_record, user_subscription, follow, post, subscription_tier, withdrawal_order

接口逻辑：

1. 校验管理员权限（permission_key: creator:view）
2. 查询 user + creator_profile 获取基本信息（读）
3. 查询 wallet 获取余额；聚合 revenue_share_record（creator_id 匹配）按 order_type 分组统计订阅收入/PPV收入（读）
4. 查询 follow 统计粉丝增长趋势（近30天）（读）
5. 查询 post 获取内容列表概要（读）
6. 查询 subscription_tier 获取订阅档位设置（读）
7. 查询 withdrawal_order 获取提现记录概要（读）
8. 组装返回

路径参数：

字段	类型	必选	说明
creatorId	string	是	创作者ID

请求参数： 无

响应数据：

字段	类型	说明
userId	string	用户ID
nickname	string	昵称
avatar	url	头像
bio	string	简介
status	string	状态
registeredAt	timestamp	注册时间
revenue	object	收入概要
revenue.totalRevenue	number	总收入（糖心币）
revenue.subscriptionRevenue	number	订阅收入（来源：revenue_share_record order_type=1）
revenue.ppvRevenue	number	PPV收入（来源：revenue_share_record order_type=2）
stats	object	统计数据
stats.followerCount	number	粉丝数
stats.subscriberCount	number	订阅数
stats.postCount	number	内容数
stats.followerGrowth	array	近30天粉丝增长（日维度）
subscriptionTiers	array	订阅档位列表
subscriptionTiers[].tierId	string	档位ID
subscriptionTiers[].name	string	档位名称
subscriptionTiers[].price	number	价格（糖心币/月）
recentWithdrawals	array	最近5条提现记录
recentWithdrawals[].amount	number	提现金额
recentWithdrawals[].status	string	状态
recentWithdrawals[].createdAt	timestamp	申请时间