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

docs/详细设计/skill/飞书任务入口解析Skill.md

@@ -0,0 +1,67 @@
+# 飞书任务入口解析Skill 设计
+
+## 1. Skill 定位
+
+`飞书任务入口解析Skill` 负责解析飞书事件和用户指令，将群聊消息映射到系统审核任务。
+
+英文实现标识建议使用 `FeishuTaskEntryParseSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuTaskEntryParseInput:
+    event_payload: dict
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuTaskEntryParseOutput:
+    command: str
+    scenario_id: str | None
+    batch_id: int | None
+    chat_id: str
+    message_id: str
+    warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FeishuTaskEntryParseOutput`
+
+主入口方法。
+
+### 4.2 `verify_event_signature(payload) -> bool`
+
+校验事件来源。
+
+### 4.3 `extract_command(payload) -> str`
+
+提取用户指令。
+
+### 4.4 `resolve_scenario(command) -> str | None`
+
+映射任务场景。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 飞书事件订阅
+2. Django webhook
+3. 场景配置 YAML
+
+## 6. 异常处理
+
+1. 验签失败：拒绝请求。
+2. 指令无法识别：返回帮助提示。
+3. 批次无法解析：提示用户补充批次。
+
+## 7. 测试要点
+
+1. 能解析群聊消息。
+2. 能识别风险报告指令。
+3. 验签失败被拒绝。
+

docs/详细设计/skill/飞书回执记录Skill.md

@@ -0,0 +1,69 @@
+# 飞书回执记录Skill 设计
+
+## 1. Skill 定位
+
+`飞书回执记录Skill` 负责记录飞书消息发送结果、通知对象、消息 ID、失败原因和审计载荷。
+
+英文实现标识建议使用 `FeishuReceiptRecordSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuReceiptRecordInput:
+    batch_id: int
+    send_result: dict
+    mention_targets: list[dict]
+    notification_payload: dict
+    trigger_context: dict
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuReceiptRecordOutput:
+    notification_record_id: int
+    audit_payload: dict
+    status: str
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FeishuReceiptRecordOutput`
+
+主入口方法。
+
+### 4.2 `create_notification_record(input) -> FeishuNotificationRecord`
+
+创建通知记录。
+
+### 4.3 `build_audit_payload(record) -> dict`
+
+生成审计载荷。
+
+### 4.4 `record_audit(payload) -> AuditLog`
+
+写入审计。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Django ORM
+2. JSONField
+3. Audit 服务
+
+## 6. 异常处理
+
+1. 记录写入失败：返回系统错误。
+2. 审计写入失败：保留通知记录并标记警告。
+3. 发送失败：仍记录失败回执。
+
+## 7. 测试要点
+
+1. 成功发送可记录 message_id。
+2. 失败发送可记录错误。
+3. 审计载荷包含触发来源。
+4. 提及用户列表可保存。
+

docs/详细设计/skill/飞书消息发送Skill.md

@@ -0,0 +1,70 @@
+# 飞书消息发送Skill 设计
+
+## 1. Skill 定位
+
+`飞书消息发送Skill` 负责调用飞书 OpenAPI 或 MCP 工具发送消息，并返回发送结果。
+
+英文实现标识建议使用 `FeishuMessageSendSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuMessageSendInput:
+    chat_id: str
+    message_type: str
+    payload: dict
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuMessageSendOutput:
+    send_status: str
+    message_id: str | None
+    raw_response: dict
+    error_message: str = ""
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FeishuMessageSendOutput`
+
+主入口方法。
+
+### 4.2 `send_text(chat_id, payload) -> dict`
+
+发送文本消息。
+
+### 4.3 `send_card(chat_id, payload) -> dict`
+
+发送互动卡片。
+
+### 4.4 `retry_on_transient_error(request) -> dict`
+
+临时错误重试。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 飞书 OpenAPI
+2. 飞书 MCP 工具
+3. HTTP client
+4. 重试策略
+
+## 6. 异常处理
+
+1. token 失效：发送失败并记录。
+2. chat_id 无效：发送失败。
+3. 网络超时：重试后失败。
+4. payload 非法：发送失败。
+
+## 7. 测试要点
+
+1. 文本消息 payload 正确。
+2. 卡片消息 payload 正确。
+3. API 失败可记录错误。
+4. 临时错误可重试。
+

docs/详细设计/skill/飞书消息摘要生成Skill.md

@@ -0,0 +1,68 @@
+# 飞书消息摘要生成Skill 设计
+
+## 1. Skill 定位
+
+`飞书消息摘要生成Skill` 负责将风险报告、导出报告和责任人信息组装为飞书文本消息或互动卡片。
+
+英文实现标识建议使用 `FeishuMessageSummaryBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuMessageSummaryBuildInput:
+    risk_report: dict
+    word_export_report: dict | None
+    mention_targets: list[dict]
+    web_detail_url: str | None
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuMessageSummaryBuildOutput:
+    message_type: str
+    payload: dict
+    summary_text: str
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FeishuMessageSummaryBuildOutput`
+
+主入口方法。
+
+### 4.2 `build_summary_text(report) -> str`
+
+生成文本摘要。
+
+### 4.3 `build_interactive_card(report, mentions, url) -> dict`
+
+生成互动卡片。
+
+### 4.4 `build_mentions(mention_targets) -> list[dict]`
+
+生成 @ 用户片段。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 飞书卡片 JSON
+2. 文本模板
+3. 可选 LLM 摘要
+
+## 6. 异常处理
+
+1. 风险报告为空：生成提示消息。
+2. Web 链接为空：卡片不展示按钮。
+3. 责任人为空：不生成 @。
+
+## 7. 测试要点
+
+1. 能生成风险摘要。
+2. 能生成卡片 payload。
+3. 能包含 @ 用户。
+4. 无链接时消息仍可发送。
+

docs/详细设计/skill/飞书责任人映射Skill.md

@@ -0,0 +1,64 @@
+# 飞书责任人映射Skill 设计
+
+## 1. Skill 定位
+
+`飞书责任人映射Skill` 负责将风险项、章节点和责任角色映射到飞书用户 ID。
+
+英文实现标识建议使用 `FeishuOwnerMappingSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuOwnerMappingInput:
+    risk_items: list[dict]
+    owner_mapping_config: dict | None = None
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuOwnerMappingOutput:
+    mention_targets: list[dict]
+    unresolved_roles: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FeishuOwnerMappingOutput`
+
+主入口方法。
+
+### 4.2 `load_owner_mapping() -> dict`
+
+读取责任人映射。
+
+### 4.3 `resolve_roles(risk_items) -> list[str]`
+
+解析责任角色。
+
+### 4.4 `resolve_user_ids(roles, mapping) -> list[dict]`
+
+映射飞书用户 ID。
+
+## 5. 技术实现
+
+使用技术：
+
+1. YAML 配置
+2. Django Admin 维护表
+3. 飞书用户 ID
+
+## 6. 异常处理
+
+1. 责任角色未配置：加入 unresolved。
+2. 用户 ID 为空：不 @，但保留角色。
+3. 配置文件缺失：使用默认映射。
+
+## 7. 测试要点
+
+1. 风险项能映射责任角色。
+2. 责任角色能映射用户 ID。
+3. 未配置角色能被识别。
+

docs/详细设计/skill/飞书通知编排Skill.md

@@ -0,0 +1,78 @@
+# 飞书通知编排Skill 设计
+
+## 1. Skill 定位
+
+`飞书通知编排Skill` 是第七步工作流的总入口 Skill，负责组织飞书触发上下文解析、通知上下文加载、责任人映射、消息摘要生成、消息发送和回执记录。
+
+英文实现标识建议使用 `FeishuNotificationOrchestrateSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FeishuNotificationOrchestrateInput:
+    batch_id: int
+    scenario_id: str
+    trigger_source: str
+    feishu_chat_id: str
+    feishu_message_id: str | None = None
+    notify_owner: bool = True
+    include_web_link: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FeishuNotificationOrchestrateOutput:
+    report_type: str
+    batch_id: int
+    send_status: str
+    mentioned_users: list[dict]
+    receipt: dict
+    audit_id: int | None = None
+```
+
+## 4. 依赖 Skill
+
+1. `飞书任务入口解析Skill`
+2. `飞书责任人映射Skill`
+3. `飞书消息摘要生成Skill`
+4. `飞书消息发送Skill`
+5. `飞书回执记录Skill`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> FeishuNotificationOrchestrateOutput`
+
+主入口方法。
+
+### 5.2 `load_notification_context(input) -> NotificationContext`
+
+加载风险报告、导出报告和 Web 链接。
+
+### 5.3 `build_notification_payload(context) -> dict`
+
+构建消息载荷。
+
+## 6. 技术实现
+
+使用技术：
+
+1. Tool Registry
+2. 飞书 OpenAPI / MCP
+3. Django ORM
+4. Audit 服务
+
+## 7. 异常处理
+
+1. 风险报告缺失：发送提示消息。
+2. 飞书 chat_id 缺失：任务失败。
+3. 发送失败：记录失败回执。
+
+## 8. 测试要点
+
+1. 能生成飞书通知报告。
+2. 能串联责任人映射和消息发送。
+3. 发送失败可记录审计。
+