portal-mini-go/.codebuddy/docs/admin-user.md

后台管理 · 用户管理模块

本文件描述 /api/admin 下的小程序端用户相关接口（列表、详情、编辑、禁用/启用）。公共约定（请求头、统一响应、鉴权中间件、错误码、配置）见 admin-api.md。

1. 接口列表

所有接口均需在请求头携带 Authorization: Bearer <JWT>（由 AdminAuth 校验）。

1.1 GET /api/admin/users

分页列表查询小程序端用户，支持按小程序与关键字（昵称 / OpenID）过滤。

查询参数

参数	类型	默认值	说明
mini_id	uint64	0（全部）	按所属小程序筛选；0 表示不限小程序。
keyword	string	空	模糊匹配 nickname 或 openid（前后自动加 %）。
page	int	1	页码，从 1 开始。
size	int	20	每页条数。

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "mini_id": 10,
        "openid": "oABC...",
        "union_id": "",
        "nickname": "张三",
        "avatar": "https://...",
        "status": 1,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

curl 示例

curl "http://localhost:8080/api/admin/users?mini_id=10&keyword=张三&page=1&size=20" \
  -H "Authorization: Bearer <JWT>"

1.2 GET /api/admin/users/:id

查询单个用户详情（后台视角，不限小程序）。

路径参数

参数	类型	说明
id	uint64	用户主键。

响应：返回 User 对象（见 §2.1）；不存在返回 40400。

1.3 PUT /api/admin/users/:id

编辑用户资料（昵称 / 头像 / 状态）。字段均为可选，仅在提供时更新。

路径参数：id（uint64）。

请求体

{
  "nickname": "新昵称",
  "avatar": "https://new-avatar.png",
  "status": 0
}

字段	类型	必填	说明
nickname	string	否	昵称，提供即更新。
avatar	string	否	头像 URL，提供即更新。
status	int8	否	状态：0 禁用，1 正常；非法值返回 40000。

所有字段以指针区分「未提供」与「置空」；若全部为空则不更新，直接返回原记录。

响应：返回更新后的 User 对象。

1.4 POST /api/admin/users/:id/status

禁用 / 启用用户。

路径参数：id（uint64）。

请求体

{ "status": 0 }

字段	类型	必填	说明
status	int8	是（binding:required）	0 禁用，1 正常；非法值返回 40000。

响应：返回更新后的 User 对象。

2. 数据模型

2.1 User（小程序端用户）

字段	类型	JSON	说明
ID	uint64	id	主键，自增。
MiniID	uint64	mini_id	所属小程序（mini_programs.id）。
OpenID	string	openid	微信 OpenID，与 mini_id 共同唯一。
UnionID	string	union_id	微信 UnionID（可能为空）。
Nickname	string	nickname	昵称。
Avatar	string	avatar	头像 URL。
Status	int8	status	0 禁用，1 正常（默认 1）。
CreatedAt	time	created_at	创建时间。
UpdatedAt	time	updated_at	更新时间。

3. 备注

• 用户管理：/api/admin/users 下的接口用于后台管理各小程序端用户（列表、详情、编辑、禁用/启用）。User 模型新增的 status 字段需手动在数据库中加列后方可生效（因项目未开启 AutoMigrate）：

  ALTER TABLE users ADD COLUMN status TINYINT NOT NULL DEFAULT 1;