# Notifier 管理人员配置说明

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

## 1. 两层结构

当前通知配置分成两层：

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

可以这样理解：

- `Notifier` 是“发信工具”
- `NotifierRoute` 是“分发规则”

## 2. 当前已支持的 mission 事件

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

- `mission.created`
- `mission.replied`
- `mission.completed`
- `mission.reply_rejected`
- `mission.reopened`
- `mission.cancelled`

所有这些事件都支持通过 `NotifierRoute` 进行分类路由。

## 3. 当前支持的分类路由能力

路由匹配规则如下：

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

这意味着你可以实现：

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

## 4. Admin 中的两个入口

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

- `通知器`
- `通知路由`

推荐的管理方式：

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

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

## 5. Notifier 字段说明

### 5.1 merchant

所属商户。

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

### 5.2 name

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

建议命名方式：

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

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

### 5.3 channel

通知渠道。

当前固定选：

- `wecom_webhook`

### 5.4 template_key

模板标识。

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

`notifier/templates/notifier/events/`

例如：

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

### 5.5 is_enabled

是否启用通知器本体。

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

### 5.6 config

渠道配置，JSON 格式。

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

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

### 5.7 description

备注说明，非必填。

## 6. NotifierRoute 字段说明

### 6.1 merchant

所属商户。

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

### 6.2 notifier

要使用的通知器。

### 6.3 event_key

要监听的业务事件。

例如：

- `mission.created`
- `mission.completed`

### 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` 为空的通配路由

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

## 9. 模板如何对应

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

- `mission_created`
- `mission_replied`
- `mission_completed`
- `mission_reply_rejected`
- `mission_reopened`
- `mission_cancelled`

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

## 10. 如何停用

### 停用整个通知器

适用于：

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

操作方式：

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

### 停用某一条路由

适用于：

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

操作方式：

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

## 11. 常见问题

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

请依次检查：

1. `Notifier` 是否启用
2. `NotifierRoute` 是否启用
3. `event_key` 是否选对
4. `mission_category` 是否与实际任务分类匹配
5. `template_key` 是否对应现有模板
6. `config.key` 是否填写正确
7. Celery worker 是否已启动

### 11.2 为什么某个任务分类没有走专门群

常见原因：

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

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

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

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

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

## 12. 管理建议

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

## 13. 最简操作结论

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

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

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