DEMO-AGENT/docs/详细设计/7.飞书通知.md

# 7. 飞书通知详细设计

## 1. 设计目标

本步骤承接风险预警和 Word 回填导出结果，目标是在飞书群聊或应用会话中完成任务触发、结果摘要查看、责任人通知和 Web 详情跳转，让注册申报审核流程具备 Web 工作台以外的协同入口。

本步骤需要完成以下业务结果：

1. 支持飞书群聊机器人触发审核任务。
2. 支持在飞书内选择任务或查看任务摘要。
3. 根据风险项和章节点映射责任角色。
4. 根据责任角色解析飞书账号。
5. 生成飞书消息摘要和 @ 通知载荷。
6. 调用飞书 OpenAPI 或 MCP 工具发送消息。
7. 记录发送结果、失败原因和回传链接。
8. 写入审计留痕。

本步骤不执行具体审核规则，不改变风险结论，不直接修改字段池或导出文件。它只负责飞书入口和通知协作。

## 2. 所属模块与边界

### 2.1 Chat

`apps.chat` 提供 Web 详情页链接和任务执行结果页面，飞书消息中应回传 Web 详情入口。

### 2.2 Agent Core

`agent_core` 负责飞书通知编排、摘要生成、责任人映射和发送载荷构建。

本步骤建议产生以下中文 Skill：

1. `飞书通知编排Skill`
2. `飞书任务入口解析Skill`
3. `飞书责任人映射Skill`
4. `飞书消息摘要生成Skill`
5. `飞书消息发送Skill`
6. `飞书回执记录Skill`

### 2.3 MCP / OpenAPI

飞书能力通过两类方式接入：

1. 飞书机器人 / Channel SDK：作为群聊触发和消息回传入口。
2. 飞书 OpenAPI MCP：作为 Agent 调用飞书消息、文档、群聊和用户信息的工具层。

MCP 只作为外部工具接入层，不承载业务审核逻辑。

### 2.4 Audit

`apps.audit` 记录飞书触发来源、消息载荷、通知对象、发送状态和失败原因。

审计中必须保留：

1. `batch_id`
2. `scenario_id`
3. `trigger_source`
4. `feishu_chat_id`
5. `feishu_message_id`
6. `mentioned_user_ids`
7. `notification_payload`
8. `send_status`
9. `error_message`

## 3. 输入输出

### 3.1 输入

```json
{
  "batch_id": 1001,
  "scenario_id": "registration_risk_report",
  "trigger_source": "feishu_group_bot",
  "feishu_chat_id": "oc_demo_chat",
  "feishu_message_id": "om_demo_message",
  "notify_owner": true,
  "include_web_link": true
}
```

### 3.2 输出

本步骤输出 `feishu_notification_report`：

```json
{
  "report_type": "feishu_notification_report",
  "batch_id": 1001,
  "send_status": "sent",
  "message_type": "interactive_card",
  "mentioned_users": [
    {
      "owner_role": "注册资料负责人",
      "feishu_user_id": "ou_demo_owner"
    }
  ],
  "web_detail_url": "http://localhost:8000/audit/1001/",
  "receipt": {
    "message_id": "om_demo_message",
    "sent_at": "2026-06-03T10:30:00+08:00"
  }
}
```

## 4. 主工作流

```text
飞书群聊或 Web 触发通知
-> 解析飞书触发上下文
-> 读取风险报告和导出报告
-> 解析责任角色和飞书账号
-> 生成飞书消息摘要
-> 构建消息卡片和 @ 通知
-> 调用飞书 OpenAPI / MCP 发送
-> 记录发送回执
-> 写入审计留痕
-> 返回发送结果
```

## 5. 节点详细设计

### 5.1 节点一：飞书任务入口解析

业务功能：

1. 解析飞书消息事件。
2. 识别任务指令。
3. 识别批次 ID 或项目上下文。
4. 将飞书触发请求映射到系统场景。

支持指令示例：

1. `检查资料完整性`
2. `生成风险报告`
3. `查看导出结果`
4. `通知责任人`

使用技术：

1. 飞书事件订阅
2. 群聊机器人消息
3. Django webhook view
4. 场景配置 YAML

产生方法：

1. `parse_feishu_event(event_payload) -> FeishuTriggerContext`
2. `resolve_scenario_from_command(text) -> str`
3. `resolve_batch_from_message(text, chat_context) -> int | None`

对应 Skill：

1. `飞书任务入口解析Skill`

### 5.2 节点二：通知上下文加载

业务功能：

1. 读取风险报告。
2. 读取 Word 导出报告。
3. 读取审计详情链接。
4. 读取任务状态。

使用技术：

1. Django ORM
2. JSONField
3. URL reverse

产生方法：

1. `load_notification_context(batch_id, scenario_id) -> NotificationContext`
2. `build_web_detail_url(report_or_audit) -> str`
3. `collect_notification_sources(context) -> list[dict]`

对应 Skill：

1. `飞书通知编排Skill`

### 5.3 节点三：责任人映射

业务功能：

1. 根据风险项、章节点和任务类型确定责任角色。
2. 根据责任角色查找飞书账号。
3. 支持后台或配置文件手动维护。
4. 对未配置账号的责任角色给出提示。

建议配置：

```yaml
owners:
  CH1:
    owner_role: 注册资料负责人
    feishu_user_id: ou_demo_owner
  field_conflict:
    owner_role: 注册资料负责人
    feishu_user_id: ou_demo_owner
  missing_required_document:
    owner_role: 注册申报负责人
    feishu_user_id: ou_demo_registration_owner
```

使用技术：

1. YAML 配置
2. Django Admin 维护表
3. 飞书用户 ID

产生方法：

1. `resolve_owner_roles(risk_items) -> list[OwnerRole]`
2. `load_owner_mapping() -> OwnerMapping`
3. `resolve_feishu_user_ids(owner_roles, mapping) -> list[FeishuMentionTarget]`

对应 Skill：

1. `飞书责任人映射Skill`

### 5.4 节点四：飞书消息摘要生成

业务功能：

1. 生成风险摘要。
2. 生成高风险列表。
3. 生成导出结果摘要。
4. 生成 Web 详情链接。
5. 生成飞书交互卡片或纯文本消息。

消息内容：

1. 当前任务名称。
2. 批次名称。
3. 是否通过。
4. 最高风险等级。
5. 高风险数量。
6. 待复核数量。
7. 责任人 @。
8. Web 详情入口。
9. 导出文件链接。

使用技术：

1. 飞书互动卡片 JSON
2. 文本消息模板
3. 可选 LLM 摘要

产生方法：

1. `build_feishu_summary(context) -> FeishuSummary`
2. `build_interactive_card(summary, mentions) -> dict`
3. `build_text_message(summary, mentions) -> dict`

对应 Skill：

1. `飞书消息摘要生成Skill`

### 5.5 节点五：飞书消息发送

业务功能：

1. 调用飞书 OpenAPI 或 MCP 发送消息。
2. 支持群聊消息。
3. 支持 @ 指定责任人。
4. 捕获发送结果和失败原因。

使用技术：

1. 飞书 OpenAPI
2. 飞书机器人
3. MCP 工具封装
4. 请求重试

产生方法：

1. `send_feishu_message(chat_id, payload) -> FeishuSendResult`
2. `send_feishu_card(chat_id, card_payload) -> FeishuSendResult`
3. `retry_send_on_transient_error(request) -> FeishuSendResult`

对应 Skill：

1. `飞书消息发送Skill`

### 5.6 节点六：飞书回执记录

业务功能：

1. 保存发送状态。
2. 保存消息 ID。
3. 保存通知对象。
4. 保存失败原因。
5. 写入审计。

使用技术：

1. Django ORM
2. Audit 服务
3. JSONField

产生方法：

1. `record_feishu_receipt(result, context) -> FeishuNotificationRecord`
2. `build_feishu_audit_payload(record, context) -> dict`
3. `record_feishu_audit(payload) -> AuditLog`

对应 Skill：

1. `飞书回执记录Skill`

## 6. Skill 清单

本步骤产生以下 Skill 设计文档：

1. [飞书通知编排Skill](skill/飞书通知编排Skill.md)
2. [飞书任务入口解析Skill](skill/飞书任务入口解析Skill.md)
3. [飞书责任人映射Skill](skill/飞书责任人映射Skill.md)
4. [飞书消息摘要生成Skill](skill/飞书消息摘要生成Skill.md)
5. [飞书消息发送Skill](skill/飞书消息发送Skill.md)
6. [飞书回执记录Skill](skill/飞书回执记录Skill.md)

## 7. 消息类型设计

| 类型 | 使用场景 |
|---|---|
| `text` | 简单摘要和失败提示 |
| `interactive_card` | 风险报告摘要、按钮和详情链接 |
| `mention_text` | @ 责任人 |

## 8. 页面与飞书展示

飞书消息建议展示：

1. 任务名称。
2. 批次名称。
3. 最高风险等级。
4. 是否通过。
5. 高风险摘要。
6. 待人工复核事项。
7. 责任人 @。
8. Web 详情链接。
9. 导出文件链接。

## 9. 异常处理

1. 飞书事件验签失败：拒绝请求。
2. 无法识别任务指令：返回帮助提示。
3. 未找到批次：返回业务提示。
4. 责任人未配置：发送群消息但不 @。
5. 飞书 API 失败：记录失败回执，可重试。
6. Web 链接生成失败：消息中省略链接并记录警告。

## 10. 与全流程接口

本步骤读取：

1. `registration_risk_report`
2. `registration_word_export_report`
3. 审计详情链接
4. 责任人映射配置

本步骤输出：

1. `feishu_notification_report`
2. 飞书消息 ID
3. 通知状态
4. 审计记录

## 11. 测试设计

### 11.1 单元测试

1. 飞书事件解析。
2. 任务指令解析。
3. 责任人映射。
4. 消息摘要构建。
5. 发送 payload 构建。

### 11.2 服务层测试

1. 风险报告可生成飞书卡片。
2. 责任人可被 @。
3. 未配置责任人时仍能发送摘要。
4. API 失败时记录失败回执。
5. 审计记录包含飞书来源。

### 11.3 集成测试

1. 群聊机器人触发风险报告查看。
2. 群聊机器人发送责任人通知。
3. Web 链接可跳转到详情页。

## 12. V1 实现建议

V1 建议先完成以下最小闭环：

1. 支持飞书群聊机器人接收指令。
2. 支持发送风险报告摘要。
3. 支持责任人手动配置和 @。
4. 支持 Web 详情链接。
5. 支持发送回执和审计记录。

增强阶段再补齐：

1. 飞书应用会话菜单。
2. 文档评论区 @bot。
3. 多维表格同步。
4. 飞书文档写回。
5. 消息卡片交互按钮。