169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
# 后台管理 · 小程序管理模块
|
||
|
||
> 本文件描述 `/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" }
|
||
```
|
||
|
||
### 1.6 `PUT /api/admin/miniapps/:id/status`
|
||
|
||
更新小程序状态（启用 / 停用）。
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | uint64 | 小程序主键。 |
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{ "status": 1 }
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `status` | int8 | 是 | 状态：`0` 停用，`1` 启用。仅允许这两个值，非法值返回 `40000`。 |
|
||
|
||
> 该接口仅更新 `status` 字段，不影响其它字段；常用于停用 / 启用小程序。
|
||
|
||
**响应**：返回更新后的 `MiniProgram` 对象（见 §2.1），`app_secret` 字段不返回。
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl -X PUT "http://localhost:8080/api/admin/miniapps/1/status" \
|
||
-H "Authorization: Bearer <JWT>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"status":0}'
|
||
```
|
||
|
||
## 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` | 创建时间，格式 `Y-m-d H:i:s`（如 `2026-10-26 15:04:05`）。 |
|
||
| `UpdatedAt` | time | `updated_at` | 更新时间，格式 `Y-m-d H:i:s`。 |
|
||
|
||
## 3. 备注
|
||
|
||
- **小程序管理**：本模块下的 `miniapps` 接口用于纳管微信小程序配置（增删改查），是小程序端 `X-App-ID` 鉴权的数据来源。
|