134 lines
3.8 KiB
Markdown
134 lines
3.8 KiB
Markdown
# 后台管理 · 用户管理模块
|
||
|
||
> 本文件描述 `/api/admin` 下的**小程序端用户**相关接口（列表、详情、编辑、禁用/启用）。公共约定（请求头、统一响应、鉴权中间件、错误码、配置）见 [admin-api.md](./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` | 每页条数。 |
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{
|
||
"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 示例**
|
||
|
||
```bash
|
||
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）。
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"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）。
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{ "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）：
|
||
```sql
|
||
ALTER TABLE users ADD COLUMN status TINYINT NOT NULL DEFAULT 1;
|
||
```
|