DEMO-AGENT/docs/1.需求分析/4.飞书通知与问答接入.md

飞书通知与问答接入需求分析

文档信息

项目	内容
功能主题	飞书通知链路与飞书内问答能力接入
关联工作流	自动汇总、NMPA 注册资料法规核查与整改闭环、产品关键信息提取与申报文件自动填表
分析日期	2026-06-07
分析版本	V1.0
短期目标	流程结束后同步飞书提醒
终极目标	用户可在飞书内向 Agent 提问并获得基于系统数据的回答

---

一、需求背景

当前系统已经具备多个注册资料处理工作流，包括文件自动汇总、法规核查与整改闭环、产品关键信息提取与申报文件自动填表。系统内已经存在模拟通知记录和通知节点，但尚未接入真实飞书发送链路。

在实际业务协作中，注册人员、审核人员和整改负责人往往以飞书群或飞书私聊作为日常沟通入口。如果工作流只在系统页面内展示结果，用户需要主动返回系统查看状态，容易造成流程完成后无人跟进、整改项遗漏、生成文件未及时下载等问题。

因此需要引入飞书接入能力，分阶段实现：

1. 流程结束后自动向飞书发送提醒，完成从“系统内闭环”到“协作通知闭环”的升级。
2. 后续支持用户在飞书内与 Agent 对话，查询批次状态、风险项、生成文件、整改建议等信息。

---

二、接入方案调研摘要

2.1 主方案：飞书官方智能体/应用机器人 + 消息 API

飞书开放平台支持创建飞书智能体应用或企业自建应用机器人。系统通过 App ID 和 App Secret 获取 tenant_access_token，再调用飞书消息 API 向固定群发送流程完成提醒；后续通过事件订阅接收用户私聊机器人或群内 @ 机器人的消息，实现飞书内问答。

该方案同时覆盖短期“流程结束后提醒”和终极“飞书内问答”，避免先接自定义 Webhook、后续再迁移到应用机器人的重复建设。

核心能力：

能力	用途
飞书智能体/应用机器人	允许 Agent 以机器人身份进入飞书
tenant_access_token	使用 App ID、App Secret 换取应用访问令牌
发送消息 API	主动向用户或群聊发送文本、富文本、卡片、文件等消息
事件订阅	接收用户私聊机器人或群里 @ 机器人的消息
权限配置	申请发送消息、接收消息、读取用户或群组信息等权限

2.2 备选方案：飞书自定义机器人 Webhook

飞书自定义机器人 Webhook 适合只做固定群主动推送，但不适合飞书内问答、私聊回复和统一身份权限管理。本项目不将 Webhook 作为主接入方案，仅作为后续极简部署或故障降级备选。

2.3 参考官方文档

主题	参考地址
一键创建飞书智能体应用	https://open.feishu.cn/document/mcp_open_tools/integrating-agents-with-feishu/overview
机器人概述	https://open.feishu.cn/document/client-docs/bot-v3/bot-overview?lang=zh-CN
自建应用获取 tenant_access_token	https://open.feishu.cn/document/server-docs/authentication-management/access-token/tenant_access_token_internal?lang=zh-CN
发送消息 API	https://open.feishu.cn/document/server-docs/im-v1/message/create?lang=zh-CN
事件订阅概述	https://open.feishu.cn/document/server-docs/event-subscription-guide/overview?lang=zh-CN

---

三、总体目标

3.1 短期目标：流程结束后同步提醒到指定个人账号

当系统中的工作流执行结束后，自动通过飞书智能体向指定个人账号发送一条结构化私聊提醒。Demo 阶段先与当前系统负责人账号单独对接，不接入外部群聊。提醒内容应帮助用户快速判断：

信息项	说明
哪个流程完成	例如自动汇总、法规核查、自动填表
哪个批次完成	展示批次编号、会话标题或上传文件摘要
当前状态	成功、部分成功、失败、需人工确认
核心结果	风险数量、阻断项数量、生成文件数量、冲突字段数量等
下一步动作	查看报告、下载文件、处理整改项、回到系统确认
系统入口	提供可点击链接，跳转到对应批次或会话页面
被提醒人	首期固定发送给已配置的个人飞书账号

3.2 中期目标：按流程和责任人分发

在个人账号通知跑通后，逐步支持更精细的通知策略：

通知策略	说明
按发起人私聊	根据系统用户映射发送给流程发起人
按工作流分群	不同工作流通知到不同群
按项目分群	同一项目或产品线通知到指定群
按负责人私聊	将待处理事项发送给上传人、审核人或整改负责人
风险分级通知	阻断项和高风险立即通知，低风险可汇总通知

3.3 终极目标：飞书内问答

用户可以在飞书内向 Agent 提问，系统根据用户消息识别意图，查询本地业务数据和已生成结果，返回回答。

示例问题：

问题	预期回答
“最近一个法规核查批次结果怎么样？”	返回最近批次状态、风险数量和报告入口
“RR-20260607-001 有哪些阻断项？”	返回阻断项标题、法规依据、整改建议
“自动填表生成的 Word 在哪里？”	返回生成文件列表和下载入口
“这个批次还缺哪些资料？”	返回缺失文件清单和对应建议
“帮我解释第 3 个风险项”	返回风险说明、证据文件、整改建议和注意事项

---

四、需求范围

4.1 本期范围

序号	范围项	说明
1	真实飞书通知通道	接入飞书官方智能体/应用机器人消息 API
2	通知开关	通过环境变量控制是否启用真实飞书通知
3	保留 mock 通道	默认可回退到 mock，不影响本地开发和自动化测试
4	工作流完成通知	流程成功、部分成功或失败后发送飞书提醒
5	通知记录落库	记录通道、目标、发送状态、发送时间、错误信息和原始 payload
6	失败不阻断主流程	飞书发送失败只记录错误，不让业务工作流失败，首期不自动重试
7	消息模板	输出清晰的富文本消息，包含批次、状态、摘要和系统链接
8	安全配置	App ID、App Secret、事件订阅密钥等敏感配置不得写入代码库
9	基础测试	覆盖成功、失败、未启用、配置缺失、发送超时等场景

4.2 非本期范围

序号	范围项	说明
1	飞书内问答完整实现	本期只为后续问答预留架构，不直接实现复杂对话
2	飞书审批流	不接入飞书审批或表单能力
3	飞书文档写入	不自动创建或更新飞书文档
4	企业级组织架构同步	不做通讯录全量同步
5	多租户飞书应用管理	Demo 阶段只考虑单企业或单环境配置
6	复杂交互式卡片操作	本期优先文本或简单卡片，不实现按钮回调闭环

---

五、用户角色与使用场景

角色	诉求	典型场景
注册人员	及时知道批次完成并下载结果	自动汇总或自动填表完成后在飞书收到提醒
审核人员	快速查看法规核查风险摘要	法规核查结束后查看阻断项和高风险数量
整改负责人	及时处理缺失资料和风险项	飞书提醒中看到整改入口和主要问题
系统管理员	维护通知配置并排查发送失败	查看通知记录、错误信息和配置状态
后续飞书用户	不打开系统也能查询结果	在飞书中向机器人提问批次状态或风险项

---

六、业务流程

6.1 短期通知流程

用户发起业务工作流
-> 系统执行自动汇总、法规核查或自动填表
-> 工作流进入完成、部分成功或失败状态
-> 系统生成通知摘要
-> 系统判断飞书真实通知是否启用
-> 未启用：写入 mock 通知记录
-> 已启用：使用 App ID/App Secret 获取或复用 tenant_access_token
-> 调用飞书消息 API 向指定个人账号发送富文本消息
-> 发送成功：写入成功通知记录和 sent_at
-> 发送失败：写入失败通知记录、错误信息和重试次数
-> 主工作流继续完成，不因通知失败回滚业务结果

6.2 终极问答流程

用户在飞书私聊机器人或群里 @ 机器人提问
-> 飞书通过事件订阅将消息推送到系统回调地址
-> 系统校验事件来源和签名
-> 系统解析用户身份、会话位置和消息内容
-> 系统执行意图识别
-> 系统根据意图查询批次、文件、报告、风险项或生成结果
-> 系统组织回答内容
-> 系统通过飞书消息 API 回复用户或群聊
-> 系统记录问答日志、引用数据和错误信息

---

七、功能需求

7.1 通知触发点

工作流	触发节点	通知时机	初始优先级
自动汇总	文件汇总完成	成功、部分成功、失败	高
法规核查与整改闭环	风险分级和报告生成后	成功、部分成功、失败；阻断项和高风险优先展示	高
自动填表	Word/PDF 和追溯清单生成后	成功、部分成功、失败	高

首期三个业务工作流均接入飞书通知：自动汇总、法规核查与整改闭环、产品关键信息提取与申报文件自动填表。

7.2 通知内容模板

通知消息首期采用富文本格式，需支持换行和重点信息突出展示。通知消息应至少包含：

字段	说明
标题	工作流名称 + 状态
批次编号	例如 RR-NOTIFY、AFF-NOTIFY
发起人	当前系统用户
完成时间	工作流完成时间
结果摘要	风险数量、文件数量、导出文件数量、冲突字段数量等
下一步	查看报告、下载结果、处理整改项、重新复核
系统链接	首期使用本地地址拼接系统内批次或会话页面链接，例如 http://127.0.0.1:8000/...

发送策略：

策略项	要求
通知状态	成功、部分成功、失败均发送飞书通知
重复发送	同一批次、同一工作流、同一状态只发送一次，避免重复点击或重复运行造成刷屏
失败重试	首期不自动重试，只记录失败状态和错误信息
主流程影响	通知失败不阻断业务工作流完成

消息内容粒度：

粒度项	要求
基础信息	工作流名称、状态、批次编号、发起人、完成时间
结果摘要	自动汇总展示文件数和异常数；法规核查展示风险总数、阻断项、高风险数量；自动填表展示导出文件数、冲突字段数和失败原因概述
详细清单	首期不在飞书私聊中展开完整风险项、缺失项或文件明细，避免消息过长
系统入口	首期使用本地地址拼接系统内批次或会话链接，部署后再升级为可配置外部域名

7.3 通知状态记录

通知发送后必须落库，便于排查和审计。

字段	说明
channel	mock、feishu_api 等
target	指定个人 open_id、user_id 等
status	pending、sent、failed 或 success、failed
payload	发送内容摘要和业务上下文
external_message_id	飞书返回的消息 ID，Webhook 无返回时可为空
error_message	失败原因
retry_count	重试次数
sent_at	成功发送时间

7.4 配置需求

环境变量建议：

配置项	说明
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，可作为 open_id 的备选
FEISHU_DEFAULT_TARGET_NAME	默认通知目标名称，用于记录展示
FEISHU_TENANT_TOKEN_CACHE_SECONDS	tenant_access_token 本地缓存秒数
FEISHU_EVENT_VERIFY_TOKEN	事件订阅校验 Token，后续问答使用
FEISHU_EVENT_ENCRYPT_KEY	事件订阅加密 Key，后续问答使用

敏感配置不得提交到代码库，只能通过本地 .env、部署环境变量或密钥管理系统注入。

首期配置维护方式：

配置类型	维护方式	说明
飞书 App ID	环境变量	属于敏感信息，不进入数据库和代码库
飞书 App Secret	环境变量	属于敏感信息，不进入数据库和代码库
指定接收人 open_id/user_id	环境变量	首期固定发送到一个个人账号
通知开关	环境变量	便于本地、测试、部署环境切换
系统用户与飞书用户映射	Django Admin	便于非开发人员维护发起人和飞书用户标识

7.5 系统用户与飞书用户映射

首期采用手工配置表维护系统用户与飞书用户之间的映射关系。系统在发送固定群通知时，根据批次 user 字段找到流程发起人或上传人，再从映射表中读取可用于飞书 @ 的用户标识。

建议字段：

字段	说明
system_username	系统登录用户名
system_user_id	系统用户 ID，可选
feishu_display_name	飞书展示名称，便于管理员识别
feishu_mobile	飞书手机号，可选
feishu_open_id	飞书 open_id，可选
feishu_user_id	飞书 user_id，可选
is_active	是否启用该映射
remark	备注

首期实现时，系统优先将通知发送给环境变量中配置的指定个人账号。用户映射表仍保留，用于后续从“固定个人账号”升级为“按流程发起人私聊”。若指定接收人未配置，系统不发送真实飞书消息，只记录配置缺失失败。

当同一个系统用户配置了多个飞书标识时，首期按以下优先级选择 @ 标识：

feishu_open_id -> feishu_user_id -> feishu_mobile

7.6 通知记录展示

首期需要在对应批次详情页展示通知状态，帮助用户和管理员判断飞书提醒是否已发送。

展示项	说明
通知通道	mock、feishu_api 等
通知目标	指定个人账号名称或配置名称
接收人	首期指定接收人；后续可展示发起人/上传人的飞书展示名称
发送状态	成功、失败、待发送或未启用
发送时间	成功发送时间
失败原因	发送失败或配置异常时展示摘要

---

八、飞书内问答需求预留

8.1 问答入口

入口	说明
私聊机器人	首期入口，用户直接向机器人询问自己的批次、文件和报告
群聊 @ 机器人	群内成员 @ 机器人询问某个批次或风险项
通知消息引用	用户收到通知后，基于批次编号继续提问

8.2 问答能力边界

第一阶段飞书问答不应直接执行高风险写操作，只提供查询和解释：

能力	是否纳入首期问答
查询批次状态	是
查询风险项摘要	是
查询缺失项摘要	是
查询生成文件摘要	是
解释整改建议	否，作为后续增强
重新发起工作流	否
删除文件或记录	否
自动关闭风险项	否
修改申报文件	否

8.3 权限原则

飞书内问答必须解决用户身份和数据权限问题：

场景	要求
私聊查询	普通用户只能查询自己发起或上传的批次；管理员可以查询全部批次
群内查询	只返回适合在群内公开的信息，敏感文件链接需谨慎
未绑定用户	提示先完成系统用户与飞书用户绑定
无权限数据	返回无权限提示，不泄露批次是否存在以外的敏感信息

8.4 首期问答交互规则

首期私聊问答支持两类批次定位方式：

方式	示例	说明
明确批次号	“查 RR-20260607-001”	系统按批次编号精确查询
自然指代	“查最近一个法规核查批次”“最新自动填表结果怎么样”	系统在用户可访问范围内查找最近批次

问答回复规则：

规则	要求
链接返回	只有用户具备对应批次访问权限时才返回系统链接
无权限结果	提示无权限或无法访问，不返回敏感摘要和链接
回答粒度	返回批次状态、风险摘要、缺失摘要、导出摘要和下一步建议
日志留痕	记录用户问题、识别意图、查询对象、回答摘要、错误信息和处理时间，不保存完整回答正文

---

九、异常与安全要求

场景	处理方式
App ID/App Secret 或指定接收人未配置	自动回退 mock 或只记录未发送状态
tenant_access_token 获取失败	记录失败，不发送消息，不阻断主流程
飞书接口超时	记录失败，不阻断主流程
飞书返回错误	记录错误码和错误信息，便于排查
消息过长	自动截断摘要，系统链接保留完整结果；首期不发送详细风险项或缺失项清单
重复触发	同一批次、同一工作流、同一状态只发送一次
敏感信息	通知正文避免包含完整文件内容、密钥、个人敏感信息
外部链接	首期使用本地地址；部署环境应升级为可信域名配置
回调伪造	后续事件订阅必须校验来源、签名、Token 或加密参数

---

十、验收标准

10.1 短期通知验收

序号	验收项	标准
1	配置关闭	未启用飞书通知时，工作流仍可正常完成并记录 mock 通知
2	配置开启	配置 App ID、App Secret 和指定个人 open_id/user_id 后，流程完成会向个人飞书账号发送提醒
3	成功记录	发送成功后通知记录状态为成功，并记录发送时间
4	失败记录	token 获取失败、消息 API 错误、超时或配置错误时记录失败原因
5	不阻断主流程	通知失败不会导致工作流失败
6	内容完整	飞书消息包含工作流、批次、状态、摘要和系统入口
7	自动化测试	有单元测试覆盖通知构造、发送成功、发送失败、配置关闭
8	token 管理	系统能获取并缓存 tenant_access_token，token 失效后可重新获取
9	后台映射	管理员可在 Django Admin 维护系统用户与飞书用户映射

10.2 终极问答验收

序号	验收项	标准
1	消息接收	系统能接收飞书私聊或群 @ 机器人消息
2	身份识别	能识别飞书用户并关联系统用户
3	意图识别	能区分批次查询、风险查询、文件查询、解释类问题
4	权限控制	普通用户只能查询自己发起或上传的批次；管理员可查询全部批次
5	消息回复	系统能通过飞书消息 API 回复用户
6	日志留痕	用户问题、意图、查询对象、回答摘要和错误信息可追溯，不保存完整回答正文
7	批次定位	支持明确批次号和“最近一个/最新批次”等自然说法
8	链接控制	只有用户有权限访问时才返回系统链接

---

十一、阶段规划

阶段一：指定个人账号完成提醒

目标：使用飞书官方智能体/应用机器人消息 API 将流程完成提醒发送到指定个人账号。Demo 阶段先与当前系统负责人账号单独对接，暂不接入外部群聊。

建议内容：

内容	说明
通知通道抽象	将 mock 和 feishu_api 封装为可切换通道
消息模板	输出流程完成摘要
指定接收人	根据环境变量配置的 open_id/user_id 发送给指定个人账号
token 管理	使用 App ID/App Secret 获取并缓存 tenant_access_token
消息 API	使用指定个人 open_id/user_id 调用飞书发送消息 API
通知记录	发送结果落库
配置开关	环境变量控制启用与否
测试覆盖	不依赖真实飞书也能测试发送逻辑
批次详情展示	在批次详情页展示通知状态和失败原因

阶段一附加：飞书问答预留

目标：在不实现飞书事件回调和私聊问答的前提下，为后续问答 MVP 预留必要的数据结构、服务边界和权限规则。

建议内容：

内容	说明
用户映射复用	飞书用户映射模型同时服务 @ 通知和后续私聊身份识别
查询服务边界	预留按批次号、最近批次、工作流类型查询结果摘要的服务接口
权限过滤规则	查询服务内置管理员全查、普通用户查自己批次的权限规则
问答日志模型预留	可先设计模型或接口，不要求首期接收飞书消息

阶段二：按流程或项目分群

目标：支持不同流程、项目或业务线配置不同飞书目标。

建议内容：

内容	说明
通知路由	根据 workflow_type、project、batch 等选择目标
通知策略	风险等级、完成状态、失败状态决定是否通知
消息降噪	避免同一批次重复刷屏

阶段三：事件订阅与私聊问答

建议内容：

内容	说明
事件回调	接收飞书私聊消息事件
用户绑定	使用飞书 open_id/user_id 映射系统用户
问答处理	查询批次状态、风险摘要、缺失摘要和导出摘要
回复消息	继续使用消息 API 回复用户

阶段四：飞书内问答

目标：通过事件订阅接收用户消息，并调用系统 Agent 能力回答问题。

建议内容：

内容	说明
事件回调	接收私聊和群 @ 消息
意图识别	解析查询对象和问题类型
数据查询	查询批次、风险、文件、报告和通知记录
回答生成	返回简洁、可追溯、带链接的回答
安全审计	记录问答日志和权限判断

---

十二、待确认问题

编号	问题	推荐选项
Q1	短期通知发到哪里？固定飞书群、按业务群区分、还是按个人私聊？	已调整：先发送到指定个人账号，暂不接入外部群聊
Q2	首期接入哪些工作流？自动填表、法规核查、自动汇总是否都通知？	已确认：三个流程都通知
Q3	通知格式用普通文本、富文本还是飞书消息卡片？	已确认：首期使用富文本
Q4	系统链接使用本地地址还是部署域名？	Demo 本地，部署后改域名
Q5	是否需要 @ 指定人员？	已调整：首期为个人私聊通知，不需要群内 @
Q6	是否需要失败重试？	已确认：首期不自动重试，只记录失败
Q7	飞书内问答优先支持私聊还是群 @？	先私聊，后群 @

---

十三、已确认决策

编号	决策	影响
D1	短期通知发送到指定个人账号，暂不接入外部群聊	首期需要配置个人 open_id/user_id；后续再扩展群聊、按发起人私聊和责任矩阵
D2	首期接收人为配置中的固定个人账号	通知服务不再依赖批次 user 解析接收人；批次 user 仍用于摘要展示和后续按发起人私聊
D3	首期采用手工配置表维护系统用户与飞书用户映射	避免首期被通讯录权限、用户自动绑定和开放平台审核阻塞；后续可升级为自动绑定
D4	首期三个流程均发送飞书完成通知	自动汇总、法规核查、自动填表都需要接入统一通知服务；消息发送到指定个人账号
D5	首期通知格式采用飞书富文本	消息构造需支持富文本结构、换行、重点字段和 @ 用户标签；暂不实现消息卡片按钮
D6	成功、部分成功、失败三类状态均发送通知	消息模板需要按状态展示不同摘要和下一步动作
D7	同一批次、同一工作流、同一状态只发送一次	通知记录需要保存可判重的业务键，发送前先检查历史成功或已发送记录
D8	首期飞书发送失败不自动重试	通知失败只落库并暴露错误信息，不引入异步重试队列
D9	飞书消息链接首期使用本地地址	满足本机 Demo；部署环境后续升级为可信域名配置
D10	飞书消息采用摘要级内容粒度	私聊通知展示核心结果摘要和入口链接，不展开完整风险项、缺失项或文件明细
D11	指定个人接收人未配置时不发送真实飞书消息	记录配置缺失失败或回退 mock；用户映射缺失不影响首期固定个人通知
D12	通知记录只保存发送摘要，不保存完整富文本 payload	降低记录冗余和敏感信息留存风险；排查时依赖摘要、状态、错误信息和业务上下文
D13	App ID、App Secret、指定个人 open_id/user_id 等敏感配置通过环境变量维护，用户映射通过 Django Admin 维护	兼顾安全性和运维便利性；用户映射服务于后续按发起人私聊和问答身份识别
D14	首期使用 tenant_access_token + 飞书消息 API 发送通知	通知客户端需要实现 token 获取、缓存、失效重取和消息 API 错误处理
D15	飞书内问答首期入口为私聊机器人	优先解决个人查询场景，降低群聊权限泄露风险
D16	飞书内问答首期回答批次状态、风险摘要、缺失摘要和导出摘要	不在首期做具体风险解释和复杂整改建议生成
D17	私聊问答支持明确批次号和“最近/最新”自然说法	问答解析需要支持批次编号识别和按工作流类型查询最近可访问批次
D18	问答权限为管理员可查全部，普通用户只能查自己发起或上传的批次	需要识别系统管理员身份，并在查询层统一做权限过滤
D19	问答回复仅在用户有权限时返回系统链接	链接生成必须在权限校验之后执行
D20	问答日志记录问题、意图、查询对象和回答摘要，不保存完整回答	兼顾审计排查与敏感信息最小留存
D21	首期实现指定个人私聊通知，并预留飞书问答数据模型和服务边界	不在首期实现飞书事件回调和交互式问答，降低一次性交付风险
D22	批次详情页需要展示通知状态	用户无需进入数据库或 Admin 即可确认飞书提醒是否发送成功
D23	多个飞书标识的 @ 优先级为 open_id > user_id > mobile	优先使用稳定标识，手机号作为兜底
D24	本需求文档版本升级为 V1.0	当前决策已足够进入功能设计阶段