docs(详细设计): 新增飞书通知设计

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

@@ -0,0 +1,407 @@
+# 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. 消息卡片交互按钮。