erpnew/docs/notifier_admin_guide.md

Notifier 管理人员配置说明

本文档面向后台管理人员，说明如何在 Django Admin 中配置 Notifier 与 NotifierRoute，让系统在指定业务事件发生时自动发送通知，并支持按任务分类分发。

1. 两层结构

当前通知配置分成两层：

• Notifier：通知器本体，负责“发到哪里、用什么模板、走什么渠道”
• NotifierRoute：通知路由，负责“什么事件、什么任务分类，应该命中哪个 Notifier”

可以这样理解：

• 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 模块已接入以下事件：

• mission.created
• mission.replied
• mission.completed
• mission.unreplied
• mission.reply_rejected
• mission.reopened
• mission.cancelled

所有这些事件都支持通过 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 中填写：

{
   "agent_ids": [1000007],
   "image_url": "https://cdn.example.com/covers/mission-news.png"
}

可选地也可以填写一个兜底跳转地址：

{
   "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. 当前支持的分类路由能力

路由匹配规则如下：

1. 先按 merchant + event_key + is_enabled=True 匹配启用中的路由
2. 如果当前任务带有分类：
   • 优先匹配该分类的专用路由
   • 同时允许匹配“任务分类为空”的通配路由
3. 如果同一个 Notifier 同时命中了专用路由和通配路由，只发送一次，优先使用专用路由

这意味着你可以实现：

• 某个分类发到专门群
• 未单独配置的分类发到通用群
• 同一事件同时发多个群

4. Admin 中的两个入口

进入 Django Admin 后，主要会看到两个对象：

• 通知器
• 通知路由

推荐的管理方式：

1. 先创建 Notifier
2. 再创建或维护它的 NotifierRoute

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

如果需要启用上面的 payload 增强器，还需要进入 任务分类 管理页，在具体分类上选择对应增强器。

5. Notifier 字段说明

5.1 merchant

所属商户。

通知器只会服务于该商户下的路由和事件。

5.2 name

通知器名称，仅用于后台识别和管理。

建议命名方式：

• 任务通知-生产群
• 任务通知-售后群
• 任务通知-管理群

同一商户下名称不能重复。

5.3 channel

通知渠道。

当前可选：

• wecom_webhook
• message_api

补充说明：

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

5.4 template_key

模板标识。

系统会根据这个字段去固定目录查找模板文件。
当前模板目录：

notifier/templates/notifier/events/

例如：

• 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

是否启用通知器本体。

• 勾选：该通知器可被路由命中
• 不勾选：即使路由存在，也不会发送

5.6 config

渠道配置，JSON 格式。

当前企业微信机器人建议配置：

{
  "key": "你的企业微信机器人key",
  "msgtype": "markdown",
  "timeout_seconds": 10
}

说明：

• key：企业微信机器人 webhook key
• msgtype：当前建议使用 markdown
• timeout_seconds：请求超时时间，通常保持默认即可

特别提醒：

• 当前不要自行在 config 中增加诸如 corp_id、agent_id、secret、to_user、to_party、to_tag 等字段，除非开发组已经单独通知并提供正式说明。
• 这些字段不属于当前已经确认可交付给管理人员配置的范围。

当前 message_api 渠道建议配置：

文本消息场景：

{
   "agent_id": 1000007,
   "timeout_seconds": 10
}

图文消息场景：

{
   "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

备注说明，非必填。

6. NotifierRoute 字段说明

6.1 merchant

所属商户。

必须与关联的 Notifier 属于同一商户。

6.2 notifier

要使用的通知器。

6.3 event_key

要监听的业务事件。

例如：

• mission.created
• mission.completed
• mission.unreplied

6.4 mission_category

任务分类路由条件。

• 为空：表示该事件的通配路由，适用于所有未被更具体路由覆盖的任务分类
• 不为空：表示只处理该任务分类下的任务事件

6.5 is_enabled

是否启用该路由。

• 勾选：路由参与匹配
• 不勾选：路由不会命中

6.6 description

备注说明，建议写清楚用途，例如：

• 任务创建-生产分类专用路由
• 任务完成-所有分类默认路由

7. 推荐配置步骤

以“任务创建时，生产分类发生产群，其他分类发管理群”为例：

第一步：创建两个 Notifier

1. 创建 Notifier A

   • name = 任务通知-生产群
   • channel = wecom_webhook
   • template_key = mission_created
   • config 填生产群机器人 key
   • is_enabled = True

2. 创建 Notifier B

   • name = 任务通知-管理群
   • channel = wecom_webhook
   • template_key = mission_created
   • config 填管理群机器人 key
   • is_enabled = True

第二步：创建路由

1. 创建 NotifierRoute A1

   • notifier = Notifier A
   • event_key = mission.created
   • mission_category = 生产
   • is_enabled = True

2. 创建 NotifierRoute B1

   • notifier = Notifier B
   • event_key = mission.created
   • mission_category = 空
   • is_enabled = True

这样配置后：

• 生产分类任务创建时，优先命中生产群路由
• 其他分类任务创建时，走管理群的通配路由

8. 典型配置示例

8.1 示例一：所有任务完成统一发管理群

Notifier

• name: 任务完成通知-管理群
• channel: wecom_webhook
• template_key: mission_completed
• is_enabled: 勾选

NotifierRoute

• event_key: mission.completed
• mission_category: 留空
• is_enabled: 勾选

8.2 示例二：售后分类任务创建发售后群

Notifier

• name: 任务创建通知-售后群
• channel: wecom_webhook
• template_key: mission_created
• is_enabled: 勾选

NotifierRoute

• event_key: mission.created
• mission_category: 售后
• is_enabled: 勾选

8.3 示例三：同一个事件同时发多个群

例如 mission.cancelled 同时发客服群和管理群：

• 创建两个不同的 Notifier
• 分别为它们配置两条 event_key = mission.cancelled 的路由
• 两条路由都可以是 mission_category 为空的通配路由

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

8.4 示例四：任务创建时发企业微信应用文本消息

适用于：

• 想发给某一个企业微信应用
• 内容以一段任务提醒文字为主

Notifier

• name: 任务创建通知-企业微信应用
• channel: message_api
• template_key: mission_created
• config:

{
   "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:

{
   "agent_ids": [1000007, 1000008],
   "timeout_seconds": 10
}

• is_enabled: 勾选

NotifierRoute

• event_key: mission.created
• mission_category: 留空 或 选择具体分类
• is_enabled: 勾选

9. 模板如何对应

当前系统已内置以下模板：

• mission_created
• mission_replied
• mission_completed
• mission_unreplied
• 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 大致会渲染成：

{
   "msgtype": "text",
   "content": "任务已创建\n任务ID：123\n创建人：张三\n分类：售后\n紧急：否\n参与人：李四、王五\n说明：请跟进客户退货"
}

用更容易理解的话说：

• msgtype = text：表示这是一条文本消息
• content：表示真正发出去的文字内容

这类模板适合：

• 直接提醒
• 内容以文字为主
• 不需要点击封面图和链接

图文消息模板示例

例如 test_message_news.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 和其它事件不同，它不是在某个瞬时动作发生时触发，而是由后台每分钟扫描一次“仍未回复的任务”后触发。

这意味着 admin 需要同时确认两件事：

1. 任务本身开启了未回复提醒
2. 通知系统中存在 mission.unreplied 对应的 NotifierRoute

如果只配置了路由，但任务没有开启提醒，则不会发送。

如果任务开启了提醒，但没有配置 mission.unreplied 路由，也不会发送到任何群。

10.1 推荐配置方式

1. 创建一个 Notifier
   • name = 任务未回复提醒-管理群
   • channel = wecom_webhook
   • template_key = mission_unreplied
   • is_enabled = True
2. 创建一条 NotifierRoute
   • event_key = mission.unreplied
   • mission_category = 留空 或选择具体任务分类
   • is_enabled = True

10.2 什么时候会持续提醒

只有满足以下条件才会持续发送 mission.unreplied：

1. 任务开启了“未回复提醒”
2. 任务还没完成
3. 任务还没取消
4. 当前没有任何有效回复
5. 没超过任务自身设置的最大提醒次数

10.3 为什么任务开启了提醒，但还是没收到群通知

优先检查：

1. 是否已配置 mission.unreplied 的路由
2. 该路由是否启用
3. 对应的 Notifier 是否启用
4. template_key 是否写成 mission_unreplied
5. Celery worker / beat 是否都在运行

11. 如何停用

停用整个通知器

适用于：

• 这个群临时不用
• 机器人 key 暂时不可用
• 该通知器下的所有路由都不想生效

操作方式：

1. 打开 Notifier
2. 取消勾选 is_enabled
3. 保存

停用某一条路由

适用于：

• 只是不想处理某个事件
• 只是不想处理某个任务分类

操作方式：

1. 打开对应 NotifierRoute
2. 取消勾选 is_enabled
3. 保存

12. 常见问题

11.1 为什么事件发生了，但没有收到通知

请依次检查：

1. Notifier 是否启用
2. NotifierRoute 是否启用
3. event_key 是否选对
4. mission_category 是否与实际任务分类匹配
5. template_key 是否对应现有模板
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 为什么某个任务分类没有走专门群

常见原因：

1. 没有为该分类配置专用路由
2. 专用路由被停用
3. 该任务分类本身不是你以为的那个分类

11.3 为什么同一个事件发了多次

通常是因为配置了多个不同的 NotifierRoute，分别绑定到了不同的 Notifier。
这不一定是错误，也可能是有意发往多个群。

11.4 同一个通知器会不会因为“专用路由 + 通配路由”重复发送两次

不会。
系统会自动去重，并优先使用更具体的分类路由。

13. 管理建议

• 先建 Notifier，再建 NotifierRoute
• 通知器名称中写清楚目标群
• 路由备注中写清楚事件和分类用途
• 先停用再删除
• 先配置一条路由做验证，再批量扩展

14. 最简操作结论

如果你只想快速配置一条通知，记住这 6 个关键点就够了：

1. 先创建 Notifier
2. 填好 channel
3. 填好 template_key
4. 在 config 中填好企业微信机器人 key
5. 再创建 NotifierRoute
6. 选对 event_key 和 mission_category

这样保存后，对应任务事件发生时就会自动按路由发送。