docs(详细设计): 按Agent原型重写流程设计

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

@@ -2,406 +2,130 @@
 
 ## 1. 设计目标
 
-本步骤承接风险预警和 Word 回填导出结果，目标是在飞书群聊或应用会话中完成任务触发、结果摘要查看、责任人通知和 Web 详情跳转，让注册申报审核流程具备 Web 工作台以外的协同入口。
+本步骤负责在审核任务执行完成或执行异常时，通过飞书 `@` 对应处理人，并回传 Web 详情链接。
 
-本步骤需要完成以下业务结果：
+V1 当前 Demo 固定通知策略：
 
-1. 支持飞书群聊机器人触发审核任务。
-2. 支持在飞书内选择任务或查看任务摘要。
-3. 根据风险项和章节点映射责任角色。
-4. 根据责任角色解析飞书账号。
-5. 生成飞书消息摘要和 @ 通知载荷。
-6. 调用飞书 OpenAPI 或 MCP 工具发送消息。
-7. 记录发送结果、失败原因和回传链接。
-8. 写入审计留痕。
+1. 执行完成后发送结果摘要并 `@` 处理人
+2. 执行异常后发送异常摘要并 `@` 处理人
 
-本步骤不执行具体审核规则，不改变风险结论，不直接修改字段池或导出文件。它只负责飞书入口和通知协作。
+## 2. 角色信息模型
 
-## 2. 所属模块与边界
+责任人信息不再只保留角色名，必须扩展为可通知实体，至少包含：
 
-### 2.1 Chat
+1. `owner_role`
+2. `owner_name`
+3. `department`
+4. `chapter_scope`
+5. `risk_scope`
+6. `feishu_user_id`
+7. `feishu_open_id`
+8. `feishu_name`
+9. `notify_enabled`
 
-`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` 记录飞书触发来源、消息载荷、通知对象、发送状态和失败原因。
-
-审计中必须保留：
+## 3. 输入
 
 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`
+2. `conversation_id`
+3. `product_name`
+4. `notify_reason`
+5. `registration_risk_report`
+6. `registration_word_export_report`
+7. `owner_mapping`
 
-## 3. 输入输出
+其中 `notify_reason` 固定支持：
 
-### 3.1 输入
+1. `task_completed`
+2. `task_failed`
 
-```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
-}
-```
+## 4. 输出对象
 
-### 3.2 输出
+`feishu_notification_report` 至少包含：
 
-本步骤输出 `feishu_notification_report`：
+1. `batch_id`
+2. `conversation_id`
+3. `notify_reason`
+4. `mentioned_users`
+5. `message_status`
+6. `web_detail_url`
+7. `receipt`
 
-```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. 主工作流
+## 5. 主流程
 
 ```text
-飞书群聊或 Web 触发通知
--> 解析飞书触发上下文
--> 读取风险报告和导出报告
--> 解析责任角色和飞书账号
--> 生成飞书消息摘要
--> 构建消息卡片和 @ 通知
--> 调用飞书 OpenAPI / MCP 发送
--> 记录发送回执
--> 写入审计留痕
--> 返回发送结果
+任务完成或异常
+-> 读取责任角色与飞书账号
+-> 构建飞书摘要
+-> 构建 @ 处理人载荷
+-> 发送飞书消息
+-> 写回发送回执
+-> 写入处理历史和审计
 ```
 
-## 5. 节点详细设计
+## 6. 通知内容要求
 
-### 5.1 节点一：飞书任务入口解析
+飞书消息至少应包含：
 
-业务功能：
+1. 任务名称
+2. 产品名称
+3. 批次号
+4. 结果状态
+5. 风险等级或异常摘要
+6. `@` 处理人
+7. Web 详情链接
 
-1. 解析飞书消息事件。
-2. 识别任务指令。
-3. 识别批次 ID 或项目上下文。
-4. 将飞书触发请求映射到系统场景。
+## 7. 处理完成通知
 
-支持指令示例：
+触发条件：
 
-1. `检查资料完整性`
-2. `生成风险报告`
-3. `查看导出结果`
-4. `通知责任人`
+1. 目录汇总完成
+2. 风险报告完成
+3. 导出状态已生成
 
-使用技术：
+输出重点：
 
-1. 飞书事件订阅
-2. 群聊机器人消息
-3. Django webhook view
-4. 场景配置 YAML
+1. 风险等级
+2. 是否允许正式导出
+3. 责任人
 
-产生方法：
+## 8. 执行异常通知
 
-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. 资料解析失败
+2. 规则执行失败
+3. 回填导出失败
+4. 外部依赖异常
 
-1. `飞书任务入口解析Skill`
+输出重点：
 
-### 5.2 节点二：通知上下文加载
+1. 异常阶段
+2. 异常摘要
+3. 责任人
+4. 是否建议人工介入
 
-业务功能：
+## 9. 与页面关系
 
-1. 读取风险报告。
-2. 读取 Word 导出报告。
-3. 读取审计详情链接。
-4. 读取任务状态。
+### 9.1 审核智能体
 
-使用技术：
+可展示：
 
-1. Django ORM
-2. JSONField
-3. URL reverse
+1. 本次是否已触发飞书通知
+2. 飞书发送状态
+3. 被 `@` 的处理人
 
-产生方法：
+### 9.2 处理历史
 
-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. 通知原因
+2. 接收人
+3. 消息状态
+4. Web 回链
 
-1. `飞书通知编排Skill`
+## 10. 验收标准
 
-### 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. 消息卡片交互按钮。
+1. 角色信息包含飞书账号相关字段。
+2. 执行完成与执行异常两类通知链路完整。
+3. 飞书消息支持直接 `@` 对应处理人。
+4. 通知结果可在处理历史和审计中回溯。