EchoChat/docs/api/admin/user.md

管理端 — 用户管理 API

通用规范（认证方式、响应格式、错误码）见 README.md 以下所有接口均需要 JWT 认证 + admin/super_admin 角色

---

接口列表

方法	路径	权限	说明
GET	/api/v1/admin/users	admin	获取用户列表
GET	/api/v1/admin/users/:id	admin	获取用户详情
PUT	/api/v1/admin/users/:id/status	admin	更新用户状态
PUT	/api/v1/admin/users/:id/role	admin / super_admin	分配用户角色
POST	/api/v1/admin/users	admin	管理员创建用户
GET	/api/v1/admin/users/:id/meetings	admin	获取用户会议记录（Phase 3 实现）

---

1. 获取用户列表

GET /api/v1/admin/users

权限： admin

查询参数：

参数	类型	必填	默认值	说明
page	int	是	-	页码（从 1 开始）
page_size	int	是	-	每页数量（1-100）
keyword	string	否	无	搜索关键词（模糊匹配用户名或邮箱）
status	int	否	无	按状态筛选：1=正常，2=禁用，3=注销

成功响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "total": 100,
        "list": [
            {
                "id": 1,
                "username": "zhangsan",
                "email": "zhangsan@example.com",
                "nickname": "张三",
                "avatar": "",
                "gender": 1,
                "phone": "13800138000",
                "status": 1,
                "status_text": "正常",
                "roles": ["user"],
                "last_login_at": "2026-02-27 10:00:00",
                "last_login_ip": "192.168.1.100",
                "created_at": "2026-02-20 08:00:00",
                "updated_at": "2026-02-27 10:00:00"
            }
        ]
    }
}

---

2. 获取用户详情

GET /api/v1/admin/users/:id

权限： admin

成功响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "id": 1,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "nickname": "张三",
        "avatar": "",
        "gender": 1,
        "phone": "13800138000",
        "status": 1,
        "status_text": "正常",
        "roles": ["user"],
        "last_login_at": "2026-02-27 10:00:00",
        "last_login_ip": "192.168.1.100",
        "created_at": "2026-02-20 08:00:00",
        "updated_at": "2026-02-27 10:00:00"
    }
}

---

3. 更新用户状态

PUT /api/v1/admin/users/:id/status

权限： admin

请求参数：

字段	类型	必填	说明
status	int	是	目标状态：1=正常（启用），2=禁用

说明：

• 禁用用户后，该用户的所有活跃 Token 将被清除
• 不能禁用自己的账号（返回 400）
• 禁用后用户尝试登录将返回 403

成功响应：

{
    "code": 0,
    "message": "success",
    "trace_id": "...",
    "time": "2026-03-02 11:12:44"
}

---

4. 分配用户角色

PUT /api/v1/admin/users/:id/role

权限： admin / super_admin

请求参数：

字段	类型	必填	说明
role_code	string	是	角色代码：user / admin / super_admin

---

5. 管理员创建用户

POST /api/v1/admin/users

权限： admin

请求参数：

字段	类型	必填	说明
username	string	是	用户名，3-50 字符
email	string	是	邮箱地址
password	string	是	初始密码，6-50 字符
nickname	string	否	昵称（默认使用用户名）
role_code	string	否	指定角色，默认为 user

成功响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "id": 6,
        "username": "created_by_admin",
        "email": "admin_created@example.com",
        "nickname": "管理员创建",
        "avatar": "",
        "gender": 0,
        "status": 1,
        "status_text": "正常",
        "roles": ["user"],
        "created_at": "2026-03-02 11:12:33",
        "updated_at": "2026-03-02 11:12:33"
    },
    "trace_id": "...",
    "time": "2026-03-02 11:12:33"
}

---

6. 获取用户会议记录

GET /api/v1/admin/users/:id/meetings

权限： admin

查询参数：

参数	类型	默认值	说明
status	string	无	ongoing=进行中，upcoming=即将开始，ended=已结束
page	int	1	页码
page_size	int	20	每页数量