用户管理

端点列表

方法	路径	说明	权限
GET	/api/v1/users	用户列表	scope=own 返回自身；scope=all 需管理员
GET	/api/v1/users/me	当前用户信息	已认证用户
GET	/api/v1/users/stats	用户统计	管理员
GET	/api/v1/users/{user_id}	用户详情	自身或管理员
PATCH	/api/v1/users/{user_id}	更新用户	自身或管理员
DELETE	/api/v1/users/{user_id}	删除用户	管理员
GET	/api/v1/users/{user_id}/permission	用户权限	自身或管理员
PATCH	/api/v1/users/{user_id}/permission	更新权限	管理员

用户信息响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-20T14:22:00Z",
  "phone": "138****8000",
  "nickname": "测试用户",
  "avatar_url": "https://cdn.example.com/avatar.jpg",
  "is_active": true,
  "foxcoins": 5000,
  "source": "web",
  "invited_by_id": null
}

关键字段说明

字段	类型	说明
id	UUID	用户唯一标识
phone	string	手机号（列表/他人查看时脱敏）
nickname	string | null	用户昵称
is_active	bool	账户是否启用
foxcoins	int	狐币余额（虚拟货币）
source	string	注册来源
invited_by_id	UUID | null	邀请人 ID

更新用户

PATCH /api/v1/users/{user_id}

{
  "nickname": "新昵称",
  "avatar_url": "https://cdn.example.com/new-avatar.jpg"
}

所有字段均为可选，仅发送需要更新的字段。

测试要点

测试建议

1. 权限隔离：普通用户只能查看/修改自己的信息，不能访问其他用户
2. 手机号脱敏：列表接口中手机号应部分隐藏
3. 管理员越权：普通用户尝试访问 /users/stats 或修改他人信息应返回 403
4. 删除保护：删除用户后其关联资源（对话、文件等）的处理行为
5. 狐币余额：余额不应出现负数，不足时相关操作应返回 402