shaguabijia-app-server/docs/api/admin-users-list.md

GET /admin/api/users — 用户列表(筛选+排序+分页)

所属:Admin·用户 组（前缀 /admin/api/users） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | ← 返回 API 索引

入参（query）

字段	类型	必填	默认	说明
phone	string	❌	null	手机号前缀匹配(phone LIKE '<值>%')
register_channel	string	❌	null	注册渠道,精确匹配
status	string	❌	null	用户状态,精确匹配:active / disabled / deleted
nickname	string	❌	null	昵称模糊匹配(ILIKE '%<值>%')
created_from / created_to	datetime	❌	null	注册时间范围(ISO 8601;按 UTC 比较)
last_login_from / last_login_to	datetime	❌	null	最近登录时间范围(ISO 8601;按 UTC 比较)
sort_by	string	❌	id	排序列:id / created_at / last_login_at
sort_order	string	❌	desc	asc / desc
limit	int	❌	20	1–100
cursor	int	❌	null	上一页 next_cursor(offset 偏移量)

出参

响应 200:{ items: AdminUserListItem[], next_cursor: int|null }(next_cursor=null 表示末页)

AdminUserListItem

字段	类型	说明
id	int	用户 id
phone	string	手机号
nickname	string | null	昵称,可空
register_channel	string	注册渠道
status	string	用户状态:active / disabled / deleted
wechat_openid	string | null	微信 openid,可空
created_at	datetime	注册时间(UTC)
last_login_at	datetime	上次登录时间(UTC)

错误码

• 401 未带/无效/过期 admin token、管理员被禁用(头带 WWW-Authenticate: Bearer)
• 422 limit 超出 1–100 范围 / sort_by·sort_order 不在白名单 / 日期格式不合法 / 字段类型不合法

说明

• 分页为 offset 偏移式(为支持任意列排序):cursor 传上一页返回的 next_cursor(实为 offset);next_cursor=null 即末页。代价:翻页期间数据变动可能错位一条,admin 低频场景可接受(同提现列表)。
• 排序:sort_by 限 id/created_at/last_login_at,非法值回落 id;同值再按 id 同向兜底,次序稳定。
• 筛选:phone 前缀、nickname 模糊(ILIKE)、register_channel/status 精确、created_*/last_login_* 时间范围;均可叠加。
• 关联用户表 user。
• 历史明细(金币流水、提现、比价、反馈等)不在本列表,走各自带 user_id 过滤的分页接口。