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

后台管理 · 小程序管理模块

本文件描述 /api/admin 下的被纳管小程序相关接口（增删改查）。公共约定（请求头、统一响应、鉴权中间件、错误码、配置）见 admin-api.md。

1. 接口列表

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

1.1 POST /api/admin/miniapps

新建被纳管小程序。

请求体

{
  "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）

{
  "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	每页条数。

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [ { "id": 1, "name": "示例小程序", "app_id": "wx123...", "status": 1 } ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

curl 示例

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）。

响应

{ "code": 0, "msg": "ok" }

1.6 PUT /api/admin/miniapps/:id/status

更新小程序状态（启用 / 停用）。

路径参数

参数	类型	说明
id	uint64	小程序主键。

请求体

{ "status": 1 }

字段	类型	必填	说明
status	int8	是	状态：0 停用，1 启用。仅允许这两个值，非法值返回 40000。

该接口仅更新 status 字段，不影响其它字段；常用于停用 / 启用小程序。

响应：返回更新后的 MiniProgram 对象（见 §2.1），app_secret 字段不返回。

curl 示例

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 鉴权的数据来源。