forked from erp-dev/erp
feat: message-api for mission via wecomm agent
This commit is contained in:
@@ -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 为什么某个任务分类没有走专门群
|
||||
|
||||
常见原因：
|
||||
|
||||
Reference in New Issue
Block a user