DEMO-AGENT/docs/2.功能设计/4.飞书通知与问答接入.md

飞书通知与问答接入功能设计

文档信息

项目	内容
需求分析文档	docs/1.需求分析/4.飞书通知与问答接入.md
依赖功能设计	docs/2.功能设计/1.自动汇总.md；docs/2.功能设计/2.NMPA注册资料法规核查与整改闭环.md；docs/2.功能设计/3.产品关键信息提取与申报文件自动填表.md
功能名称	飞书通知与问答接入
所属模块	审核智能体 review_agent
设计日期	2026-06-07
设计版本	V1.0

---

一、设计目标

本功能用于将系统内工作流结果通过飞书官方智能体/应用机器人同步到指定个人账号，并为后续飞书内问答能力预留数据模型和服务边界。首期实现重点是：自动汇总、NMPA 注册资料法规核查与整改闭环、产品关键信息提取与申报文件自动填表三个流程结束后，使用 App ID/App Secret 获取 tenant_access_token，调用飞书消息 API 向指定个人账号发送富文本私聊提醒。

首期不实现飞书事件订阅回调和私聊问答，但需要在设计上预留用户映射、查询服务、权限过滤和问答日志能力，保证后续可以平滑扩展到“用户在飞书私聊机器人中查询批次状态、风险摘要、缺失摘要和导出摘要”。

---

二、设计范围

2.1 本期范围

序号	范围项	说明
1	指定个人通知	通过飞书官方智能体/应用机器人消息 API 向一个指定个人账号发送通知
2	发起人展示	消息正文展示批次发起人或上传人，不做群内 @
3	三流程接入	自动汇总、法规核查、自动填表均发送完成通知
4	富文本消息	使用飞书富文本格式展示标题、批次、状态、摘要、链接和发起人
5	token 管理	使用 App ID/App Secret 获取并缓存 tenant_access_token
6	通知判重	同一批次、同一工作流、同一状态只发送一次
7	通知记录	保存摘要、通道、目标、状态、失败原因、发送时间等信息
8	批次详情展示	在对应批次详情页展示通知状态和失败原因
9	用户映射管理	通过 Django Admin 手工维护系统用户与飞书用户标识，服务后续按发起人私聊和问答身份识别
10	问答预留	预留飞书用户映射、查询服务、权限规则和问答日志模型

2.2 非本期范围

序号	范围项	说明
1	飞书私聊问答回调	不实现事件订阅接口和问答回复处理
2	群聊 @ 机器人问答	不接收群消息，不处理群内权限问题
3	飞书事件订阅回调	首期不接收私聊或群聊消息事件
4	复杂消息卡片	不做交互式卡片按钮和回调
5	自动后台重试	飞书发送失败只记录，不自动重试
6	飞书通讯录同步	不自动拉取用户，首期手工维护映射

---

三、与既有功能的关系

既有能力	处理方式	说明
自动汇总工作流	接入通知	文件汇总完成后生成摘要通知
法规核查工作流	替换/扩展 mock 通知	风险分级和报告生成后发送摘要通知
自动填表工作流	扩展现有 notifier	Word/追溯清单生成后发送摘要通知
通知记录模型	统一扩展	现有法规和填表通知记录已存在，本设计建议抽象统一通知服务
工作流事件	复用	通知发送结果可作为节点事件或批次附属信息展示
Django Admin	扩展	新增飞书用户映射管理入口

---

四、总体架构

4.1 逻辑架构

flowchart TD
    A["业务工作流完成"] --> B["NotificationDispatcher"]
    B --> C["WorkflowNotificationBuilder"]
    C --> D["ConfiguredPersonalRecipientResolver"]
    D --> E["RichTextMessageBuilder"]
    E --> F{"通知是否已发送"}
    F -->|"已发送"| G["写入/返回重复跳过结果"]
    F -->|"未发送"| H{"飞书通知是否启用"}
    H -->|"否"| I["写入 mock/未启用记录"]
    H -->|"是"| J["FeishuTokenProvider"]
    J --> K["获取/复用 tenant_access_token"]
    K --> L["FeishuMessageApiClient"]
    L --> X["POST /im/v1/messages"]
    X --> M["保存通知记录"]
    M --> N["批次详情页展示"]

    O["后续飞书私聊消息"] -.预留.-> P["FeishuQuestionService"]
    P -.预留.-> Q["BatchSummaryQueryService"]
    Q -.预留.-> R["权限过滤"]
    P -.预留.-> S["FeishuQuestionLog"]

4.2 模块划分

模块	责任
notification_dispatcher	工作流完成后统一调度通知发送
workflow_notification_builder	将不同工作流批次转换为统一通知上下文
feishu_recipient_resolver	首期读取配置中的个人 open_id/user_id；后续支持按系统用户映射解析
feishu_message_builder	构造飞书富文本消息体
feishu_token_provider	使用 App ID/App Secret 获取并缓存 tenant_access_token
feishu_message_api_client	调用飞书发送消息 API、处理超时和响应解析
notification_record_service	判重、保存成功/失败/未启用记录
batch_notification_presenter	为批次详情页输出通知状态
feishu_question_service	后续问答预留，解析问题并查询摘要
batch_summary_query_service	后续问答预留，按权限查询批次摘要

---

五、通知业务流程

5.1 主流程

业务工作流进入 success、partial_success 或 failed
-> 工作流调用统一通知服务
-> 通知服务生成 workflow_type、batch_id、status 组成的判重键
-> 检查是否已有同一判重键的成功通知
-> 若已有成功通知，跳过发送并返回 skipped
-> 读取批次、用户、摘要、结果链接
-> 读取配置中的个人 open_id/user_id 作为接收人
-> 构造富文本消息，正文展示批次发起人或上传人
-> 判断 FEISHU_NOTIFY_ENABLED
-> 未启用时写入 mock/disabled 记录
-> 已启用时获取或复用 tenant_access_token
-> 调用飞书消息 API 向指定个人 open_id/user_id 发送消息
-> 发送成功写入 sent/success 记录
-> 发送失败写入 failed 记录，记录错误信息
-> 业务工作流不因通知失败而失败

5.2 三类工作流通知摘要

工作流	workflow_type	摘要字段	下一步
自动汇总	file_summary	文件总数、成功解析数、失败/跳过数、导出文件数	查看汇总结果或下载 Excel
法规核查	regulatory_review	风险总数、阻断项数、高风险数、中风险数、报告导出状态	查看风险报告和整改建议
自动填表	application_form_fill	选中模板数、导出文件数、冲突字段数、失败原因概述	下载 Word/追溯清单并人工确认

5.3 通知状态

状态	含义	是否阻断主流程
pending	已创建记录但未发送	否
sent/success	已成功发送到飞书	否
failed	发送失败或配置异常	否
skipped_duplicate	已存在同一批次、同一流程、同一状态通知	否
disabled/mock	真实通知未启用，记录为模拟或未启用	否

---

六、飞书富文本设计

6.1 消息结构

飞书富文本消息建议使用 post 类型。首期内容只放摘要，不展开完整风险项和缺失项。

{
  "msg_type": "post",
  "content": {
    "post": {
      "zh_cn": {
        "title": "自动填表流程已完成",
        "content": [
          [
            {"tag": "text", "text": "状态：成功\n"},
            {"tag": "text", "text": "批次：AFF-20260607-001\n"},
            {"tag": "text", "text": "发起人：owner\n"}
          ],
          [
            {"tag": "text", "text": "摘要：生成 2 个文件，冲突字段 1 个。\n"},
            {"tag": "a", "text": "查看系统结果", "href": "http://127.0.0.1:8000/..."}
          ]
        ]
      }
    }
  }
}

6.2 接收人标识优先级

首期接收人来自环境变量配置。若同时配置多个飞书标识，按以下优先级选取：

FEISHU_DEFAULT_USER_OPEN_ID -> FEISHU_DEFAULT_USER_ID

若无可用接收人标识，系统不发送真实飞书消息，并记录配置缺失失败。

用户映射表仍保留，用于后续从“固定个人账号”升级为“按发起人私聊”。

6.3 系统链接

首期使用本地地址，例如：

http://127.0.0.1:8000/

批次详情链接由各工作流已有页面路由或详情接口拼接。部署环境后续再升级为可信域名配置。

---

七、配置设计

配置项	来源	是否敏感	说明
FEISHU_NOTIFY_ENABLED	环境变量	否	是否启用真实飞书通知
FEISHU_NOTIFY_CHANNEL	环境变量	否	首期为 feishu_api
FEISHU_APP_ID	环境变量	是	飞书智能体/企业自建应用 App ID
FEISHU_APP_SECRET	环境变量	是	飞书智能体/企业自建应用 App Secret
FEISHU_DEFAULT_USER_OPEN_ID	环境变量	否	首期指定接收人的飞书 open_id
FEISHU_DEFAULT_USER_ID	环境变量	否	首期指定接收人的飞书 user_id
FEISHU_DEFAULT_TARGET_NAME	环境变量	否	固定群展示名称
FEISHU_TENANT_TOKEN_CACHE_SECONDS	环境变量	否	tenant_access_token 本地缓存秒数
FEISHU_REQUEST_TIMEOUT_SECONDS	环境变量	否	默认 5 秒
系统用户与飞书用户映射	Django Admin	部分敏感	open_id、user_id、mobile

---

八、页面设计

8.1 Django Admin

新增飞书用户映射管理：

字段	列表展示	可搜索	可过滤
system_user	是	username	是
feishu_display_name	是	是	否
feishu_open_id	否	是	否
feishu_user_id	否	是	否
feishu_mobile	否	是	否
is_active	是	否	是

8.2 批次详情页

三个流程对应的批次详情或结果区域展示通知状态：

展示项	说明
通知通道	mock、feishu_api
通知目标	指定个人账号名称或配置名称
接收人	指定个人账号；后续可展示发起人/上传人的飞书展示名
发送状态	成功、失败、未启用、重复跳过
发送时间	成功发送时间
失败原因	配置错误、超时、飞书返回错误等摘要

---

九、飞书问答预留设计

9.1 首期预留能力

能力	设计说明
用户映射复用	后续私聊事件中的飞书用户 ID 可通过映射表关联系统用户
批次查询服务	预留按批次号、工作流类型、最近批次查询摘要的服务
权限过滤	普通用户只查自己发起或上传的批次；管理员可查全部
问答日志	预留日志表或服务接口，记录问题、意图、查询对象和回答摘要

9.2 后续问答能力边界

问题类型	首期问答 MVP 是否支持
查最近批次状态	是
查指定批次状态	是
查风险摘要	是
查缺失摘要	是
查导出摘要	是
解释具体整改建议	否
重新发起工作流	否

---

十、验收标准

序号	验收项	标准
1	三流程通知	自动汇总、法规核查、自动填表完成后均调用统一通知服务
2	个人账号发送	配置 App ID、App Secret 和指定个人 open_id/user_id 后，个人飞书账号能收到富文本通知
3	发起人展示	消息正文能展示流程发起人或上传人
4	接收人缺失	指定接收人缺失时不发送真实消息，并记录配置错误
5	token 管理	系统能获取并缓存 tenant_access_token，token 失效后可重新获取
6	判重	同一批次、同一流程、同一状态不会重复发送成功通知
7	失败不阻断	飞书接口失败时主工作流仍完成
8	记录落库	成功、失败、未启用、重复跳过均可追溯
9	页面展示	批次详情页展示通知状态和失败原因
10	问答预留	用户映射、查询服务边界和日志设计可支持后续私聊问答