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 输入

{
  "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：

{
  "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. 主工作流

飞书群聊或 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. 对未配置账号的责任角色给出提示。

建议配置：

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
2. 飞书任务入口解析Skill
3. 飞书责任人映射Skill
4. 飞书消息摘要生成Skill
5. 飞书消息发送Skill
6. 飞书回执记录Skill

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. 消息卡片交互按钮。