更新小程序

1. 接口定位

• 接口名称: 更新小程序
• 所属域: admin/applet
• 业务目标: 按小程序 ID 局部更新已存在的小程序配置

2. 请求定义

• Method: POST
• Path: /applet/update
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 对相同更新内容重复提交可视为幂等

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
id	是	string	要更新的小程序 ID
name	否	object	wrapper 字段，存在时更新名称
appID	否	object	wrapper 字段，存在时更新业务 AppID
icon	否	object	wrapper 字段，存在时更新图标
url	否	object	wrapper 字段，存在时更新访问地址
md5	否	object	wrapper 字段，存在时更新摘要
size	否	object	wrapper 字段，存在时更新安装包大小
version	否	object	wrapper 字段，存在时更新版本号
priority	否	object	wrapper 字段，存在时更新排序优先级
status	否	object	wrapper 字段，存在时更新状态
createTime	否	object	请求结构中存在，但当前更新逻辑不会处理该字段

wrapper 字段说明

• StringValue 风格字段使用：{ "value": "new-value" }
• Int64Value 风格字段使用：{ "value": 123 }
• UInt32Value 风格字段使用：{ "value": 1 }

字段约束

• 协议校验要求 id 不能为空。
• 服务端会先确认目标小程序存在。
• 更新字段必须至少传一个，否则返回 no update info。
• 局部更新转换规则：
  • name/appID/url/version 传空字符串会报错
  • md5 传入时会校验是否是长度正确的十六进制 MD5
  • size 传入时必须大于 0
  • status 传入时当前实现不会再次校验是否只能为 1/2

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

• 本接口成功时返回空对象（无业务字段）。

5. 业务规则

• 仅管理员可以调用。
• 更新流程是“先查存在性，再转更新字典，再执行 $set 更新”。
• 只有请求中显式传入的 wrapper 字段才会被更新；未传字段保持原值。

6. 错误码与失败场景

错误码	场景	典型报错
1001	id 为空	id is empty
1001	没有任何可更新字段	no update info
1001	name 传空字符串	name is empty
1001	appID 传空字符串	appID is empty
1001	url 传空字符串	url is empty
1001	md5 非合法 MD5	md5 is invalid
1001	size <= 0	size is invalid
1001	version 传空字符串	version is empty
-	目标小程序不存在或数据库更新失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

fetch("http://localhost:10009/applet/update", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440603",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "9b0cc4db-2ef0-4377-bb2b-3e7b2900be1d",
    name: { value: "OpenIM Docs Pro" },
    version: { value: "1.1.0" },
    status: { value: 2 },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "id": "9b0cc4db-2ef0-4377-bb2b-3e7b2900be1d",
  "name": {
    "value": "OpenIM Docs Pro"
  },
  "version": {
    "value": "1.1.0"
  },
  "status": {
    "value": 2
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "md5 is invalid"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 校验 id。
3. 查询目标小程序是否存在。
4. 将 wrapper 字段转换为数据库更新字典，并执行字段级校验。
5. 对目标记录执行 $set 更新并返回成功响应。

9. 变更记录

• 2026-03-31: 首版发布，基于小程序局部更新与 wrapper 字段处理逻辑补全文档。