feat: message-api for mission via wecomm agent

2026-05-14 09:30:38 +08:00
parent 9359013b4c
commit f409f2e6ee
38 changed files with 2085 additions and 49 deletions
--- a/docs/MESSAGE_API.md
+++ b/docs/MESSAGE_API.md
@@ -0,0 +1,165 @@
+# 消息发送 API
+
+这组 API 用于对外主动发送企业微信应用消息。
+
+当前提供两个接口：
+
+- `POST /api/message/send`：发送文本消息
+- `POST /api/message/send/news`：发送单篇图文消息，可同时投递到多个 `agent_id`
+
+## 鉴权
+
+仅这组消息发送 API 需要固定 `Authorization` 请求头。
+
+服务端读取环境变量：
+
+- `MESSAGE_API_AUTHORIZATION`
+
+默认值：
+
+- `hophopkk`
+
+请求示例：
+
+```http
+Authorization: hophopkk
+Content-Type: application/json
+```
+
+鉴权失败时返回：
+
+```json
+{
+  "detail": "Invalid Authorization header"
+}
+```
+
+HTTP 状态码：`401 Unauthorized`
+
+## 发送文本消息
+
+### 请求
+
+`POST /api/message/send`
+
+```json
+{
+  "agent_id": 1000007,
+  "content": "库存盘点将在 18:00 开始",
+  "user_ids": ["zhangsan", "lisi"]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `agent_id` | integer | 是 | 企业微信应用 ID |
+| `content` | string | 是 | 文本内容，1-2048 字节 |
+| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
+
+### 成功响应
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok"
+}
+```
+
+### curl 示例
+
+```bash
+curl -X POST 'http://localhost:8198/api/message/send' \
+  -H 'Authorization: hophopkk' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "agent_id": 1000007,
+    "content": "库存盘点将在 18:00 开始",
+    "user_ids": ["zhangsan", "lisi"]
+  }'
+```
+
+## 发送图文消息
+
+### 请求
+
+`POST /api/message/send/news`
+
+```json
+{
+  "agent_ids": [1000007, 1000008],
+  "title": "销售日报",
+  "description": "点击查看今日各区域销售汇总",
+  "url": "https://example.com/reports/daily-sales",
+  "image_url": "https://example.com/static/daily-sales-cover.png",
+  "user_ids": ["zhangsan"]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `agent_ids` | integer[] | 是 | 目标应用 ID 列表，至少 1 个 |
+| `title` | string | 是 | 图文标题，1-128 字符 |
+| `description` | string | 是 | 图文描述，1-512 字符 |
+| `url` | string | 是 | 点击跳转链接 |
+| `image_url` | string | 是 | 封面图片 URL，直接映射到企业微信 `picurl` |
+| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
+
+### 成功响应
+
+至少一个 `agent_id` 发送成功时返回 `200`，并带每个应用的发送结果：
+
+```json
+{
+  "results": [
+    {
+      "agent_id": 1000007,
+      "ok": true,
+      "response": {
+        "errcode": 0,
+        "errmsg": "ok"
+      },
+      "error": null
+    },
+    {
+      "agent_id": 1000008,
+      "ok": false,
+      "response": null,
+      "error": "agent not found"
+    }
+  ]
+}
+```
+
+如果所有 `agent_id` 都失败，则返回 `502 Bad Gateway`：
+
+```json
+{
+  "detail": "All agent sends failed"
+}
+```
+
+### curl 示例
+
+```bash
+curl -X POST 'http://localhost:8198/api/message/send/news' \
+  -H 'Authorization: hophopkk' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "agent_ids": [1000007, 1000008],
+    "title": "销售日报",
+    "description": "点击查看今日各区域销售汇总",
+    "url": "https://example.com/reports/daily-sales",
+    "image_url": "https://example.com/static/daily-sales-cover.png",
+    "user_ids": ["zhangsan"]
+  }'
+```
+
+## 发布建议
+
+- 如果要对外给第三方系统调用，至少同步交付这份文档和环境变量名 `MESSAGE_API_AUTHORIZATION`
+- 当前是固定密钥模式，适合内网或受控系统对接，不适合开放互联网暴露
+- 如果后续要接入更多对外方，建议升级为签名、时间戳或短期 token 模式
--- a/docs/WECOM_APP_INTEGRATION_GUIDE.md
+++ b/docs/WECOM_APP_INTEGRATION_GUIDE.md
@@ -0,0 +1,412 @@
+# 企业微信应用接入说明
+
+本文档面向企业微信自建应用开发组，说明当前 AI Agent 的接入方式、适合的消息入口、菜单和提问引导建议、能力边界，以及消息处理侧需要注意的事项。
+
+## 1. 目标
+
+当前 Agent 不是通用对话机器人，而是一个“受约束的业务查询助手”。
+
+它适合处理以下两类问题：
+
+1. MES / 出货 / 运输车辆等业务数据查询。
+2. 指定客户的财务记录查询。
+
+它不适合承担以下职责：
+
+1. 开放式闲聊。
+2. 多轮澄清式对话。
+3. 写入、审批、修改业务数据。
+4. 复杂统计分析和自定义报表。
+
+因此，企业微信侧的入口设计应尽量采用“菜单驱动 + 明确提问”的方式，而不是把它当成一个无限制聊天窗口。
+
+## 2. 当前调用入口
+
+当前服务对外提供的 Agent 入口为：
+
+- `POST /agent`
+
+健康检查：
+
+- `GET /health`
+
+当前请求体：
+
+```json
+{
+  "message": "查询华东未出货出货单",
+  "merchant_id": 1
+}
+```
+
+当前响应体：
+
+```json
+{
+  "reply": "目前查询到华东区域没有未出货的出货单（结果为0条）。"
+}
+```
+
+说明：
+
+- `message` 为发送给 Agent 的自然语言问题。
+- `merchant_id` 目前只对商户隔离型业务 API 生效。
+- 财务查询当前不依赖 `merchant_id`。
+- 返回值是自然语言文本，面向企业微信 markdown 消息渲染。
+
+## 3. 当前能力范围
+
+### 3.1 商户业务查询
+
+当前已接入以下业务能力：
+
+1. 查询 MES 设备列表。
+2. 查询指定日期范围内的 MES 生产安排。
+3. 查询运输车辆详情。
+4. 查询未进入送货单的出货单。
+
+这些能力依赖：
+
+- `merchant_id`
+
+因此企业微信应用侧如果要接这类查询，建议在进入 Agent 前就明确当前商户身份，或由调用方稳定注入 `merchant_id`。
+
+### 3.2 财务查询
+
+当前已接入以下财务记录类型：
+
+1. 销售记录
+2. 销退记录
+3. 收款记录
+4. 退款记录
+
+财务查询支持：
+
+- 单选一种记录类型
+- 多选多种记录类型
+- 宽泛的“财务记录”查询
+
+财务查询还能区分：
+
+1. 真实资金变动
+2. 挂账 / 冲减 / 欠款调整
+
+## 4. 当前明确不支持的能力
+
+企业微信应用开发组应优先在入口侧理解这些边界，因为这些能力不应引导给 Agent。
+
+### 4.1 不支持写操作
+
+当前不支持：
+
+1. 写入财务数据
+2. 修改财务数据
+3. 删除财务数据
+4. 审批财务数据
+5. 纠正财务数据
+6. 写入业务单据
+
+如果用户发起这类请求，推荐在企业微信应用侧直接拦截，或允许 Agent 返回标准拒绝说明。
+
+### 4.2 不支持复杂统计
+
+当前财务接口只支持“查记录”，不支持复杂统计分析。
+
+允许的上限只有：
+
+1. 对返回记录做直接计数。
+2. 对返回记录做直接累计。
+
+当前不支持：
+
+1. 按季度汇总
+2. 按月汇总
+3. 按年汇总
+4. 环比
+5. 同比
+6. 趋势分析
+7. 占比分析
+8. 分组统计
+9. 筛选后再累计
+10. 小计、分类汇总、派生统计口径
+
+如果企业微信应用已经能判断是这类诉求，建议不要直接把这类问题送给 Agent。
+
+## 5. 企业微信消息渲染约束
+
+当前 Agent 的回复是按企业微信应用消息中的 markdown 消息来约束的。
+
+已知约束如下：
+
+1. 企业微信 markdown 只支持 markdown 子集。
+2. `content` 最长不超过 `2048` 字节，UTF-8 编码。
+3. 当前 Agent 会尽量把回复压缩在约 `1200` 字节以内。
+4. 不应使用表格。
+5. 不应使用 fenced code block。
+6. 不应使用复杂嵌套列表。
+7. 不应依赖复杂 HTML 排版。
+
+当前更适合的展示形式：
+
+1. 一段简洁结论。
+2. 2 到 5 条短列表。
+3. 必要时附少量关键字段。
+
+因此，企业微信应用侧不应期待 Agent 返回：
+
+1. 表格型结果
+2. 长篇报告
+3. 大批量明细完整铺开
+
+## 6. 入口设计建议
+
+### 6.1 推荐采用单入口调用，多菜单引导
+
+当前技术上只需要一个 Agent 接口入口：
+
+- `POST /agent`
+
+但在企业微信应用层，建议不要只给一个“自由提问”入口。更合适的是：
+
+1. 菜单项负责限定业务范围。
+2. 菜单点击后，用明确提示语引导用户输入必要字段。
+3. 应用层把整理后的自然语言问题发送给 `/agent`。
+
+换句话说，推荐是“多个菜单入口，共用一个 Agent API”。
+
+### 6.2 推荐菜单分组
+
+建议至少拆成两大类：
+
+1. 生产/物流类查询
+2. 财务类查询
+
+财务类再细分为：
+
+1. 查询客户销售记录
+2. 查询客户销退记录
+3. 查询客户收款记录
+4. 查询客户退款记录
+5. 查询客户全部财务记录
+
+生产/物流类可拆为：
+
+1. 查询 MES 设备
+2. 查询生产安排
+3. 查询车辆信息
+4. 查询未出货出货单
+
+## 7. 提问引导建议
+
+### 7.1 总原则
+
+企业微信侧不应引导用户输入过于自由的问题，而应尽量引导输入“Agent 已支持的字段”。
+
+推荐原则：
+
+1. 一次只问一类问题。
+2. 提示词里直接说明需要提供什么。
+3. 对关键参数给示例。
+4. 不要让用户猜系统支持哪些写法。
+
+### 7.2 财务类推荐引导文案
+
+#### 查询客户销售记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的销售记录
+```
+
+#### 查询客户销退记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的销退记录
+```
+
+#### 查询客户收款记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的收款记录
+```
+
+#### 查询客户退款记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的退款记录
+```
+
+#### 查询客户全部财务记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的财务记录
+```
+
+#### 查询挂账或冲减
+
+推荐引导：
+
+```text
+请输入客户名称，并明确说明挂账或冲减，例如：查询杭州某客户的收款挂账调整记录
+```
+
+### 7.3 生产/物流类推荐引导文案
+
+#### 查询 MES 设备
+
+推荐引导：
+
+```text
+请输入查询需求，例如：查询当前商户的 MES 设备
+```
+
+#### 查询生产安排
+
+推荐引导：
+
+```text
+请输入日期范围，例如：查询 2026-05-01 到 2026-05-07 的生产安排
+```
+
+#### 查询车辆信息
+
+推荐引导：
+
+```text
+请输入车牌号，例如：查询车牌 粤A12345 的车辆信息
+```
+
+#### 查询未出货出货单
+
+推荐引导：
+
+```text
+请输入地区，例如：查询华东未出货出货单
+```
+
+## 8. 建议的应用层预处理
+
+企业微信应用侧建议做以下最小预处理：
+
+1. 注入 `merchant_id`，如果当前入口属于商户业务场景。
+2. 保留用户原始问题，不要做过度改写。
+3. 可以在菜单点击后，补一个简短上下文前缀，例如：
+   - `当前是财务查询场景：查询杭州某客户的销退记录`
+   - `当前是生产安排查询场景：查询 2026-05-01 到 2026-05-07 的生产安排`
+4. 不要在应用层生成复杂长提示词，避免和 Agent 提示词互相冲突。
+
+## 9. 建议的应用层拦截规则
+
+以下问题建议在企业微信应用层直接拦截，或者至少标记为“超出当前 Agent 支持范围”：
+
+1. `帮我新增一条财务记录`
+2. `把这个客户的退款改掉`
+3. `审批这笔收款`
+4. `按季度汇总这个客户的销售和回款`
+5. `统计今年每个月的销退趋势`
+6. `按地区筛选后累计某客户收款`
+
+推荐返回说明：
+
+```text
+当前入口只支持记录查询，不支持写入、修改、审批或复杂统计分析。
+```
+
+## 10. 建议的调用方式
+
+### 10.1 财务查询示例
+
+```json
+{
+  "message": "查询杭州某客户的销退记录"
+}
+```
+
+### 10.2 商户业务查询示例
+
+```json
+{
+  "message": "查询华东未出货出货单",
+  "merchant_id": 1
+}
+```
+
+### 10.3 财务能力说明类示例
+
+```json
+{
+  "message": "你可以查询哪些财务数据？是否可以多选？"
+}
+```
+
+期望回答方向：
+
+1. 支持销售、销退、收款、退款。
+2. 可以单选，也可以多选。
+3. 如果问“财务记录”，可以查全部四类。
+
+## 11. 推荐的消息处理流程
+
+推荐流程如下：
+
+1. 用户点击菜单。
+2. 企业微信应用展示该菜单对应的引导语。
+3. 用户输入问题。
+4. 应用层判断是否需要补 `merchant_id`。
+5. 应用层判断是否属于明显超范围请求。
+6. 如果在支持范围内，则调用 `/agent`。
+7. 将 `reply` 直接作为企业微信 markdown 消息发送。
+
+## 12. 入口选择建议
+
+如果开发组需要判断“应该做几个入口”，建议如下：
+
+### 方案 A：一个统一输入入口
+
+优点：
+
+1. 技术实现最简单。
+2. 前端交互最少。
+
+缺点：
+
+1. 用户容易提超范围问题。
+2. 参数缺失率会更高。
+3. 结果稳定性较弱。
+
+### 方案 B：按业务域拆菜单，共用一个 Agent API
+
+优点：
+
+1. 更符合当前 Agent 的能力边界。
+2. 更容易做提问引导。
+3. 回复稳定性更高。
+4. 更适合企业微信菜单场景。
+
+缺点：
+
+1. 菜单设计需要更多前期整理。
+
+当前更推荐：
+
+- 采用方案 B。
+
+## 13. 当前接入结论
+
+对于企业微信应用开发组，当前最合适的接入方式不是“开放聊天入口”，而是：
+
+1. 用菜单限制问题范围。
+2. 用引导语约束用户输入。
+3. 用一个统一的 `/agent` 入口承接调用。
+4. 在应用层提前拦截写操作和复杂统计类请求。
+
+这样能最大程度发挥当前 Agent 的查询能力，同时避免把不支持的能力暴露成错误体验。
--- a/docs/api_v2_mission_api.md
+++ b/docs/api_v2_mission_api.md
@@ -279,6 +279,17 @@

 响应：`MissionCategory[]`

+`MissionCategory` 当前包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | 分类 ID |
+| `merchant` | int | 所属商户 ID |
+| `name` | string | 分类名称 |
+| `payload_processor` | string | payload 增强器标识，未启用时为空字符串 |
+| `created_at` | datetime | 创建时间 |
+| `updated_at` | datetime | 更新时间 |
+
 ## 创建任务分类

 - URL: `/api/v2/mission-categories/`
@@ -289,12 +300,14 @@
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | string | 是 | 分类名称，同商户下唯一 |
+| `payload_processor` | string | 否 | payload 增强器标识；当前可选值：`structured_description_v1` |

 请求示例：

 ```json
 {
-  "name": "售后"
+  "name": "售后",
+  "payload_processor": "structured_description_v1"
 }
 ```

@@ -317,6 +330,7 @@
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `name` | string | 分类名称，同商户下唯一 |
+| `payload_processor` | string | payload 增强器标识；传空字符串表示清空 |

 成功响应：`MissionCategory`

--- a/docs/notifier_admin_guide.md
+++ b/docs/notifier_admin_guide.md
@@ -14,6 +14,22 @@
 - `Notifier` 是“发信工具”
 - `NotifierRoute` 是“分发规则”

+## 1.1 当前文档适用范围
+
+这份文档只描述“当前已经确认可由后台管理人员自行配置”的 `Notifier` 能力。
+
+截至目前，已经稳定确认、并且适合由后台人员自行配置的渠道有：
+
+- `wecom_webhook`
+- `message_api`
+
+注意：
+
+- `wecom_webhook` 和 `message_api` 的配置方式不同，不要混用字段。
+- `message_api` 适合发企业微信应用消息，可以发文本，也可以发单篇图文。
+- 当前 ERP 只是 `message_api` 的调用方，不直接管理企业微信凭据。
+- 当前 `message_api` 默认仍由开发组提供模板文件，管理人员主要负责选择正确的 `template_key` 和填写 `config`。
+
 ## 2. 当前已支持的 mission 事件

 目前 `mission` 模块已接入以下事件：
@@ -28,6 +44,92 @@

 所有这些事件都支持通过 `NotifierRoute` 进行分类路由。

+## 2.1 任务分类上的 payload 增强器
+
+除 `Notifier` 和 `NotifierRoute` 以外，部分任务分类还可以额外配置 `payload 增强器`。
+
+它的作用不是决定“发给谁”，而是在发送通知前，先对任务描述做一次固定规则的加工，再把结果交给模板使用。
+
+当前已提供的增强器：
+
+- `structured_description_v1`
+
+当前配套可直接使用的 `message_api` 模板：
+
+- `mission_structured_description_text`
+- `mission_structured_description_news`
+
+适用场景：
+
+- 某些模板不直接消费整段 `任务描述`
+- 而是希望从 `任务描述` 中拆出标题、正文、链接这类结构化字段
+
+当前 `structured_description_v1` 的处理规则：
+
+1. 忽略任务描述第一行
+2. 如果某一行以 `款式图:` 开头，则提取该行后面的图片地址为封面图字段，并且该行不再参与标题/正文内容
+3. 如果最后一行里包含 `http://` 或 `https://` 链接，则提取为跳转链接字段，并且该行不再参与正文拆分
+4. 之后按第一个空行拆分：空行前为标题，空行后为正文
+5. 如果没有空行，则剩余内容全部作为标题，正文为空
+
+模板可使用的新增字段：
+
+- `parsed_description_title`
+- `parsed_description_body`
+- `parsed_description_url`
+- `parsed_description_image_url`
+
+如果你希望直接复用开发组已经准备好的模板，推荐：
+
+- `channel = message_api`
+- `template_key = mission_structured_description_text`
+
+这个模板会把上面三个字段组织成一条可直接发送的文本消息。
+
+如果你希望发送单篇图文消息，可以使用：
+
+- `channel = message_api`
+- `template_key = mission_structured_description_news`
+
+这个模板除了依赖增强器产出的字段外，还要求在 `Notifier.config` 中填写：
+
+```json
+{
+   "agent_ids": [1000007],
+   "image_url": "https://cdn.example.com/covers/mission-news.png"
+}
+```
+
+可选地也可以填写一个兜底跳转地址：
+
+```json
+{
+   "agent_ids": [1000007],
+   "image_url": "https://cdn.example.com/covers/mission-news.png",
+   "url": "https://erp.example.com/missions/fallback"
+}
+```
+
+说明：
+
+- 优先使用任务描述里解析出的链接作为 `news.url`
+- 优先使用任务描述里 `款式图:` 解析出的图片地址作为 `news.image_url`
+- 如果解析不出链接，则回退到 `Notifier.config.url`
+- 如果解析不出图片，则回退到 `Notifier.config.image_url`
+- 如果 `Notifier.config.image_url` 也为空，则回退到系统级默认空值图 `MESSAGE_API_DEFAULT_NEWS_IMAGE_URL`
+
+当前默认值是：
+
+- `https://via.placeholder.com/640x360.png?text=No+Image`
+
+如果你们后续有自己的线上空值图，建议在环境变量里覆盖这个默认值，而不是继续依赖外部占位图服务。
+
+补充说明：
+
+- 该增强器是否启用，由任务分类决定
+- 同一个模板可以被多个分类复用，但只有启用了增强器的分类才会得到这些解析字段
+- `mission_id`、`category_name` 等原始审计字段仍然会照常传递
+
 ## 3. 当前支持的分类路由能力

 路由匹配规则如下：
@@ -58,6 +160,8 @@

 在 `Notifier` 详情页中，也可以直接通过 inline 管理该通知器下的路由。

+如果需要启用上面的 `payload 增强器`，还需要进入 `任务分类` 管理页，在具体分类上选择对应增强器。
+
 ## 5. Notifier 字段说明

 ### 5.1 merchant
@@ -82,9 +186,16 @@

 通知渠道。

-当前固定选：
+当前可选：

 - `wecom_webhook`
+- `message_api`
+
+补充说明：
+
+- 如果你在后台将来看到新的 channel 选项，不代表它已经进入“可自行配置”的稳定状态。
+- 当前管理人员应只配置已经明确说明过的 channel。
+- 如果要发送企业微信应用消息，请选 `message_api`，不要继续选 `wecom_webhook`。

 ### 5.4 template_key

@@ -97,9 +208,17 @@

 例如：

- `template_key = mission_completed`
+- `wecom_webhook` 渠道下：`template_key = mission_completed`
 - 对应模板文件：`notifier/templates/notifier/events/mission_completed.md`

+- `message_api` 渠道下：`template_key = mission_completed`
+- 对应模板文件：`notifier/templates/notifier/events/mission_completed.json`
+
+可以把它理解为：
+
+- `.md` 模板：最后会渲染成一段文字
+- `.json` 模板：最后会渲染成一组“结构化消息字段”
+
 ### 5.5 is_enabled

 是否启用通知器本体。
@@ -121,6 +240,49 @@
 }
 ```

+说明：
+
+- `key`：企业微信机器人 webhook key
+- `msgtype`：当前建议使用 `markdown`
+- `timeout_seconds`：请求超时时间，通常保持默认即可
+
+特别提醒：
+
+- 当前不要自行在 `config` 中增加诸如 `corp_id`、`agent_id`、`secret`、`to_user`、`to_party`、`to_tag` 等字段，除非开发组已经单独通知并提供正式说明。
+- 这些字段不属于当前已经确认可交付给管理人员配置的范围。
+
+当前 `message_api` 渠道建议配置：
+
+文本消息场景：
+
+```json
+{
+   "agent_id": 1000007,
+   "timeout_seconds": 10
+}
+```
+
+图文消息场景：
+
+```json
+{
+   "agent_ids": [1000007, 1000008],
+   "timeout_seconds": 10
+}
+```
+
+说明：
+
+- `agent_id`：企业微信应用 ID，适用于文本消息
+- `agent_ids`：企业微信应用 ID 列表，适用于图文消息
+- `timeout_seconds`：请求超时时间，通常保持默认即可
+
+特别提醒：
+
+- `message_api` 当前不要求管理人员填写任何企业微信系统级配置。
+- 对 ERP 来说，只需要知道 `message_api` 的访问地址和固定 `Authorization`。
+- `message_api` 下应优先使用开发组已提供好的 `template_key`，不要自行猜测 JSON 字段名。
+
 ### 5.7 description

 备注说明，非必填。
@@ -249,6 +411,64 @@

 系统会分别发送到两个群。

+### 8.4 示例四：任务创建时发企业微信应用文本消息
+
+适用于：
+
+- 想发给某一个企业微信应用
+- 内容以一段任务提醒文字为主
+
+`Notifier`
+
+- `name`: `任务创建通知-企业微信应用`
+- `channel`: `message_api`
+- `template_key`: `mission_created`
+- `config`:
+
+```json
+{
+   "agent_id": 1000007,
+   "timeout_seconds": 10
+}
+```
+
+- `is_enabled`: 勾选
+
+`NotifierRoute`
+
+- `event_key`: `mission.created`
+- `mission_category`: 留空 或 选择具体分类
+- `is_enabled`: 勾选
+
+### 8.5 示例五：任务创建时发企业微信应用图文消息
+
+适用于：
+
+- 想同时发到多个企业微信应用
+- 希望用户在企业微信里看到标题、摘要、点击链接、封面图
+
+`Notifier`
+
+- `name`: `任务创建图文通知-企业微信应用`
+- `channel`: `message_api`
+- `template_key`: `test_message_news`
+- `config`:
+
+```json
+{
+   "agent_ids": [1000007, 1000008],
+   "timeout_seconds": 10
+}
+```
+
+- `is_enabled`: 勾选
+
+`NotifierRoute`
+
+- `event_key`: `mission.created`
+- `mission_category`: 留空 或 选择具体分类
+- `is_enabled`: 勾选
+
 ## 9. 模板如何对应

 当前系统已内置以下模板：
@@ -260,10 +480,88 @@
 - `mission_reply_rejected`
 - `mission_reopened`
 - `mission_cancelled`
+- `test_message_news`

 管理人员通常只需要填 `template_key`，不需要改代码。  
 如果后续要新增模板内容或调整文案，需要由开发人员修改模板文件。

+补充说明：
+
+- 当前这套 admin 配置说明默认基于“模板文件”模式。
+- `wecom_webhook` 使用 `.md` 模板文件。
+- `message_api` 使用 `.json` 模板文件。
+- 在新的正式说明发布前，管理人员不要自行推断未文档化的模板字段。
+
+### 9.1 `message_api` 的 JSON 模板到底长什么样
+
+这部分是为了帮助管理人员“看懂模板的大致样子”，不是要求你在后台手工编写模板。
+
+可以把 JSON 模板理解为：
+
+- 它不是程序代码
+- 它更像一张“字段清单”
+- 系统会把里面的变量替换成真正的任务内容
+
+#### 文本消息模板示例
+
+例如 `mission_created.json` 大致会渲染成：
+
+```json
+{
+   "msgtype": "text",
+   "content": "任务已创建\n任务ID：123\n创建人：张三\n分类：售后\n紧急：否\n参与人：李四、王五\n说明：请跟进客户退货"
+}
+```
+
+用更容易理解的话说：
+
+- `msgtype = text`：表示这是一条文本消息
+- `content`：表示真正发出去的文字内容
+
+这类模板适合：
+
+- 直接提醒
+- 内容以文字为主
+- 不需要点击封面图和链接
+
+#### 图文消息模板示例
+
+例如 `test_message_news.json` 大致会渲染成：
+
+```json
+{
+   "msgtype": "news",
+   "title": "任务 123 通知",
+   "description": "请跟进客户退货",
+   "url": "https://example.com/missions/123",
+   "image_url": "https://example.com/static/mission-cover.png"
+}
+```
+
+用更容易理解的话说：
+
+- `msgtype = news`：表示这是一条单篇图文消息
+- `title`：企业微信里显示的标题
+- `description`：企业微信里显示的摘要
+- `url`：用户点击后打开的链接
+- `image_url`：封面图地址
+
+这类模板适合：
+
+- 需要点击查看详情
+- 需要更像“卡片消息”的展示
+- 想同时发到多个企业微信应用
+
+### 9.2 管理人员最需要记住什么
+
+对于 `message_api`，管理人员通常只要记住下面几件事：
+
+1. 文本消息用 `agent_id`
+2. 图文消息用 `agent_ids`
+3. `template_key` 要和开发组给出的模板名一致
+4. 不要自己修改 JSON 字段名
+5. 如果不确定是文本还是图文，先问开发组，不要猜
+
 ## 10. 未回复提醒的 admin 配置要点

 `mission.unreplied` 和其它事件不同，它不是在某个瞬时动作发生时触发，而是由后台每分钟扫描一次“仍未回复的任务”后触发。
@@ -352,6 +650,22 @@
 6. `config.key` 是否填写正确
 7. Celery worker 是否已启动

+### 11.3 为什么 `message_api` 没有更多系统配置项
+
+原因是：
+
+1. 当前 ERP 只是 `message_api` 的调用方。
+2. 企业微信真正的凭据管理和发送细节不属于 ERP 负责。
+3. 因此后台管理人员只需要配置通知器自己的参数，例如 `agent_id`、`agent_ids`、`template_key`。
+
+系统级配置由部署环境统一提供，例如：
+
+1. `MESSAGE_API_BASE_URL`
+2. `MESSAGE_API_AUTHORIZATION`
+3. `MESSAGE_API_DEFAULT_NEWS_IMAGE_URL`
+
+如果后续 `message_api` 的接口契约扩展，开发组会补充新的配置说明。
+
 ### 11.2 为什么某个任务分类没有走专门群

 常见原因：
--- a/docs/notifier_module_design.md
+++ b/docs/notifier_module_design.md
@@ -25,6 +25,7 @@
 - 独立 app：`notifier`
 - Celery task 化投递
 - 企业微信 webhook 渠道
+- `message_api` 渠道（ERP 作为调用方）
 - 模板化内容渲染
 - Admin 可配置
 - `NotifierRoute` 事件路由
@@ -33,7 +34,6 @@
 本阶段仍未做：

 - 旧模块静态通知逻辑迁移
- 外部 API
 - 通知投递明细表
 - 数据库级别审计

@@ -151,7 +151,26 @@
 `template_key` 如果写错，会在渲染阶段报错并记录日志。  
 后续可在 admin 或 model clean 中增强校验。

-## 12. 当前结论
+## 12. `message_api` 渠道边界
+
+`message_api` 的定位是：
+
+- ERP / notifier 只负责渲染结构化消息模板并调用内部 `message_api`
+- ERP 不直接管理企业微信 `corp_id`、`secret`、`access_token`
+- ERP 不直接调用企业微信官方 API
+
+当前实现方式：
+
+- `message_api` channel 使用 `.json` 模板
+- backend 会校验模板渲染结果是否符合 text/news 结构
+- 之后由 notifier 作为 HTTP client 调用 `MESSAGE_API_BASE_URL`
+
+这意味着：
+
+- `agent_id` / `agent_ids` 仍然属于 channel 级配置
+- 企业微信系统级凭据属于 `message_api` 服务自身，不属于 ERP 配置
+
+## 13. 当前结论

 当前 `notifier` 已具备：