# 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`

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