erpnew/docs/notifier_admin_guide.md

Notifier 管理人员配置说明

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

1. Notifier 是什么

Notifier 可以理解为一条“通知规则”。

当某个业务事件发生时，系统会根据以下条件查找可用的通知器：

• 商户一致
• event_key 一致
• is_enabled=True

找到后，系统会自动：

1. 使用对应模板渲染消息内容
2. 按配置的渠道发送
3. 记录发送日志

当前已支持的渠道：

• 企业微信机器人 wecom_webhook

2. 当前已支持的事件

目前 mission 模块已接入以下事件：

• mission.created：任务创建
• mission.replied：任务有新回应
• mission.completed：任务完成
• mission.reply_rejected：任务回应被撤销
• mission.reopened：任务被重新打开
• mission.cancelled：任务被取消

如果要让某个事件发送通知，只需要在后台新增对应 event_key 的 Notifier。

3. 在哪里配置

进入 Django Admin 后，找到：

• 通知器

然后点击“新增”即可。

4. 字段说明

创建 Notifier 时，需要填写以下字段。

4.1 merchant

所属商户。

通知器只会匹配当前商户下发生的事件。
不同商户如果都需要通知，需要分别创建各自的 Notifier。

4.2 name

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

建议命名方式：

• 任务创建通知-生产群
• 任务完成通知-老板群
• 任务取消通知-客服群

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

4.3 event_key

要监听的业务事件标识。

这是最核心的绑定字段。
它决定这条 Notifier 绑定到哪个业务信号。

例如：

• mission.completed 表示“任务完成时发送”
• mission.cancelled 表示“任务取消时发送”

4.4 channel

通知渠道。

当前固定选：

• wecom_webhook

4.5 template_key

消息模板标识。

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

notifier/templates/notifier/events/

例如：

• template_key = mission_completed
• 对应模板文件：notifier/templates/notifier/events/mission_completed.md

4.6 is_enabled

是否启用。

• 勾选：该 Notifier 生效
• 不勾选：该 Notifier 不会参与匹配和发送

4.7 config

渠道配置，使用 JSON 格式填写。

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

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

字段说明：

• key：企业微信机器人 webhook key
• msgtype：消息类型，建议用 markdown
• timeout_seconds：请求超时时间，单位秒

4.8 description

备注说明，非必填。

建议写清楚这条通知器的用途，例如：

• 用于生产部任务完成通知
• 用于客服查看任务取消

5. 配置步骤

以“任务完成时发送企业微信通知”为例：

1. 进入 Admin 的 通知器
2. 点击“新增”
3. 选择 merchant
4. 填写 name
5. 选择 event_key = mission.completed
6. 选择 channel = wecom_webhook
7. 填写 template_key = mission_completed
8. 在 config 中填写 webhook 参数
9. 勾选 is_enabled
10. 保存

保存后，只要该商户下发生“任务完成”事件，系统就会自动尝试发送通知。

6. 推荐配置示例

6.1 示例一：任务创建通知

适合发到内部任务协作群。

字段建议：

• name: 任务创建通知-协作群
• event_key: mission.created
• channel: wecom_webhook
• template_key: mission_created
• is_enabled: 勾选

config 示例：

{
  "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "msgtype": "markdown",
  "timeout_seconds": 10
}

6.2 示例二：任务完成通知

适合发到管理群或老板群。

字段建议：

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

6.3 示例三：任务取消通知

适合发到客服或跟单群。

字段建议：

• name: 任务取消通知-客服群
• event_key: mission.cancelled
• channel: wecom_webhook
• template_key: mission_cancelled
• is_enabled: 勾选

7. 一个事件是否可以绑定多个 Notifier

可以。

例如同一个商户下，mission.completed 可以同时配置：

• 一条发到生产群
• 一条发到老板群
• 一条发到客服群

只要它们满足：

• merchant 相同
• event_key 相同
• is_enabled=True

系统就会逐条发送。

8. 模板如何对应

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

• mission_created
• mission_replied
• mission_completed
• mission_reply_rejected
• mission_reopened
• mission_cancelled

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

9. 如何停用某条通知

如果暂时不想让某条通知继续发送，不需要删除，只需要：

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

这样最安全，也方便后续恢复。

10. 常见问题

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

请依次检查：

1. Notifier 是否已勾选 is_enabled
2. merchant 是否配置正确
3. event_key 是否选对
4. template_key 是否与现有模板匹配
5. config.key 是否填写正确
6. Celery worker 是否已启动

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

通常是因为配置了多条相同 merchant + event_key 的启用状态通知器。
这不一定是错误，也可能是有意发往多个群。

如果不希望多发，请检查是否存在重复配置。

10.3 是否建议删除 Notifier

一般不建议优先删除，建议先停用：

• 更安全
• 方便回滚
• 方便排查历史配置

11. 管理建议

建议按下面的方式维护：

• 名称中写清楚用途和群目标
• 先停用再删除
• 一个事件先配一条验证，确认无误后再扩展到多个群
• description 中注明负责人或用途

12. 给管理人员的最简操作结论

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

1. 选对 merchant
2. 选对 event_key
3. 选 channel = wecom_webhook
4. 填对 template_key
5. 在 config 填正确的企业微信机器人 key

这样保存后，对应事件发生时就会自动发送。