rbac

2026-10-25 22:47:13 +08:00
parent 897d6c4483
commit b34fba352b
20 changed files with 2615 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 后台管理 · 认证模块
+
+> 本文件描述 `/api/admin` 下的**认证相关**接口（登录、当前管理员信息）。公共约定（请求头、统一响应、鉴权中间件、错误码、配置）见 [admin-api.md](./admin-api.md)。
+
+## 1. 接口列表
+
+### 1.1 `POST /api/admin/login`
+
+后台管理员登录，签发 JWT。无需 `Authorization` 头。
+
+**请求体**
+
+```json
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `username` | string | 是 | 管理员账号（当前示例固定 `admin`）。 |
+| `password` | string | 是 | 密码（当前示例固定 `admin123`；生产应接 DB + 密码哈希）。 |
+
+**响应**
+
+```json
+{ "code": 0, "msg": "ok", "data": { "token": "<JWT>" } }
+```
+
+**curl 示例**
+
+```bash
+curl -X POST http://localhost:8080/api/admin/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+### 1.2 `GET /api/admin/info`
+
+受保护接口示例，需有效 JWT，返回当前管理员 ID。
+
+**请求头**：`Authorization: Bearer <JWT>`
+
+**响应**
+
+```json
+{ "code": 0, "msg": "ok", "data": { "admin_id": "1" } }
+```
+
+## 2. 备注
+
+- **后台账号**：`POST /api/admin/login` 当前为固定示例账号，生产环境需接入数据库与密码哈希校验。
@@ -0,0 +1,135 @@
+# 后台管理 · 小程序管理模块
+
+> 本文件描述 `/api/admin` 下的**被纳管小程序**相关接口（增删改查）。公共约定（请求头、统一响应、鉴权中间件、错误码、配置）见 [admin-api.md](./admin-api.md)。
+
+## 1. 接口列表
+
+所有接口均需在请求头携带 `Authorization: Bearer <JWT>`（由 `AdminAuth` 校验）。
+
+### 1.1 `POST /api/admin/miniapps`
+
+新建被纳管小程序。
+
+**请求体**
+
+```json
+{
+  "name": "示例小程序",
+  "description": "用于演示",
+  "app_id": "wx1234567890",
+  "app_secret": "secret-xxxx",
+  "status": 1,
+  "ext": "{\"k\":\"v\"}"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | 是 | 小程序名称。 |
+| `description` | string | 否 | 描述。 |
+| `app_id` | string | 是 | 微信 AppID，全局唯一。 |
+| `app_secret` | string | 是 | 微信 AppSecret（**不会在响应中返回**）。 |
+| `status` | int8 | 否 | 状态：`0` 停用，`1` 启用。缺省为 `1`。 |
+| `ext` | string | 否 | 扩展字段，必须为合法 JSON 字符串（允许空串）。 |
+
+**响应**：返回创建后的 `MiniProgram` 对象（见 §2.1），`app_secret` 字段不返回。
+
+### 1.2 `PUT /api/admin/miniapps/:id`
+
+按 ID 局部更新小程序。
+
+**路径参数**
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | uint64 | 小程序主键。 |
+
+**请求体**（所有字段均为可选，仅在提供时更新；`ext` 若提供需为合法 JSON）
+
+```json
+{
+  "name": "新名称",
+  "description": "新描述",
+  "app_secret": "new-secret",
+  "status": 0,
+  "ext": "{\"theme\":\"dark\"}"
+}
+```
+
+> 字段以指针区分「未提供」与「置空」；若全部为空则不更新，直接返回原记录。
+
+**响应**：返回更新后的 `MiniProgram` 对象。
+
+### 1.3 `GET /api/admin/miniapps/:id`
+
+查询单个小程序。
+
+**路径参数**：`id`（uint64）。
+
+**响应**：返回 `MiniProgram` 对象；不存在返回 `40400`。
+
+### 1.4 `GET /api/admin/miniapps`
+
+分页列表查询小程序。
+
+**查询参数**
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `status` | int8 | `-1`（全部） | 按状态筛选：`0` 停用，`1` 启用，`-1` 全部。 |
+| `page` | int | `1` | 页码，从 1 开始。 |
+| `size` | int | `20` | 每页条数。 |
+
+**响应**
+
+```json
+{
+  "code": 0,
+  "msg": "ok",
+  "data": {
+    "list": [ { "id": 1, "name": "示例小程序", "app_id": "wx123...", "status": 1 } ],
+    "total": 1,
+    "page": 1,
+    "size": 20
+  }
+}
+```
+
+**curl 示例**
+
+```bash
+curl "http://localhost:8080/api/admin/miniapps?status=1&page=1&size=20" \
+  -H "Authorization: Bearer <JWT>"
+```
+
+### 1.5 `DELETE /api/admin/miniapps/:id`
+
+软删除小程序（置 `deleted_at`）。
+
+**路径参数**：`id`（uint64）。
+
+**响应**
+
+```json
+{ "code": 0, "msg": "ok" }
+```
+
+## 2. 数据模型
+
+### 2.1 MiniProgram（被纳管小程序）
+
+| 字段 | 类型 | JSON | 说明 |
+| --- | --- | --- | --- |
+| `ID` | uint64 | `id` | 主键，自增。 |
+| `Name` | string | `name` | 名称。 |
+| `Description` | string | `description` | 描述。 |
+| `AppID` | string | `app_id` | 微信 AppID，全局唯一。 |
+| `AppSecret` | string | `app_secret` | **不返回**（json `-`）。 |
+| `Status` | int8 | `status` | `0` 停用，`1` 启用。 |
+| `Ext` | string | `ext` | 扩展 JSON 文本。 |
+| `CreatedAt` | time | `created_at` | 创建时间。 |
+| `UpdatedAt` | time | `updated_at` | 更新时间。 |
+
+## 3. 备注
+
+- **小程序管理**：本模块下的 `miniapps` 接口用于纳管微信小程序配置（增删改查），是小程序端 `X-App-ID` 鉴权的数据来源。
@@ -0,0 +1,133 @@
+# 后台管理 · 用户管理模块
+
+> 本文件描述 `/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;
+  ```