kefu/im/backend/docs/admin-create-user.md

管理端新增客户端用户

入口：管理端 → 用户管理 → 新增用户。必填中国大陆手机号、昵称和初始密码；性别、城市、简介可选。创建后列表自动定位到新用户，可继续编辑资料。

• 账号默认为正常、正式用户、普通会员状态、未认证；创建时不发短信、不创建登录会话。
• 初始密码必填，但不限制长度或字符组合，纯数字、纯字母、中文等均可。账号可在 App/H5 使用手机号和初始密码登录；请通过安全渠道交付密码，并提醒用户登录后修改。
• 手机号通过唯一索引防止重复（包括已停用或尚未释放手机号的账号），使用 AES-GCM 加密保存；密码以 bcrypt 哈希保存，超过 72 字节的密码使用 Argon2id，兼容已有账号。通用 HTTP 请求大小限制仍然生效。
• 账号、资料、隐私设置、通知设置和审计日志在同一事务内创建；任一写入失败会回滚。

接口与权限

POST /admin/v1/users，必须携带有效管理员令牌，并具备 users:create 权限。请求字段：phone、password、nickname，可选 gender（0/1/2）、city、bio。不接受设置会员、认证、测试标记或账号状态的额外字段。

成功返回通用响应中的 data: { id, publicId }，不返回密码或用户令牌。参数错误返回 HTTP 400，手机号重复返回 409，权限不足返回 403，数据库错误返回 500。

审计动作是 create_user，包含操作管理员、目标用户、星遇号、昵称、来源及操作 IP，不保存初始密码或完整手机号。

发布

1. 使用项目现有迁移流程执行 backend/migrations/029_admin_create_users.sql（此前的迁移必须已执行）。该迁移新增权限，并仅默认授予内置超级管理员角色。
2. 发布更新后的后端和管理端构建。管理端构建命令：在 admin 目录执行 pnpm --filter @vben/web-ele build。
3. 管理员重新登录以刷新权限；其他运营角色可在“管理员与权限”中按需勾选“新增客户端用户”，并保留“查看用户”以访问用户列表。

验证

go test ./internal/app -run TestAdminCreateUser -count=1 覆盖真实路由的认证和权限、参数校验、重复手机号保护、敏感数据保护、事务回滚、列表查询及密码登录。测试使用内存 SQL 适配器，不接触线上账号；真实数据库迁移和部署后仍需验收。