> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 服务通知接入（服务端）

> 本文面向负责业务服务端、MCP Server 和通知策略的开发者，说明如何为豆包应用插件配置通知模板，并在业务事件发生后向指定用户发送服务通知。

> 服务通知是业务服务端主动调用平台 OpenAPI 的能力，不要求为每条通知新增 MCP Tool、Widget 或 Page。只有通知需要落地页、通知设置页或对话入口时，才需要同步开发前端或 MCP 能力。

## 接入目标

服务通知适合订单状态变化、预约提醒、审核结果、服务完成等“业务事实已经发生，需要主动提醒用户”的场景。完整接入需要解决四件事：

1. 在 `business-templates.yaml` 中声明通知标题、摘要、展示字段和变量；
2. 将模板同步到当前应用并完成审核上线；
3. 业务服务端取得应用级 AccessToken 和目标用户 OpenID；
4. 按业务事件生成稳定幂等键，调用服务通知 OpenAPI 并记录结果。

标准链路为：

1. 业务事件发生后，按事件选择固定的 `template_id`；
2. 从可信账号绑定中取得目标用户 OpenID；
3. 获取并缓存应用级 AccessToken；
4. 构造模板变量和稳定的 `out_msg_id`；
5. 调用 `push_send`；
6. 当 `code == 0` 且 `notice_id` 非空时，记录为“平台已接受”，否则分类失败并按策略重试；
7. 最后使用真机确认用户侧展示。

> **结果口径：**&#x63A5;口返回 `notice_id` 只表示平台已接受发送请求，不等于通知已经送达，也不等于用户侧已经展示。实际展示必须通过真机观察确认。

## 名词解释

| 对象                        | 作用                  | 关键规则                              |
| ------------------------- | ------------------- | --------------------------------- |
| `business-templates.yaml` | 保存服务通知和远程任务的应用级业务模板 | 与 `manifest.yaml` 独立；标准布局下放在项目根目录 |
| `template_id`             | 开发者定义的通知模板稳定标识      | 字符串；通知模板与任务模板之间也不能重名              |
| `brief`                   | 通知列表或系统提醒中的摘要       | 必填、非空；可以引用已声明变量                   |
| `variable_list`           | 模板允许运行时传入的变量集合      | 所有占位符都必须声明；运行时变量值均为字符串            |
| `open_id`                 | 当前应用下的用户身份标识        | 必须来自可信账号绑定，不能接受客户端任意指定其他用户        |
| `out_msg_id`              | 开发者侧消息幂等键           | 同一业务事件重试必须复用                      |
| `notice_id`               | 平台侧通知 ID            | 仅代表平台接受请求后的资源标识                   |

## 接入前准备

| 顺序 | 开发者要完成的动作                                                                          | 关键产出            |
| -- | ---------------------------------------------------------------------------------- | --------------- |
| 1  | 创建豆包应用插件并获取 AppID、AppSecret                                                        | 应用级凭据           |
| 2  | 按 [登录接入（服务端）](/apps-plugin/docs/backend-development/login.md) 建立 OpenID 与业务账号的可信绑定 | 可定位目标用户的 OpenID |
| 3  | 明确通知触发事件、接收范围、用户关闭策略、落地页和重试策略                                                      | 通知业务规则          |
| 4  | 在项目根目录准备 `business-templates.yaml`                                                 | 可校验的通知模板        |
| 5  | 实现应用级 Token 缓存和通知发送记录                                                              | 安全、可恢复的发送链路     |

> AppSecret、AccessToken、完整 OpenID、完整通知正文和业务敏感字段只能存在于服务端安全边界，不得写入前端、Manifest、运行态 Skill、代码仓库或普通日志。

## 配置通知模板

标准项目布局：

```text
<project>/
├── manifest.yaml
└── business-templates.yaml
```

通知模板示例：

```yaml
schema_version: 1

notice_templates:
  - template_id: milk_tea_ready
    name: "奶茶制作完成通知"
    title: "你的{name}已经做好啦"
    brief: "{name}已制作完成，取餐码 {pickup_code}"

    variable_list:
      - name
      - pickup_code
      - store_name

    keywords:
      - keyword_key: pickup_code
        keyword_name: "取餐码"
        field_value: "{pickup_code}"

      - keyword_key: store_name
        keyword_name: "取餐门店"
        field_value: "{store_name}"
```

### 字段说明

| 字段               | 必填 | 说明                                |
| ---------------- | -- | --------------------------------- |
| `schema_version` | 是  | 当前固定为 `1`                         |
| `template_id`    | 是  | 应用内稳定业务标识；最长 128，只包含字母、数字、`_`、`-` |
| `name`           | 是  | 模板管理名称，不允许占位符                     |
| `title`          | 是  | 通知标题，可以引用已声明变量                    |
| `brief`          | 是  | 通知摘要，不能为空或只包含空格                   |
| `variable_list`  | 按需 | 模板变量集合；变量名以字母开头，只包含字母、数字和下划线      |
| `keywords`       | 是  | 通知卡片展示字段，至少一项                     |
| `keyword_key`    | 是  | 模板内稳定字段 key，不可重复                  |
| `keyword_name`   | 是  | 用户可见字段名，不允许变量                     |
| `field_value`    | 否  | 用户可见字段值；省略时默认使用 `{keyword_key}`   |

`brief` 应在用户不展开通知卡片时也能独立表达关键信息。只在 `brief` 中使用的变量同样必须加入 `variable_list`。

字段含义确定后，不要随意更改 `keyword_key`。同一事件如果用户授权语义或字段集合明显不同，应使用新的 `template_id`，不要用大量可选变量承载无关通知。

## 校验与同步模板

修改模板后先执行兼容校验：

```bash
dbx check --file ./business-templates.yaml --json
```

只同步业务模板，不提交新的前端、Manifest 或 Skill 版本时：

```bash
dbx config sync business-templates \
  --project <project-root> \
  --json
```

显式同步要求项目根目录存在 `business-templates.yaml`；文件不存在时命令失败。执行 `dbx build` 创建完整版本时，该文件会自动参与严格校验和同步；文件缺失则跳过，不会清空远端。必须检查 `config_sync_results` 中每个模板的结果，不能只看版本提交成功或命令退出码。

> 从本地 YAML 中删除模板不代表平台模板被删除或下线。删除、下线必须使用平台明确提供的管理操作。

## 获取调用凭证和目标用户

### 应用级 AccessToken

业务服务端使用 AppID、AppSecret 调用应用级 Token 接口，并按 `expires_in` 缓存复用。不要在每次通知发送前重新获取 Token，也不要让多个业务模块各自并发刷新。

建议使用统一 Token Provider，提供：

- 缓存与提前刷新；
- 并发 single-flight；
- 原子换新；
- Token 明确失效时最多强制刷新并重试一次；
- 不在日志中输出 Token。

### 目标用户 OpenID

目标 OpenID 必须来自当前应用下的可信账号绑定记录。业务服务端根据业务事件和账号关系决定接收人，不接受客户端传入任意 OpenID。

缺少可信 OpenID 时应停止发送并记录可诊断错误，不能使用固定测试用户、默认 OpenID 或其它身份 fallback。

## 发送服务通知

### 基本信息

| 名称           | 描述                                           |
| ------------ | -------------------------------------------- |
| HTTP Path    | `/api/miniapp_notify/v1/developer/push_send` |
| HTTP Method  | `POST`                                       |
| Content-Type | `application/json`                           |
| 鉴权           | `X-DB-AccessToken`                           |

服务端 API 域名以 [服务端 API 总览](/apps-plugin/docs/server-api/overview.md) 中当前环境说明为准。

### 请求头

| 字段                 | 必填 | 说明                              |
| ------------------ | -- | ------------------------------- |
| `X-DB-AccessToken` | 是  | 使用 AppID、AppSecret 获取的应用级 Token |
| `Content-Type`     | 是  | 固定为 `application/json`          |

### 请求体

| 字段                  | 必填 | 说明                                            |
| ------------------- | -- | --------------------------------------------- |
| `open_id`           | 是  | 当前应用下目标用户的 OpenID                             |
| `template_id`       | 是  | `business-templates.yaml` 中声明的通知模板 ID         |
| `channel_info_list` | 是  | JSON 字符串；服务通知使用 `["service_notice"]`          |
| `biz_data`          | 是  | JSON 字符串；内容为 `map<string,string>`，变量与模板声明精确匹配 |
| `out_msg_id`        | 建议 | 稳定消息幂等键；同一业务事件重试时复用                           |
| `jump_data`         | 否  | JSON 字符串；通知点击后的应用插件内部 Page 信息                 |
| `ext_data`          | 否  | JSON 字符串；只有平台当前协议明确要求时才传                      |

请求示例：

```json
{
  "open_id": "<user_open_id>",
  "template_id": "milk_tea_ready",
  "channel_info_list": "[\"service_notice\"]",
  "biz_data": "{\"name\":\"珍珠奶茶\",\"pickup_code\":\"A018\",\"store_name\":\"中关村店\"}",
  "out_msg_id": "milk-tea-order-20260722-001-ready",
  "jump_data": "{\"path\":\"pages/order/detail\",\"query\":\"order_id=20260722-001\"}"
}
```

`channel_info_list`、`biz_data` 和 `jump_data` 在外层协议中都是 JSON 字符串。实现时应使用语言 JSON 库完成内外两层序列化，不能手工拼接转义文本。

`jump_data` 只能指向当前应用插件内部已注册的 Page，不允许透传用户提供的任意外部 URL。

### 响应

```json
{
  "code": 0,
  "msg": "success",
  "log_id": "202607220001",
  "data": {
    "notice_id": "1234567890",
    "success_channel_list": ["service_notice"],
    "fail_channel_list": []
  }
}
```

只有 `code == 0` 且 `data.notice_id` 非空时，才能把本次记录更新为“平台已接受”。HTTP 200 但业务码非 0 时仍是业务失败。

## 幂等、重试与可观测性

1. 业务事件第一次进入发送流程时生成并持久化 `out_msg_id`；
2. 网络超时或可重试错误继续使用原 `out_msg_id`；
3. 模板、权限、变量等确定性错误不盲目重试；
4. 限流或短暂网络错误使用有上限的指数退避；
5. 保存模板 ID、脱敏用户标识、`out_msg_id`、平台结果码、耗时和 `log_id`；
6. 不记录 AccessToken、完整 OpenID、完整 `biz_data` 或敏感通知正文。

建议将通知状态至少拆分为：

| 状态     | 含义                            |
| ------ | ----------------------------- |
| 待发送    | 业务事件已落库，尚未调用平台                |
| 平台已接受  | `code == 0` 且返回 `notice_id`   |
| 平台拒绝   | 参数、模板、权限或业务校验失败               |
| 结果未知   | 请求超时，需使用同一 `out_msg_id` 重试或核对 |
| 用户侧已确认 | 仅在受控测试中实际观察到通知展示              |

## 调试与验收

### 模拟器调试

启动 `dbx dev` 创建 Sandbox Session 时，CLI/平台会将当前 Manifest 与可选 `business-templates.yaml` 加入 Session 创建请求。模板变化后：

1. 手动重新执行模板兼容校验；
2. 在 Web 调试面板撤回并重建 Session；
3. 使用模拟器链路实际注入的身份调用通知接口。

只刷新页面不会更新已有 Session。Session 创建成功也不代表模板已经正式同步，更不代表通知已在用户侧展示。

### 真机调试与正式上线

真机调试必须让 `business-templates.yaml` 与当前 Manifest、前端资源和其它产物一起进入该次调试包。模板单独同步或模拟器 Session 不能替代真机调试。

正式发送前必须确认：

- 模板已严格校验、同步成功、审核通过并处于可用状态；
- AppID、AppSecret、OpenID、AccessToken 和模板属于同一应用与环境；
- 接收范围、用户授权/关闭策略、频控和重试策略已明确；
- 使用受控测试账号验证，避免向真实用户批量发送测试通知。

## 常见问题

### 模板校验提示缺少 `brief`

每个通知模板都必须提供非空 `brief`。摘要中的占位符也必须加入 `variable_list`，运行时由 `biz_data` 提供。

### 接口提示变量不匹配

检查 `biz_data` 是否为字符串到字符串的 JSON 对象。所有声明变量都要提供，不能少传、多传，也不能传平台保留变量。

### HTTP 200，但没有收到通知

先检查响应业务 `code` 和 `notice_id`。即使平台已接受，也要分别检查模板状态、目标环境、目标 OpenID、成功渠道和真机展示；不能把 HTTP 200 直接视为送达。

### 网络重试后出现重复通知

确认同一业务事件是否复用了持久化的 `out_msg_id`。每次重试生成新 ID 会失去幂等保护。

### 模拟器接口成功，但看不到通知

模拟器是否提供通知展示入口取决于当前版本。没有实际观察到入口时，应记录为 `UNSUPPORTED` 或 `NOT VERIFIED`，不能由接口成功推断用户侧已展示。

## 上线检查

- `business-templates.yaml` 与 `manifest.yaml` 路径关系正确；
- 每个通知模板都有稳定且全局唯一的 `template_id`；
- `brief` 非空，标题、摘要和关键词中的变量均正确声明；
- 模板已完成严格校验、同步和审核上线；
- 应用级 Token 统一缓存和刷新，不在日志或前端暴露；
- OpenID 来自可信账号绑定；
- 同一业务事件使用稳定 `out_msg_id`；
- 参数错误与短暂错误采用不同重试策略；
- 平台接受、实际送达和用户侧展示分别记录；
- 已使用受控账号完成真机验证。
