新增小程序

1. 接口定位

• 接口名称: 新增小程序
• 所属域: admin/applet
• 业务目标: 创建一条小程序记录，供客户端按上架状态展示

2. 请求定义

• Method: POST
• Path: /applet/add
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等；如果不传 id，每次都会生成新的 UUID

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
id	否	string	小程序记录 ID；为空时服务端自动生成 UUID
name	是	string	小程序名称
appID	是	string	业务侧小程序标识
icon	是	string	图标地址
url	是	string	小程序访问地址
md5	是	string	安装包摘要字符串
size	是	int64	安装包大小，必须大于 0
version	是	string	版本号
priority	否	uint32	排序优先级
status	是	uint32	状态：1 上架，2 下架
createTime	否	int64	请求字段存在，但服务端新增时不会使用该值

status 取值

值	含义
1	上架
2	下架

字段约束

• 协议校验要求：name、appID、icon、url、md5、version 不能为空，size > 0，status 必须在 1/2 之间。
• RPC 层还会再次校验：
  • name 非空，否则 name empty
  • appID 非空，否则 appid empty
  • status 只能是 1 或 2，否则 invalid status
• 当前新增逻辑不会校验 md5 是否真的是合法 MD5 字符串，只检查协议层的非空条件。

4. 响应结构

通用响应包裹

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

data 字段

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

5. 业务规则

• 仅管理员可以调用。
• 如果 id 为空，服务端会使用 UUID 自动生成记录主键。
• 实际写入字段包括：id/name/app_id/icon/url/md5/size/version/priority/status/createTime。
• createTime 始终取服务端当前时间，不使用请求中的 createTime 字段。

6. 错误码与失败场景

错误码	场景	典型报错
1001	name 为空	name is empty 或 name empty
1001	appID 为空	appID is empty 或 appid empty
1001	icon 为空	icon is empty
1001	url 为空	url is empty
1001	md5 为空	md5 is empty
1001	size <= 0	size is invalid
1001	version 为空	version is empty
1001	status 非 1/2	status is invalid 或 invalid status
-	id 唯一索引冲突或写入失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

fetch("http://localhost:10009/applet/add", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440601",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "OpenIM Docs",
    appID: "docs-center",
    icon: "https://example.com/applet.png",
    url: "https://example.com/applet/index.html",
    md5: "4e5d54f50370b936533dfcb2f3540a8b",
    size: 204800,
    version: "1.0.0",
    priority: 10,
    status: 1,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "name": "OpenIM Docs",
  "appID": "docs-center",
  "icon": "https://example.com/applet.png",
  "url": "https://example.com/applet/index.html",
  "md5": "4e5d54f50370b936533dfcb2f3540a8b",
  "size": 204800,
  "version": "1.0.0",
  "priority": 10,
  "status": 1
}

成功响应示例

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

失败响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 校验必填字段与状态。
3. 若未传 id，生成 UUID。
4. 组装小程序记录并写入数据库。
5. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，基于小程序新增与服务端自动生成 ID 逻辑补全文档。