forked from erp-dev/erp
feat: notifier beta
This commit is contained in:
293
docs/notifier_admin_guide.md
Normal file
293
docs/notifier_admin_guide.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# 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 格式填写。
|
||||
|
||||
当前企业微信机器人建议配置如下：
|
||||
|
||||
```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` 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
这样保存后，对应事件发生时就会自动发送。
|
||||
Reference in New Issue
Block a user