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

2026-06-03 21:15:34 +08:00
parent cc200a32c4
commit 7a60af0485
7 changed files with 823 additions and 0 deletions
--- a/docs/详细设计/skill/飞书任务入口解析Skill.md
+++ b/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. 验签失败被拒绝。
+
--- a/docs/详细设计/skill/飞书回执记录Skill.md
+++ b/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. 提及用户列表可保存。
+
--- a/docs/详细设计/skill/飞书消息发送Skill.md
+++ b/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. 临时错误可重试。
+
--- a/docs/详细设计/skill/飞书消息摘要生成Skill.md
+++ b/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. 无链接时消息仍可发送。
+
--- a/docs/详细设计/skill/飞书责任人映射Skill.md
+++ b/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. 未配置角色能被识别。
+
--- a/docs/详细设计/skill/飞书通知编排Skill.md
+++ b/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. 发送失败可记录审计。
+