Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(feishu): 提交飞书接入文档和本地配置

Browse Source
This commit is contained in:
bruce
2026-06-07 22:36:04 +08:00
parent f23e403eb8
commit 90144c42ac
6 changed files with 2314 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.env
View File

@@ -17,3 +17,9 @@ SCENARIO_CONFIG_DIR=configs
GOVERNANCE_CONFIG_PATH=configs/governance.yaml
UPLOAD_ROOT=data/uploads
CHROMA_PATH=data/chroma
FEISHU_NOTIFY_ENABLED=true
FEISHU_APP_ID=cli_aaafcc59f4b85bc2
FEISHU_APP_SECRET=OO8GKpjqTO3bHAUwCiSmRgW4FqsNB5Qa
FEISHU_DEFAULT_USER_OPEN_ID=ou_a6015773781a117eb7d8995efa5e4590
FEISHU_DEFAULT_TARGET_NAME=bruce
PUBLIC_BASE_URL=http://127.0.0.1:8000

527
docs/1.需求分析/4.飞书通知与问答接入.md Normal file
View File

@@ -0,0 +1,527 @@
# 飞书通知与问答接入需求分析
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 功能主题 | 飞书通知链路与飞书内问答能力接入 |
| 关联工作流 | 自动汇总、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 短期通知流程
```text
用户发起业务工作流
-> 系统执行自动汇总、法规核查或自动填表
-> 工作流进入完成、部分成功或失败状态
-> 系统生成通知摘要
-> 系统判断飞书真实通知是否启用
-> 未启用：写入 mock 通知记录
-> 已启用：使用 App ID/App Secret 获取或复用 tenant_access_token
-> 调用飞书消息 API 向指定个人账号发送富文本消息
-> 发送成功：写入成功通知记录和 sent_at
-> 发送失败：写入失败通知记录、错误信息和重试次数
-> 主工作流继续完成，不因通知失败回滚业务结果
```
### 6.2 终极问答流程
```text
用户在飞书私聊机器人或群里 @ 机器人提问
-> 飞书通过事件订阅将消息推送到系统回调地址
-> 系统校验事件来源和签名
-> 系统解析用户身份、会话位置和消息内容
-> 系统执行意图识别
-> 系统根据意图查询批次、文件、报告、风险项或生成结果
-> 系统组织回答内容
-> 系统通过飞书消息 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 | 备注 |
首期实现时，系统优先将通知发送给环境变量中配置的指定个人账号。用户映射表仍保留，用于后续从“固定个人账号”升级为“按流程发起人私聊”。若指定接收人未配置，系统不发送真实飞书消息，只记录配置缺失失败。
当同一个系统用户配置了多个飞书标识时，首期按以下优先级选择 @ 标识：
```text
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 | 当前决策已足够进入功能设计阶段 |

292
docs/2.功能设计/4.飞书通知与问答接入.md Normal file
View File

@@ -0,0 +1,292 @@
# 飞书通知与问答接入功能设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 需求分析文档 | 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 逻辑架构
```mermaid
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 主流程
```text
业务工作流进入 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` 类型。首期内容只放摘要，不展开完整风险项和缺失项。
```json
{
"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 接收人标识优先级
首期接收人来自环境变量配置。若同时配置多个飞书标识，按以下优先级选取：
```text
FEISHU_DEFAULT_USER_OPEN_ID -> FEISHU_DEFAULT_USER_ID
```
若无可用接收人标识，系统不发送真实飞书消息，并记录配置缺失失败。
用户映射表仍保留，用于后续从“固定个人账号”升级为“按发起人私聊”。
### 6.3 系统链接
首期使用本地地址，例如：
```text
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 | 问答预留 | 用户映射、查询服务边界和日志设计可支持后续私聊问答 |

604
docs/3.详细设计/4.飞书通知与问答接入.md Normal file
View File

@@ -0,0 +1,604 @@
# 飞书通知与问答接入详细设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 需求分析文档 | docs/1.需求分析/4.飞书通知与问答接入.md |
| 功能设计文档 | docs/2.功能设计/4.飞书通知与问答接入.md |
| 数据库设计文档 | docs/4.数据库设计/4.飞书通知与问答接入.md |
| 所属模块 | 审核智能体 review_agent |
| 设计日期 | 2026-06-07 |
| 设计版本 | V1.0 |
---
## 一、实现目标
首期实现一个统一飞书通知能力，使自动汇总、法规核查、自动填表三个工作流在完成、部分成功或失败时，通过飞书官方智能体/应用机器人消息 API 向指定个人账号发送富文本私聊通知。通知失败不阻断主流程，发送结果落库并在批次详情页展示。
同时预留飞书私聊问答所需的用户映射、查询服务、权限过滤和问答日志模型，但不实现飞书事件订阅回调。
---
## 二、推荐文件结构
| 文件 | 类型 | 责任 |
| --- | --- | --- |
| `review_agent/models.py` | 修改 | 新增 `FeishuUserMapping`、`WorkflowNotificationRecord`、`FeishuQuestionLog` |
| `review_agent/admin.py` | 修改/新增 | 注册飞书用户映射和通知记录后台 |
| `review_agent/notifications/__init__.py` | 新增 | 通知模块包 |
| `review_agent/notifications/context.py` | 新增 | 定义统一通知上下文 dataclass |
| `review_agent/notifications/recipient.py` | 新增 | 解析首期指定个人接收人；后续扩展为按系统用户映射解析 |
| `review_agent/notifications/message_builder.py` | 新增 | 构造飞书富文本 payload 和摘要 |
| `review_agent/notifications/feishu_token.py` | 新增 | 使用 App ID/App Secret 获取并缓存 tenant_access_token |
| `review_agent/notifications/feishu_message_api.py` | 新增 | 调用飞书发送消息 API、处理响应解析 |
| `review_agent/notifications/records.py` | 新增 | 判重和通知记录落库 |
| `review_agent/notifications/dispatcher.py` | 新增 | 对外统一发送入口 |
| `review_agent/notifications/workflow_adapters.py` | 新增 | 三个工作流批次到通知上下文的适配 |
| `review_agent/feishu_questions/query.py` | 新增 | 后续问答预留：批次摘要查询 |
| `review_agent/feishu_questions/permissions.py` | 新增 | 后续问答预留：权限过滤 |
| `tests/test_feishu_notification.py` | 新增 | 飞书通知单元测试 |
| `tests/test_feishu_question_reserved.py` | 新增 | 问答预留服务测试 |
---
## 三、数据结构设计
### 3.1 NotificationContext
```python
from dataclasses import dataclass, field
from typing import Any
@dataclass(frozen=True)
class NotificationContext:
workflow_type: str
workflow_batch_id: int
workflow_batch_no: str
workflow_status: str
title: str
trigger_user_id: int
trigger_username: str
result_url: str
summary_lines: list[str] = field(default_factory=list)
next_action: str = ""
metadata: dict[str, Any] = field(default_factory=dict)
@property
def dedupe_key(self) -> str:
return f"{self.workflow_type}:{self.workflow_batch_id}:{self.workflow_status}"
```
### 3.2 ResolvedFeishuTarget
```python
from dataclasses import dataclass
@dataclass(frozen=True)
class ResolvedFeishuTarget:
mapping_id: int | None
display_name: str
identifier_type: str
identifier_value: str
masked_identifier: str
missing: bool = False
```
identifier_type 取值：
| 值 | 说明 |
| --- | --- |
| open_id | 使用飞书 open_id |
| user_id | 使用飞书 user_id |
| mobile | 使用手机号，后续按发起人私聊时使用 |
| missing | 未配置映射 |
---
## 四、模型详细设计
### 4.1 FeishuUserMapping
字段见数据库设计。模型需提供方法：
```python
def preferred_identifier(self) -> tuple[str, str]:
if self.feishu_open_id:
return "open_id", self.feishu_open_id
if self.feishu_user_id:
return "user_id", self.feishu_user_id
if self.feishu_mobile:
return "mobile", self.feishu_mobile
return "missing", ""
```
`clean()` 校验：
```python
def clean(self):
if not (self.feishu_open_id or self.feishu_user_id or self.feishu_mobile):
raise ValidationError("feishu_open_id、feishu_user_id、feishu_mobile 至少填写一个")
```
### 4.2 WorkflowNotificationRecord
字段见数据库设计。建议方法：
```python
@classmethod
def already_sent(cls, dedupe_key: str) -> bool:
return cls.objects.filter(dedupe_key=dedupe_key, send_status=cls.SendStatus.SUCCESS).exists()
```
注意：若使用唯一约束限制 `dedupe_key`，重复触发时可以直接返回已有记录；若希望保留 skipped_duplicate 记录，则不能对 dedupe_key 做全局唯一，只能用查询判重。本项目需求是“只发一次”，更推荐保留唯一成功意图，重复触发返回已有记录或创建 skipped 记录需在实现计划中二选一。为了 SQLite 简化，首期建议不创建 skipped 记录，直接返回已有成功记录。
---
## 五、核心服务详细设计
### 5.1 workflow_adapters.py
职责：把不同批次对象转换为 `NotificationContext`。
函数：
```python
def build_file_summary_context(batch: FileSummaryBatch) -> NotificationContext: ...
def build_regulatory_review_context(batch: RegulatoryReviewBatch) -> NotificationContext: ...
def build_application_form_fill_context(batch: ApplicationFormFillBatch) -> NotificationContext: ...
```
自动汇总摘要：
| 字段 | 计算方式 |
| --- | --- |
| 文件总数 | `batch.items.count()` |
| 成功解析数 | 解析状态为 success 的 item 数 |
| 异常数 | failed、skipped、unsupported 等状态数量 |
| 导出文件数 | `ExportedSummaryFile` 中 workflow_type=file_summary 或 batch 关联文件数 |
法规核查摘要：
| 字段 | 计算方式 |
| --- | --- |
| 风险总数 | `batch.issues.count()` |
| 阻断项 | severity=blocking |
| 高风险 | severity=high |
| 中风险 | severity=medium |
自动填表摘要：
| 字段 | 计算方式 |
| --- | --- |
| 模板数 | `len(batch.selected_templates)` |
| 导出文件数 | 对应 `ExportedSummaryFile` 数量 |
| 冲突字段数 | `len(batch.conflict_summary or [])` |
| 失败原因 | `batch.error_message` 或节点错误摘要 |
### 5.2 recipient.py
职责：首期根据环境变量解析指定个人接收人；后续可扩展为根据系统用户解析飞书目标。
伪代码：
```python
def resolve_feishu_target(user: User) -> ResolvedFeishuTarget:
if settings.FEISHU_DEFAULT_USER_OPEN_ID:
return ResolvedFeishuTarget(
mapping_id=None,
display_name=getattr(settings, "FEISHU_DEFAULT_TARGET_NAME", "指定个人账号"),
identifier_type="open_id",
identifier_value=settings.FEISHU_DEFAULT_USER_OPEN_ID,
masked_identifier=mask_identifier(settings.FEISHU_DEFAULT_USER_OPEN_ID),
missing=False,
)
if settings.FEISHU_DEFAULT_USER_ID:
return ResolvedFeishuTarget(
mapping_id=None,
display_name=getattr(settings, "FEISHU_DEFAULT_TARGET_NAME", "指定个人账号"),
identifier_type="user_id",
identifier_value=settings.FEISHU_DEFAULT_USER_ID,
masked_identifier=mask_identifier(settings.FEISHU_DEFAULT_USER_ID),
missing=False,
)
return ResolvedFeishuTarget(
mapping_id=None,
display_name=user.get_username(),
identifier_type="missing",
identifier_value="",
masked_identifier="",
missing=True,
)
def resolve_feishu_target_by_user_mapping(user: User) -> ResolvedFeishuTarget:
mapping = (
FeishuUserMapping.objects
.filter(system_user=user, is_active=True)
.first()
)
if mapping is None:
return ResolvedFeishuTarget(
mapping_id=None,
display_name=user.get_username(),
identifier_type="missing",
identifier_value="",
masked_identifier="",
missing=True,
)
identifier_type, identifier_value = mapping.preferred_identifier()
return ResolvedFeishuTarget(
mapping_id=mapping.pk,
display_name=mapping.feishu_display_name or user.get_username(),
identifier_type=identifier_type,
identifier_value=identifier_value,
masked_identifier=mask_identifier(identifier_value),
missing=identifier_type == "missing",
)
```
脱敏规则：
| 类型 | 规则 |
| --- | --- |
| mobile | 保留前三位和后四位，如 `138****1234` |
| open_id/user_id | 保留前 6 位和后 4 位 |
| missing | 空字符串 |
首期调度器使用 `resolve_feishu_target()`。`resolve_feishu_target_by_user_mapping()` 作为后续“按发起人私聊”能力预留。
### 5.3 message_builder.py
职责：构造富文本 payload 和入库摘要。
函数：
```python
def build_feishu_post_message(
context: NotificationContext,
target: ResolvedFeishuTarget,
) -> dict: ...
def build_message_summary(
context: NotificationContext,
target: ResolvedFeishuTarget,
) -> str: ...
```
富文本规则：
| 场景 | 规则 |
| --- | --- |
| 有映射 | 加入 `at` 标签 |
| 无映射 | 不加入 `at` 标签，增加映射缺失提示 |
| 失败状态 | 标题和下一步动作突出失败原因摘要 |
| 摘要过长 | 每条摘要最多 120 字，总摘要最多 800 字 |
| 链接 | 使用本地地址拼接，后续再切换域名配置 |
### 5.4 feishu_token.py
职责：使用 App ID/App Secret 获取并缓存 `tenant_access_token`。
函数：
```python
def get_tenant_access_token() -> FeishuTokenResult: ...
def refresh_tenant_access_token() -> FeishuTokenResult: ...
```
结果结构：
```python
@dataclass(frozen=True)
class FeishuTokenResult:
ok: bool
tenant_access_token: str
expire_seconds: int
code: str
message: str
```
处理规则：
| 场景 | 处理 |
| --- | --- |
| App ID/App Secret 缺失 | 返回 failed，错误码 config_missing |
| 缓存 token 未过期 | 直接返回缓存 token |
| token 过期或不存在 | 调用飞书 token API 重新获取 |
| token API 返回失败 | 返回 failed，记录 code/message |
| HTTP 超时 | 返回 failed，错误码 timeout |
### 5.5 feishu_message_api.py
职责：调用飞书发送消息 API。
函数：
```python
def send_personal_message(
*,
tenant_access_token: str,
receive_id_type: str,
receive_id: str,
payload: dict,
) -> FeishuMessageApiResult: ...
```
结果结构：
```python
@dataclass(frozen=True)
class FeishuMessageApiResult:
ok: bool
status_code: int | None
code: str
message: str
duration_ms: int
message_id: str = ""
```
异常处理：
| 异常 | 处理 |
| --- | --- |
| 指定接收人缺失 | 返回 failed，错误码 recipient_missing |
| tenant_access_token 缺失 | 返回 failed，错误码 token_missing |
| HTTP 超时 | 返回 failed，错误码 timeout |
| 非 2xx | 返回 failed，记录 status_code |
| 飞书返回 code 非 0 | 返回 failed，记录 code/message |
| token 失效 | 刷新 token 后允许同步重试一次消息 API |
### 5.6 records.py
职责：判重和落库。
流程：
```text
输入 NotificationContext
-> 查询 dedupe_key 是否已有 success
-> 若有，返回已有记录，不发送
-> 若未启用真实飞书，创建 disabled/mock 记录
-> 若发送成功，创建 success 记录
-> 若发送失败，创建 failed 记录
```
字段写入规则：
| 字段 | 来源 |
| --- | --- |
| workflow_type | context.workflow_type |
| workflow_batch_id | context.workflow_batch_id |
| workflow_batch_no | context.workflow_batch_no |
| workflow_status | context.workflow_status |
| dedupe_key | context.dedupe_key |
| trigger_user_id | context.trigger_user_id |
| feishu_mapping_id | target.mapping_id |
| at_identifier_type | target.identifier_type |
| at_identifier_masked | target.masked_identifier |
| message_summary | `build_message_summary()` |
### 5.7 dispatcher.py
对外入口：
```python
def dispatch_workflow_notification(context: NotificationContext) -> WorkflowNotificationRecord:
if WorkflowNotificationRecord.already_sent(context.dedupe_key):
return WorkflowNotificationRecord.objects.get(
dedupe_key=context.dedupe_key,
send_status=WorkflowNotificationRecord.SendStatus.SUCCESS,
)
user = User.objects.get(pk=context.trigger_user_id)
target = resolve_feishu_target(user)
message = build_feishu_post_message(context, target)
summary = build_message_summary(context, target)
if not settings.FEISHU_NOTIFY_ENABLED:
return create_disabled_record(context, target, summary)
token_result = get_tenant_access_token()
if not token_result.ok:
return create_failed_record(context, target, summary, token_result)
result = send_personal_message(
tenant_access_token=token_result.tenant_access_token,
receive_id_type=target.identifier_type,
receive_id=target.identifier_value,
payload=message,
)
if result.ok:
return create_success_record(context, target, summary, result)
return create_failed_record(context, target, summary, result)
```
---
## 六、工作流接入点
| 工作流 | 推荐接入位置 |
| --- | --- |
| 自动汇总 | 文件汇总批次状态写为 success/partial_success/failed 后 |
| 法规核查 | 报告导出和风险项保存后；替换或并行现有 `create_mock_notifications` |
| 自动填表 | `notify` 节点中替换或扩展现有 `notify_completion` |
接入原则：
| 原则 | 说明 |
| --- | --- |
| 通知异常捕获 | 工作流调用通知服务时捕获异常并记录 non_blocking_errors |
| 不回滚业务结果 | 通知失败不修改业务批次成功状态 |
| 单点适配 | 工作流只负责生成或传入批次，摘要由 adapter 负责 |
---
## 七、批次详情展示设计
### 7.1 后端上下文
为批次详情页提供：
```python
def get_notification_records(workflow_type: str, batch_id: int) -> QuerySet:
return WorkflowNotificationRecord.objects.filter(
workflow_type=workflow_type,
workflow_batch_id=batch_id,
).order_by("-created_at")
```
### 7.2 页面展示规则
| 状态 | 展示 |
| --- | --- |
| success | “飞书通知已发送”，展示 sent_at |
| failed | “飞书通知失败”，展示 error_message |
| disabled | “飞书通知未启用” |
| 无记录 | “暂无通知记录” |
三个工作流结果页可复用同一 partial 模板或上下文字段。
---
## 八、问答预留详细设计
### 8.1 批次摘要查询服务
预留函数：
```python
def query_batch_summary(
user: User,
*,
workflow_type: str | None = None,
batch_no: str | None = None,
latest: bool = False,
) -> dict:
...
```
权限规则：
| 用户 | 可查范围 |
| --- | --- |
| 管理员 | 全部批次 |
| 普通用户 | `batch.user == user` 的批次 |
| 未绑定用户 | 不可查 |
查询对象：
| 类型 | 说明 |
| --- | --- |
| 明确批次号 | 精确匹配 batch_no |
| 最近/最新 | 在有权限范围内按 created_at/finished_at 倒序取第一条 |
| 工作流类型 | file_summary、regulatory_review、application_form_fill |
### 8.2 问答日志服务
预留函数：
```python
def record_feishu_question_log(
*,
user: User | None,
mapping: FeishuUserMapping | None,
source_type: str,
question_text: str,
intent: str,
query_object: dict,
answer_summary: str,
permission_result: str,
status: str,
error_message: str = "",
) -> FeishuQuestionLog:
...
```
首期不需要接飞书事件，但测试可直接调用该服务，确认日志字段与权限规则可用。
---
## 九、测试设计
### 9.1 单元测试
| 测试文件 | 用例 |
| --- | --- |
| `tests/test_feishu_notification.py` | tenant_access_token 获取和缓存 |
| `tests/test_feishu_notification.py` | 指定个人接收人优先级 open_id > user_id |
| `tests/test_feishu_notification.py` | 指定接收人缺失时写 failed 记录 |
| `tests/test_feishu_notification.py` | 真实通知关闭时写 disabled/mock 记录 |
| `tests/test_feishu_notification.py` | 消息 API 成功写 success 记录 |
| `tests/test_feishu_notification.py` | token 获取失败写 failed 记录 |
| `tests/test_feishu_notification.py` | 消息 API 超时写 failed 记录 |
| `tests/test_feishu_notification.py` | 同一 dedupe_key 不重复发送 |
| `tests/test_feishu_question_reserved.py` | 管理员可查询全部批次摘要 |
| `tests/test_feishu_question_reserved.py` | 普通用户只能查询自己的批次 |
| `tests/test_feishu_question_reserved.py` | 问答日志不保存完整回答正文 |
### 9.2 集成测试
| 场景 | 验证 |
| --- | --- |
| 自动汇总完成 | 生成通知上下文并写记录 |
| 法规核查完成 | 风险摘要正确 |
| 自动填表完成 | 导出和冲突摘要正确 |
| 批次详情页 | 展示通知状态和失败原因 |
### 9.3 外部飞书测试
真实飞书 API 测试不进入默认 CI。建议提供手动命令或 Django management command：
```text
python manage.py send_test_feishu_notification --username owner
```
该命令只在本地配置 `FEISHU_NOTIFY_ENABLED=true`、`FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_DEFAULT_USER_OPEN_ID` 或 `FEISHU_DEFAULT_USER_ID` 后使用。
---
## 十、异常处理
| 异常 | 处理 |
| --- | --- |
| 指定接收人缺失 | 不发送真实消息，记录 recipient_missing |
| App ID/App Secret 未配置 | 写 failed 或 disabled 记录，不发送 |
| tenant_access_token 获取失败 | 写 failed，记录 token API 错误 |
| 指定接收人 open_id/user_id 未配置 | 写 failed，错误码 recipient_missing |
| HTTP 超时 | 写 failed，错误码 timeout |
| 飞书返回错误 | 写 failed，记录 code/message |
| 通知记录唯一冲突 | 查询已有记录并返回，不重复发送 |
| 批次链接生成失败 | 发送无链接摘要，记录 warning 到 message_summary |
---
## 十一、日志与安全
| 项 | 要求 |
| --- | --- |
| 日志脱敏 | 不打印 App Secret、tenant_access_token、完整手机号 |
| 入库脱敏 | 通知记录只保存脱敏接收人标识 |
| payload | 不保存完整富文本 payload |
| 错误信息 | 保存飞书错误摘要，避免保存敏感请求头 |
| 问答日志 | 保存问题、意图、对象和回答摘要，不保存完整回答 |
---
## 十二、实施顺序建议
| 顺序 | 内容 |
| --- | --- |
| 1 | 新增模型、迁移和 Admin |
| 2 | 实现用户映射解析和脱敏 |
| 3 | 实现飞书富文本构造 |
| 4 | 实现 tenant_access_token 获取与缓存 |
| 5 | 实现飞书消息 API 发送客户端 |
| 6 | 实现通知记录判重和落库 |
| 7 | 实现三个工作流 adapter |
| 8 | 接入三个工作流完成节点 |
| 9 | 批次详情页展示通知状态 |
| 10 | 实现问答预留查询服务和日志服务 |
| 11 | 补齐单元测试和集成测试 |

302
docs/4.数据库设计/4.飞书通知与问答接入.md Normal file
View File

@@ -0,0 +1,302 @@
# 飞书通知与问答接入数据库设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 需求分析文档 | docs/1.需求分析/4.飞书通知与问答接入.md |
| 功能设计文档 | docs/2.功能设计/4.飞书通知与问答接入.md |
| 数据库类型 | SQLite / Django ORM |
| 表名前缀 | ra_ |
| 设计日期 | 2026-06-07 |
| 设计版本 | V1.0 |
---
## 一、设计原则
| 原则 | 说明 |
| --- | --- |
| 统一通知抽象 | 三个工作流共用统一通知服务和通用通知记录，减少重复实现 |
| 兼容现有表 | 现有法规通知、填表通知可保留；新增通用表作为后续统一入口 |
| 可判重 | 通知记录必须支持同一批次、同一流程、同一状态只发送一次 |
| 摘要入库 | 只保存发送摘要、状态、错误，不保存完整富文本 payload |
| 映射可维护 | 系统用户与飞书用户映射独立建表，通过 Django Admin 维护 |
| 问答可扩展 | 预留问答日志表，首期可不接事件回调 |
| SQLite 兼容 | 使用 Django ORM 常规字段，避免数据库特有能力 |
---
## 二、ER 图
```mermaid
erDiagram
AUTH_USER ||--o{ RA_FEISHU_USER_MAPPING : maps
AUTH_USER ||--o{ RA_WORKFLOW_NOTIFICATION_RECORD : triggers
RA_FEISHU_USER_MAPPING ||--o{ RA_WORKFLOW_NOTIFICATION_RECORD : resolves
AUTH_USER ||--o{ RA_FEISHU_QUESTION_LOG : asks
RA_WORKFLOW_NOTIFICATION_RECORD {
bigint id
string workflow_type
bigint workflow_batch_id
string workflow_status
string dedupe_key
string channel
string target
string send_status
}
RA_FEISHU_USER_MAPPING {
bigint id
bigint system_user_id
string feishu_open_id
string feishu_user_id
string feishu_mobile
boolean is_active
}
RA_FEISHU_QUESTION_LOG {
bigint id
bigint system_user_id
string feishu_open_id
string intent
string query_object
string status
}
```
---
## 三、表结构设计
### 3.1 ra_feishu_user_mapping
系统用户与飞书用户标识映射表。首期通知发送给环境变量中配置的指定个人账号，本表通过 Django Admin 手工维护，用于后续按发起人私聊通知和飞书私聊问答身份识别。
| 字段名 | Django 类型 | SQLite 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | BigAutoField | integer | 是 | 主键 |
| system_user_id | ForeignKey | bigint | 是 | 关联 Django 用户 |
| feishu_display_name | CharField(120) | varchar(120) | 否 | 飞书展示名，便于后台识别 |
| feishu_open_id | CharField(120) | varchar(120) | 否 | 飞书 open_id，优先用于 @ |
| feishu_user_id | CharField(120) | varchar(120) | 否 | 飞书 user_id，第二优先级 |
| feishu_mobile | CharField(40) | varchar(40) | 否 | 飞书手机号，兜底 |
| is_active | BooleanField | bool | 是 | 是否启用 |
| remark | CharField(255) | varchar(255) | 否 | 备注 |
| created_at | DateTimeField | datetime | 是 | 创建时间 |
| updated_at | DateTimeField | datetime | 是 | 更新时间 |
约束：
| 约束名 | 字段 | 说明 |
| --- | --- | --- |
| uq_ra_feishu_mapping_user | system_user_id | 一个系统用户首期只维护一条启用映射 |
索引：
| 索引名 | 字段 | 说明 |
| --- | --- | --- |
| idx_ra_feishu_mapping_active | is_active | 后台筛选启用映射 |
| idx_ra_feishu_mapping_open | feishu_open_id | 后续私聊事件反查用户 |
| idx_ra_feishu_mapping_userid | feishu_user_id | 后续私聊事件反查用户 |
| idx_ra_feishu_mapping_mobile | feishu_mobile | 手机号兜底查询 |
校验规则：
| 规则 | 说明 |
| --- | --- |
| 至少一个飞书标识 | `feishu_open_id`、`feishu_user_id`、`feishu_mobile` 至少填写一个 |
| @ 优先级 | `feishu_open_id -> feishu_user_id -> feishu_mobile` |
---
### 3.2 ra_workflow_notification_record
通用工作流通知记录表。用于记录自动汇总、法规核查、自动填表的飞书通知发送结果。现有专项通知表可继续保留，后续逐步收敛到本表。
| 字段名 | Django 类型 | SQLite 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | BigAutoField | integer | 是 | 主键 |
| workflow_type | CharField(40) | varchar(40) | 是 | file_summary、regulatory_review、application_form_fill |
| workflow_batch_id | PositiveBigIntegerField | bigint | 是 | 对应工作流批次 ID |
| workflow_batch_no | CharField(80) | varchar(80) | 是 | 批次编号冗余，便于展示 |
| workflow_status | CharField(40) | varchar(40) | 是 | success、partial_success、failed 等 |
| dedupe_key | CharField(160) | varchar(160) | 是 | 判重键 |
| trigger_user_id | ForeignKey | bigint | 是 | 发起人或上传人 |
| feishu_mapping_id | ForeignKey | bigint | 否 | 命中的飞书用户映射 |
| channel | CharField(40) | varchar(40) | 是 | mock、feishu_api、disabled |
| target | CharField(160) | varchar(160) | 否 | 指定个人账号名称、open_id、user_id 或目标标识 |
| at_display_name | CharField(120) | varchar(120) | 否 | 被 @ 人展示名 |
| at_identifier_type | CharField(30) | varchar(30) | 否 | open_id、user_id、mobile、missing |
| at_identifier_masked | CharField(120) | varchar(120) | 否 | 脱敏后的 @ 标识 |
| send_status | CharField(30) | varchar(30) | 是 | pending、success、failed、skipped_duplicate、disabled |
| message_title | CharField(200) | varchar(200) | 是 | 通知标题 |
| message_summary | TextField | text | 否 | 发送摘要，不保存完整 payload |
| result_url | CharField(500) | varchar(500) | 否 | 系统结果入口 |
| external_message_id | CharField(120) | varchar(120) | 否 | Webhook 一般为空，API 发送时保存 |
| error_code | CharField(80) | varchar(80) | 否 | 飞书或客户端错误码 |
| error_message | TextField | text | 否 | 失败原因 |
| request_duration_ms | PositiveIntegerField | integer | 否 | HTTP 请求耗时 |
| sent_at | DateTimeField | datetime | 否 | 成功发送时间 |
| created_at | DateTimeField | datetime | 是 | 创建时间 |
| updated_at | DateTimeField | datetime | 是 | 更新时间 |
唯一约束：
| 约束名 | 字段 | 说明 |
| --- | --- | --- |
| uq_ra_notify_dedupe_key | dedupe_key | 同一批次、流程、状态只保留一个成功发送意图 |
索引：
| 索引名 | 字段 | 说明 |
| --- | --- | --- |
| idx_ra_notify_workflow | workflow_type, workflow_batch_id | 批次详情页查询通知 |
| idx_ra_notify_user_created | trigger_user_id, created_at | 用户通知历史 |
| idx_ra_notify_status | send_status, created_at | 排查失败通知 |
| idx_ra_notify_batch_no | workflow_batch_no | 按批次编号检索 |
dedupe_key 生成规则：
```text
{workflow_type}:{workflow_batch_id}:{workflow_status}
```
---
### 3.3 ra_feishu_question_log
飞书问答日志预留表。首期可创建表但不接入事件回调；后续私聊问答 MVP 使用该表记录问题、意图、查询对象、回答摘要和错误信息。
| 字段名 | Django 类型 | SQLite 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | BigAutoField | integer | 是 | 主键 |
| system_user_id | ForeignKey | bigint | 否 | 识别出的系统用户 |
| feishu_mapping_id | ForeignKey | bigint | 否 | 命中的飞书映射 |
| feishu_open_id | CharField(120) | varchar(120) | 否 | 事件中的 open_id |
| feishu_user_id | CharField(120) | varchar(120) | 否 | 事件中的 user_id |
| source_type | CharField(30) | varchar(30) | 是 | private_chat、group_mention |
| message_id | CharField(120) | varchar(120) | 否 | 飞书消息 ID |
| question_text | TextField | text | 是 | 用户原始问题 |
| intent | CharField(60) | varchar(60) | 否 | batch_status、risk_summary、export_summary 等 |
| query_object | JSONField | text/json | 是 | 批次号、工作流类型、最近批次等查询对象 |
| answer_summary | TextField | text | 否 | 回答摘要，不保存完整回答正文 |
| permission_result | CharField(40) | varchar(40) | 否 | allowed、denied、unbound |
| status | CharField(30) | varchar(30) | 是 | success、failed、ignored |
| error_message | TextField | text | 否 | 异常说明 |
| processed_at | DateTimeField | datetime | 否 | 处理完成时间 |
| created_at | DateTimeField | datetime | 是 | 创建时间 |
索引：
| 索引名 | 字段 | 说明 |
| --- | --- | --- |
| idx_ra_feishu_q_user_created | system_user_id, created_at | 用户问答历史 |
| idx_ra_feishu_q_intent | intent, created_at | 按意图分析 |
| idx_ra_feishu_q_status | status, created_at | 排查失败问答 |
| idx_ra_feishu_q_message | message_id | 消息幂等 |
---
## 四、状态枚举
### 4.1 WorkflowNotificationRecord.channel
| 值 | 说明 |
| --- | --- |
| mock | 模拟通知 |
| disabled | 真实通知未启用 |
| feishu_api | 飞书官方智能体/企业自建应用消息 API |
| feishu_webhook | 备选自定义机器人 Webhook，非首期主方案 |
### 4.2 WorkflowNotificationRecord.send_status
| 值 | 说明 |
| --- | --- |
| pending | 待发送 |
| success | 发送成功 |
| failed | 发送失败 |
| skipped_duplicate | 重复通知跳过 |
| disabled | 未启用真实发送 |
### 4.3 FeishuQuestionLog.intent
| 值 | 说明 |
| --- | --- |
| batch_status | 查询批次状态 |
| risk_summary | 查询风险摘要 |
| missing_summary | 查询缺失摘要 |
| export_summary | 查询导出摘要 |
| unknown | 未识别 |
---
## 五、与现有表的兼容关系
| 现有表 | 处理建议 |
| --- | --- |
| `ra_regulatory_notification_record` | 保留现有数据；法规核查真实飞书通知可新增写入通用表，后续再决定是否迁移 |
| `ra_application_form_fill_notification_record` | 保留现有数据；自动填表通知状态展示可优先读通用表，兼容旧表 |
| `ra_exported_summary_file` | 通知摘要中的导出文件数量来自该表 |
| `ra_workflow_event` | 可记录通知节点事件，但不替代通知记录表 |
| `auth_user` | 飞书映射通过外键关联系统用户 |
---
## 六、数据脱敏与安全
| 数据 | 入库策略 |
| --- | --- |
| App ID | 不入库，只在环境变量中维护 |
| App Secret | 不入库，只在环境变量中维护 |
| tenant_access_token | 不持久化入库，仅允许进程内短期缓存 |
| 富文本完整 payload | 不入库 |
| 手机号 | 映射表保存原值；通知记录只保存脱敏值 |
| open_id/user_id | 映射表保存原值；通知记录保存脱敏值 |
| 用户问题 | 问答日志保存原始问题，用于审计；不保存完整回答正文 |
---
## 七、迁移计划
| 步骤 | 说明 |
| --- | --- |
| 1 | 新增 `FeishuUserMapping` 模型和迁移 |
| 2 | 新增 `WorkflowNotificationRecord` 模型和迁移 |
| 3 | 新增 `FeishuQuestionLog` 预留模型和迁移 |
| 4 | 注册 Django Admin 管理入口 |
| 5 | 批次详情页查询通用通知记录展示 |
| 6 | 保留现有专项通知表，不做破坏性迁移 |
---
## 八、验收 SQL 示例
查询某个批次通知状态：
```sql
SELECT workflow_type, workflow_batch_no, workflow_status, channel, send_status, sent_at, error_message
FROM ra_workflow_notification_record
WHERE workflow_type = 'application_form_fill'
AND workflow_batch_no = 'AFF-20260607-001'
ORDER BY created_at DESC;
```
查询未配置飞书映射的失败或降级通知：
```sql
SELECT workflow_type, workflow_batch_no, trigger_user_id, send_status, message_summary
FROM ra_workflow_notification_record
WHERE at_identifier_type = 'missing'
ORDER BY created_at DESC;
```
查询飞书用户映射：
```sql
SELECT u.username, m.feishu_display_name, m.feishu_open_id, m.feishu_user_id, m.feishu_mobile, m.is_active
FROM ra_feishu_user_mapping m
JOIN auth_user u ON u.id = m.system_user_id
ORDER BY u.username;
```

583
docs/5.开发计划/4.飞书通知与问答接入.md Normal file
View File

@@ -0,0 +1,583 @@
# 飞书通知与问答接入开发计划
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 需求分析文档 | docs/1.需求分析/4.飞书通知与问答接入.md |
| 功能设计文档 | docs/2.功能设计/4.飞书通知与问答接入.md |
| 详细设计文档 | docs/3.详细设计/4.飞书通知与问答接入.md |
| 数据库设计文档 | docs/4.数据库设计/4.飞书通知与问答接入.md |
| 功能名称 | 飞书通知与问答接入 |
| 所属模块 | 审核智能体 review_agent |
| 执行方式 | 单人开发 + Codex 自动化执行 |
| 计划日期 | 2026-06-07 |
| 计划版本 | V1.0 |
---
## Codex 自动执行说明
本文件用于 Codex 自动执行开发任务。执行时必须按阶段顺序推进，不得跳过测试、不得直接请求真实飞书接口作为自动化测试、不得把真实 App Secret 或 token 写入代码库。
执行规则：
| 规则 | 要求 |
| --- | --- |
| 执行顺序 | 必须从 FS-0 到 FS-8 顺序执行，前一阶段验证未通过不得进入下一阶段 |
| TDD | 每个服务、模型、命令和页面展示任务必须先写失败测试，再实现代码，再运行测试确认通过 |
| 外部 API | 自动化测试必须 mock 飞书 token API 和消息 API；真实飞书只通过 `send_test_feishu_notification` 手动命令验证 |
| 凭证安全 | 不得提交真实 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`tenant_access_token`、用户 open_id/user_id |
| 失败处理 | 如测试失败，先定位是否由本阶段改动引起；不得修改无关功能绕过测试 |
| 工作区安全 | 不得回滚用户已有变更；如遇到同文件用户改动，先阅读并兼容 |
| 提交节奏 | 每个阶段完成并通过阶段验证后再提交，提交信息参考“建议提交切分” |
| 实现边界 | 首期只做指定个人账号私聊通知和问答预留；不得扩展外部群聊、事件订阅、LLM 问答解析 |
自动执行入口建议：
```text
请按 docs/5.开发计划/4.飞书通知与问答接入.md 从 FS-0 开始逐阶段执行。
每个阶段必须先写测试、运行失败、实现、运行通过，再进入下一阶段。
真实飞书 API 只能通过手动 management command 验证，pytest 中必须 mock。
```
---
## 一、开发计划目标
本开发计划用于指导“飞书通知与问答接入”首期开发。首期目标是通过飞书官方智能体/应用机器人接口，把系统中三个工作流的结束结果发送到指定个人飞书账号，并为后续飞书内问答建立可测试的最小服务边界。
本期必须完成：
| 类别 | 内容 |
| --- | --- |
| 真实飞书通知 | 使用 App ID/App Secret 获取 `tenant_access_token`，调用飞书消息 API 发送私聊通知 |
| 指定个人账号 | 通过 `.env` 配置 `FEISHU_DEFAULT_USER_OPEN_ID` 或 `FEISHU_DEFAULT_USER_ID`，首期优先发给该账号 |
| 三流程接入 | 自动汇总、法规核查、自动填表三个流程完成后均触发通知 |
| 数据库记录 | 新增统一通知记录表、飞书用户映射表、token 缓存表、问答日志表 |
| 页面展示 | 三个流程结果页或详情区域展示飞书通知状态 |
| 问答预留 | 建表、实现批次摘要查询、简单规则意图解析、本地模拟问答命令 |
| 测试策略 | 关键服务严格 TDD；自动化测试 mock 飞书 API；真实飞书发送通过 management command 手动验证 |
本期明确不做：
| 类别 | 内容 |
| --- | --- |
| 外部群聊接入 | 暂不向群聊发送通知，不做群内 @ |
| 飞书事件订阅 | 暂不接收飞书回调，不实现真实私聊问答事件入口 |
| 手动重发 | 页面和 Admin 暂不提供重发按钮 |
| 自动后台重试 | 通知失败只记录；成功才判重，失败允许后续再次发送 |
| LLM 问答解析 | 问答预留只做简单规则解析，不接 LLM |
---
## 二、已确认开发规则
| 规则项 | 内容 |
| --- | --- |
| 主接入方式 | 飞书官方智能体/应用机器人消息 API |
| 凭证配置 | `.env` 提供 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` |
| 接收人配置 | `.env` + Django Admin 都做；首期发送优先使用 `.env` 指定个人账号 |
| 接收人优先级 | `FEISHU_DEFAULT_USER_OPEN_ID` > `FEISHU_DEFAULT_USER_ID` |
| token 缓存 | 数据库缓存 `tenant_access_token` 和过期时间 |
| 通知记录 | 新增统一 `WorkflowNotificationRecord`，三个流程都写入 |
| 判重策略 | 同一批次、同一流程、同一状态，只有成功记录才判重；失败后允许再次发送 |
| 系统链接 | 新增 `PUBLIC_BASE_URL`，默认 `http://127.0.0.1:8000` |
| 页面展示 | 三个流程结果页或详情区域展示通知状态 |
| 真实 API 测试 | 自动化测试全部 mock；新增 management command 手动发送真实测试消息 |
| TDD | 每个核心模块先写测试再实现 |
| 环境变量说明 | 写变量名和用途，不写真实值 |
| 阶段提交 | 模型、服务、工作流、页面、命令、测试分阶段提交 |
| 问答预留 | 建 `FeishuQuestionLog`，实现摘要查询、规则解析和本地模拟命令 |
---
## 三、总体验收标准
| 类别 | 完成标准 |
| --- | --- |
| 配置 | `.env` 支持 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_DEFAULT_USER_OPEN_ID` / `FEISHU_DEFAULT_USER_ID`、`PUBLIC_BASE_URL` |
| token | 系统可获取、缓存、过期刷新 `tenant_access_token`；token API 失败会记录失败通知 |
| 发送 | 手动命令可向指定个人账号发送真实测试消息 |
| 通知 | 三个流程完成后均创建通知记录，并在启用配置时调用飞书消息 API |
| 判重 | 成功记录存在时，同一批次/流程/状态不重复发送；失败记录不阻止再次发送 |
| 失败隔离 | 飞书发送失败不影响业务工作流完成 |
| 页面 | 三个流程结果页或详情区域能看到通知通道、接收人、状态、时间、失败原因 |
| 问答预留 | 本地模拟命令可解析“最新/最近/批次号/工作流关键词”，返回批次摘要并记录日志 |
| 权限 | 普通用户只能查询自己的批次摘要；管理员可查全部 |
| 回归 | 文件汇总、法规核查、自动填表既有测试不回归 |
---
## 四、阶段总览
| 阶段 | 名称 | 目标 | 阶段验收 |
| --- | --- | --- | --- |
| FS-0 | 准备与基线 | 确认文档和测试基线 | `python manage.py check` 与关键现有测试通过 |
| FS-1 | 数据模型与配置 | 新增通知、映射、token、问答日志模型和环境配置 | migration、模型测试通过 |
| FS-2 | 飞书 API 基础服务 | token 获取缓存、接收人解析、消息构造、消息 API client | 服务单测通过，全部 mock 外部 HTTP |
| FS-3 | 通知调度与记录 | 统一通知上下文、判重、成功/失败/disabled 落库 | 通知服务测试通过 |
| FS-4 | 三流程接入 | 自动汇总、法规核查、自动填表完成后触发通知 | 三流程通知集成测试通过 |
| FS-5 | 页面展示 | 批次详情或结果区域展示通知状态 | 页面/视图测试通过 |
| FS-6 | 手动真实测试命令 | management command 发送真实飞书测试消息 | 本地配置后可向个人账号发消息 |
| FS-7 | 问答预留能力 | 批次摘要查询、规则意图解析、模拟问答命令、问答日志 | 问答预留测试通过 |
| FS-8 | 文档与全量回归 | 更新环境变量说明，运行全量相关测试 | 回归通过，计划完成 |
---
## 五、FS-0 准备与基线
### FS-0-001 确认开发文档和当前工作区
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 准备 / Git |
| 前置任务 | 无 |
| 涉及文件 | 文档文件，不改代码 |
| 目标 | 确认需求、功能、数据库、详细设计和开发计划均存在，并记录当前工作区状态 |
| 开发步骤 | 1. 检查 `git status --short`；2. 确认四份设计文档与本开发计划存在；3. 确认当前未提交变更均为文档或用户已有变更；4. 不回滚任何用户变更 |
| 验收标准 | 工作区状态清楚，可进入开发 |
| 验证命令 | `git status --short` |
| Codex 执行提示 | 请先确认飞书接入四份设计文档和开发计划存在，检查工作区状态，不要回滚用户已有变更。 |
### FS-0-002 运行基线测试
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 回归 |
| 前置任务 | FS-0-001 |
| 涉及文件 | 无固定文件 |
| 目标 | 确认开发前现有主流程可运行 |
| 开发步骤 | 1. 运行 Django check；2. 运行通知相关旧测试；3. 运行三个工作流关键测试；4. 若失败，判断是否既有问题并记录 |
| 验收标准 | 基线通过，或既有失败已记录且不与本功能冲突 |
| 验证命令 | `python manage.py check`; `pytest tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py` |
| Codex 执行提示 | 请运行 Django check 和现有通知/工作流关键测试，确认开发前基线。 |
---
## 六、FS-1 数据模型与配置
### FS-1-001 新增飞书接入 ORM 模型测试
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 数据库 |
| 前置任务 | FS-0 |
| 涉及文件 | `tests/test_feishu_models.py` |
| 目标 | 先写失败测试，覆盖飞书用户映射、token 缓存、统一通知记录、问答日志 |
| 开发步骤 | 1. 新增 `test_feishu_user_mapping_preferred_identifier`；2. 新增 `test_feishu_access_token_cache_expiry`；3. 新增 `test_workflow_notification_success_dedupe_only_success`；4. 新增 `test_feishu_question_log_records_summary_without_full_answer` |
| 验收标准 | 新测试因模型不存在而失败 |
| 验证命令 | `pytest tests/test_feishu_models.py -q` |
| Codex 执行提示 | 请先为飞书相关模型写失败测试，覆盖接收人标识优先级、数据库 token 缓存、成功判重和问答日志摘要。 |
### FS-1-002 新增模型
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 数据库 / 后端 |
| 前置任务 | FS-1-001 |
| 涉及文件 | `review_agent/models.py` |
| 目标 | 新增 `FeishuUserMapping`、`FeishuAccessTokenCache`、`WorkflowNotificationRecord`、`FeishuQuestionLog` |
| 开发步骤 | 1. `FeishuUserMapping` 关联系统用户，支持 open_id、user_id、mobile、is_active；2. `FeishuAccessTokenCache` 保存 token、expires_at、app_id_hash、error_message；3. `WorkflowNotificationRecord` 保存 workflow_type、batch_id、batch_no、status、channel、target、send_status、summary、error、sent_at；4. `FeishuQuestionLog` 保存问题、意图、查询对象、回答摘要、权限结果和状态；5. 添加索引和模型方法 |
| 验收标准 | `python manage.py check` 通过 |
| 验证命令 | `python manage.py check` |
| Codex 执行提示 | 请按数据库设计新增四个模型。注意 token 需要数据库缓存，通知判重只对 success 生效。 |
### FS-1-003 生成迁移并通过模型测试
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 数据库 / 测试 |
| 前置任务 | FS-1-002 |
| 涉及文件 | `review_agent/migrations/`、`tests/test_feishu_models.py` |
| 目标 | 生成 migration，模型测试全部通过 |
| 开发步骤 | 1. 运行 makemigrations；2. 检查 migration 只包含飞书相关表；3. 运行 migrate；4. 运行模型测试 |
| 验收标准 | migration 可执行，模型测试通过 |
| 验证命令 | `python manage.py makemigrations review_agent`; `python manage.py migrate`; `pytest tests/test_feishu_models.py -q` |
| Codex 执行提示 | 请生成飞书相关模型迁移并运行模型测试。 |
### FS-1-004 注册 Admin 和配置项
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后台 / 配置 |
| 前置任务 | FS-1-003 |
| 涉及文件 | `review_agent/admin.py`、`config/settings.py`、`.env.example` 或 README |
| 目标 | Admin 可维护用户映射；settings 暴露飞书配置；文档只写变量名不写真实值 |
| 开发步骤 | 1. 注册 `FeishuUserMapping`、`WorkflowNotificationRecord`、`FeishuAccessTokenCache`、`FeishuQuestionLog`；2. settings 读取 `FEISHU_NOTIFY_ENABLED`、`FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_DEFAULT_USER_OPEN_ID`、`FEISHU_DEFAULT_USER_ID`、`FEISHU_DEFAULT_TARGET_NAME`、`PUBLIC_BASE_URL`；3. 默认 `PUBLIC_BASE_URL=http://127.0.0.1:8000`；4. 在说明文件中加入变量名和用途 |
| 验收标准 | Django check 通过；Admin 列表可展示字段 |
| 验证命令 | `python manage.py check` |
| Codex 执行提示 | 请注册飞书相关模型到 Admin，并新增环境变量配置说明，不要写入真实凭证。 |
### FS-1 阶段验证
```bash
python manage.py check
pytest tests/test_feishu_models.py -q
```
---
## 七、FS-2 飞书 API 基础服务
### FS-2-001 token 服务 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 服务 |
| 前置任务 | FS-1 |
| 涉及文件 | `tests/test_feishu_api_services.py` |
| 目标 | 先写 token 获取、缓存、过期刷新、失败记录测试 |
| 开发步骤 | 1. mock 飞书 token HTTP 成功；2. 测试首次获取后写数据库缓存；3. 测试未过期时不再请求 HTTP；4. 测试过期后重新请求；5. 测试 token API 失败返回错误对象 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_api_services.py -k token -q` |
| Codex 执行提示 | 请先写飞书 tenant_access_token 服务测试，外部 HTTP 必须 mock。 |
### FS-2-002 实现 token 服务
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 服务 |
| 前置任务 | FS-2-001 |
| 涉及文件 | `review_agent/notifications/feishu_token.py` |
| 目标 | 使用 App ID/App Secret 获取并数据库缓存 `tenant_access_token` |
| 开发步骤 | 1. 定义 `FeishuTokenResult`；2. 检查配置缺失；3. 查询未过期数据库缓存；4. 调用 token API；5. 保存 token 和 expires_at；6. token 失败时返回错误，不抛出到业务流程 |
| 验收标准 | token 服务测试通过 |
| 验证命令 | `pytest tests/test_feishu_api_services.py -k token -q` |
| Codex 执行提示 | 请实现 token 服务，缓存放数据库，不打印 App Secret 和 token。 |
### FS-2-003 接收人解析和消息构造 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 服务 |
| 前置任务 | FS-2-002 |
| 涉及文件 | `tests/test_feishu_api_services.py` |
| 目标 | 测试指定个人接收人优先级、配置缺失、富文本消息摘要 |
| 开发步骤 | 1. 测试 `FEISHU_DEFAULT_USER_OPEN_ID` 优先；2. 测试无 open_id 时使用 `FEISHU_DEFAULT_USER_ID`；3. 测试均缺失返回 `recipient_missing`；4. 测试消息包含流程、批次、状态、摘要、链接和发起人 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_api_services.py -k 'recipient or message' -q` |
| Codex 执行提示 | 请先写接收人解析和富文本消息构造测试。 |
### FS-2-004 实现接收人解析和消息构造
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 服务 |
| 前置任务 | FS-2-003 |
| 涉及文件 | `review_agent/notifications/recipient.py`、`review_agent/notifications/message_builder.py`、`review_agent/notifications/context.py` |
| 目标 | 生成统一通知上下文、指定个人接收人和飞书富文本 payload |
| 开发步骤 | 1. 定义 `NotificationContext`；2. 定义 `ResolvedFeishuTarget`；3. 实现 `resolve_configured_personal_recipient()`；4. 实现 `build_feishu_post_message()`；5. 实现 `build_message_summary()`；6. 链接使用 `PUBLIC_BASE_URL` |
| 验收标准 | 接收人和消息构造测试通过 |
| 验证命令 | `pytest tests/test_feishu_api_services.py -k 'recipient or message' -q` |
| Codex 执行提示 | 请实现通知上下文、接收人解析和飞书富文本消息构造。首期不需要群 @。 |
### FS-2-005 消息 API client TDD 与实现
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 测试 |
| 前置任务 | FS-2-004 |
| 涉及文件 | `tests/test_feishu_api_services.py`、`review_agent/notifications/feishu_message_api.py` |
| 目标 | mock 飞书消息 API，完成成功、超时、错误码、token 失效重试一次 |
| 开发步骤 | 1. 写成功测试，断言请求携带 Authorization；2. 写非 0 code 测试；3. 写超时测试；4. 写 token 失效后刷新 token 并同步重试一次测试；5. 实现 `send_personal_message()` |
| 验收标准 | 消息 API client 测试通过 |
| 验证命令 | `pytest tests/test_feishu_api_services.py -q` |
| Codex 执行提示 | 请用 mock HTTP 实现飞书消息 API client。自动化测试不得请求真实飞书。 |
### FS-2 阶段验证
```bash
pytest tests/test_feishu_api_services.py -q
```
---
## 八、FS-3 通知调度与记录
### FS-3-001 通知记录服务 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 服务 |
| 前置任务 | FS-2 |
| 涉及文件 | `tests/test_feishu_notification_dispatcher.py` |
| 目标 | 先写通知调度、成功判重、失败允许再次发送、disabled 记录测试 |
| 开发步骤 | 1. 测试通知关闭写 disabled；2. 测试发送成功写 success；3. 测试已有 success 时不再调用 API；4. 测试已有 failed 时允许再次调用 API；5. 测试 token 失败写 failed |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_notification_dispatcher.py -q` |
| Codex 执行提示 | 请先写统一通知调度测试，重点覆盖成功判重和失败可重试。 |
### FS-3-002 实现通知记录和 dispatcher
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 服务 |
| 前置任务 | FS-3-001 |
| 涉及文件 | `review_agent/notifications/records.py`、`review_agent/notifications/dispatcher.py` |
| 目标 | 实现统一通知调度入口 |
| 开发步骤 | 1. 实现 `already_successfully_sent(dedupe_key)`；2. 实现 disabled、success、failed 记录创建；3. 实现 `dispatch_workflow_notification(context)`；4. 捕获服务异常并写 failed；5. 不让异常冒泡阻断工作流 |
| 验收标准 | dispatcher 测试通过 |
| 验证命令 | `pytest tests/test_feishu_notification_dispatcher.py -q` |
| Codex 执行提示 | 请实现统一通知调度和记录落库。注意 success 才判重，failed 不判重。 |
### FS-3 阶段验证
```bash
pytest tests/test_feishu_notification_dispatcher.py -q
```
---
## 九、FS-4 三流程接入
### FS-4-001 工作流 adapter TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 集成 |
| 前置任务 | FS-3 |
| 涉及文件 | `tests/test_feishu_workflow_adapters.py` |
| 目标 | 测试自动汇总、法规核查、自动填表三类批次能生成正确通知上下文 |
| 开发步骤 | 1. 构造 `FileSummaryBatch` 和 items，断言文件摘要；2. 构造 `RegulatoryReviewBatch` 和 issues，断言风险摘要；3. 构造 `ApplicationFormFillBatch` 和 exports，断言导出/冲突摘要；4. 断言 result_url 使用 `PUBLIC_BASE_URL` |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_workflow_adapters.py -q` |
| Codex 执行提示 | 请先写三个工作流 adapter 的测试。 |
### FS-4-002 实现工作流 adapters
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 服务 |
| 前置任务 | FS-4-001 |
| 涉及文件 | `review_agent/notifications/workflow_adapters.py` |
| 目标 | 三个工作流批次转换为 `NotificationContext` |
| 开发步骤 | 1. 实现 `build_file_summary_context()`；2. 实现 `build_regulatory_review_context()`；3. 实现 `build_application_form_fill_context()`；4. 控制摘要长度；5. 处理 partial_success 和 failed |
| 验收标准 | adapter 测试通过 |
| 验证命令 | `pytest tests/test_feishu_workflow_adapters.py -q` |
| Codex 执行提示 | 请实现三个工作流通知上下文 adapter。 |
### FS-4-003 接入三个工作流完成节点
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 工作流 |
| 前置任务 | FS-4-002 |
| 涉及文件 | `review_agent/file_summary/workflow.py`、`review_agent/regulatory_review/workflow.py`、`review_agent/application_form_fill/workflow.py` |
| 目标 | 三个工作流完成后调用通知 dispatcher |
| 开发步骤 | 1. 自动汇总成功/失败状态落定后触发通知；2. 法规核查报告和风险落库后触发通知；3. 自动填表 notify 节点改为统一通知服务；4. 捕获通知异常并记录非阻断错误；5. 保留现有 mock 测试兼容 |
| 验收标准 | 三流程通知集成测试通过 |
| 验证命令 | `pytest tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py` |
| Codex 执行提示 | 请把统一通知服务接入三个工作流完成节点，通知失败不得影响业务状态。 |
### FS-4 阶段验证
```bash
pytest tests/test_feishu_workflow_adapters.py tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py
```
---
## 十、FS-5 页面展示
### FS-5-001 通知状态展示测试
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 前端 |
| 前置任务 | FS-4 |
| 涉及文件 | `tests/test_file_summary_frontend.py`、`tests/test_regulatory_frontend.py`、`tests/test_application_form_fill_frontend.py` |
| 目标 | 测试三个流程页面或结果区域展示飞书通知状态 |
| 开发步骤 | 1. 准备 success 通知记录，断言页面出现“飞书通知已发送”；2. 准备 failed 记录，断言出现失败原因；3. 无记录时展示“暂无飞书通知记录”或不破坏页面 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_file_summary_frontend.py tests/test_regulatory_frontend.py tests/test_application_form_fill_frontend.py -k feishu` |
| Codex 执行提示 | 请先写三个流程通知状态展示测试。 |
### FS-5-002 实现通知状态 presenter 和页面展示
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 前端 |
| 前置任务 | FS-5-001 |
| 涉及文件 | `review_agent/notifications/presenter.py`、`review_agent/*/views.py`、`templates/home.html` 或相关模板 |
| 目标 | 页面展示通知状态、接收人、发送时间、失败原因 |
| 开发步骤 | 1. 实现 `get_notification_records(workflow_type, batch_id)`；2. 在三个流程视图上下文中加入通知记录；3. 模板展示最近一条通知状态；4. 保持页面无记录时兼容 |
| 验收标准 | 页面展示测试通过 |
| 验证命令 | `pytest tests/test_file_summary_frontend.py tests/test_regulatory_frontend.py tests/test_application_form_fill_frontend.py -k feishu` |
| Codex 执行提示 | 请实现通知状态 presenter，并在三个流程结果页展示最近飞书通知状态。 |
### FS-5 阶段验证
```bash
pytest tests/test_file_summary_frontend.py tests/test_regulatory_frontend.py tests/test_application_form_fill_frontend.py -k feishu
```
---
## 十一、FS-6 手动真实测试命令
### FS-6-001 测试命令 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 命令 |
| 前置任务 | FS-5 |
| 涉及文件 | `tests/test_feishu_management_commands.py` |
| 目标 | 测试 management command 构造测试通知并调用 dispatcher |
| 开发步骤 | 1. mock dispatcher；2. 执行 `send_test_feishu_notification --username owner`；3. 断言构造测试上下文；4. 测试缺少用户时报错 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_management_commands.py -q` |
| Codex 执行提示 | 请先写真实飞书测试命令的自动化测试，dispatcher 要 mock。 |
### FS-6-002 实现发送测试消息命令
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 运维 / 命令 |
| 前置任务 | FS-6-001 |
| 涉及文件 | `review_agent/management/commands/send_test_feishu_notification.py` |
| 目标 | 本地可手动向指定个人飞书账号发送真实测试消息 |
| 开发步骤 | 1. 支持 `--username`；2. 构造 workflow_type=`manual_test` 的 `NotificationContext`；3. 调用 dispatcher；4. 输出 send_status、target、error_message；5. 不打印 token 和 App Secret |
| 验收标准 | 命令测试通过；本地配置真实凭证后可手动验证 |
| 验证命令 | `pytest tests/test_feishu_management_commands.py -q`; `python manage.py send_test_feishu_notification --username owner` |
| Codex 执行提示 | 请实现发送测试飞书通知的 management command。自动测试 mock dispatcher，真实发送只手动运行。 |
### FS-6 阶段验证
```bash
pytest tests/test_feishu_management_commands.py -q
```
手动验证命令：
```bash
python manage.py send_test_feishu_notification --username owner
```
---
## 十二、FS-7 问答预留能力
### FS-7-001 批次摘要查询服务 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 服务 |
| 前置任务 | FS-6 |
| 涉及文件 | `tests/test_feishu_question_reserved.py` |
| 目标 | 测试按批次号、latest、工作流类型查询三个流程摘要 |
| 开发步骤 | 1. 普通用户查询自己的最新法规核查批次；2. 普通用户不能查询他人批次；3. 管理员可查全部；4. 按批次号精确查询；5. 返回状态、摘要、链接 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_question_reserved.py -k query -q` |
| Codex 执行提示 | 请先写飞书问答预留的批次摘要查询测试。 |
### FS-7-002 实现批次摘要查询服务
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 服务 |
| 前置任务 | FS-7-001 |
| 涉及文件 | `review_agent/feishu_questions/query.py`、`review_agent/feishu_questions/permissions.py` |
| 目标 | 支持三个工作流的摘要查询和权限过滤 |
| 开发步骤 | 1. 实现管理员/普通用户权限过滤；2. 实现 batch_no 查询；3. 实现 latest 查询；4. 实现 workflow_type 关键词映射；5. 返回统一摘要 dict |
| 验收标准 | 查询服务测试通过 |
| 验证命令 | `pytest tests/test_feishu_question_reserved.py -k query -q` |
| Codex 执行提示 | 请实现问答预留查询服务，普通用户只能查自己的批次，管理员可查全部。 |
### FS-7-003 简单意图解析和日志 TDD
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 服务 |
| 前置任务 | FS-7-002 |
| 涉及文件 | `tests/test_feishu_question_reserved.py` |
| 目标 | 测试规则解析“最新/最近/批次号/工作流关键词”，并记录问答日志 |
| 开发步骤 | 1. 识别 `RR-`、`AFF-`、`FS-` 批次号；2. 识别“最新/最近”；3. 识别“法规核查/自动填表/自动汇总”；4. 记录 `FeishuQuestionLog`，不保存完整回答正文 |
| 验收标准 | 测试先失败 |
| 验证命令 | `pytest tests/test_feishu_question_reserved.py -k 'intent or log' -q` |
| Codex 执行提示 | 请先写简单规则意图解析和问答日志测试，不接 LLM。 |
### FS-7-004 实现意图解析、问答服务和模拟命令
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 后端 / 命令 |
| 前置任务 | FS-7-003 |
| 涉及文件 | `review_agent/feishu_questions/intent.py`、`review_agent/feishu_questions/service.py`、`review_agent/management/commands/feishu_question_simulate.py` |
| 目标 | 本地模拟飞书问答输入，返回批次摘要并记录日志 |
| 开发步骤 | 1. 实现 `parse_question_intent(text)`；2. 实现 `answer_question(user, text)`；3. 写入 `FeishuQuestionLog`；4. 实现命令 `python manage.py feishu_question_simulate --username owner "查最新法规核查"`；5. 输出回答摘要 |
| 验收标准 | 问答预留测试和命令测试通过 |
| 验证命令 | `pytest tests/test_feishu_question_reserved.py -q`; `python manage.py feishu_question_simulate --username owner "查最新法规核查"` |
| Codex 执行提示 | 请实现飞书问答预留的规则解析、服务和本地模拟命令。 |
### FS-7 阶段验证
```bash
pytest tests/test_feishu_question_reserved.py -q
python manage.py feishu_question_simulate --username owner "查最新法规核查"
```
---
## 十三、FS-8 文档与全量回归
### FS-8-001 更新配置说明
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 文档 / 配置 |
| 前置任务 | FS-7 |
| 涉及文件 | `README.md`、`.env.example` 或项目配置说明文档 |
| 目标 | 说明飞书相关环境变量和手动测试命令 |
| 开发步骤 | 1. 写明变量名和用途；2. 标注不要提交真实 App Secret；3. 写明 `send_test_feishu_notification` 用法；4. 写明自动化测试不请求真实飞书 |
| 验收标准 | 配置说明清楚，无真实密钥 |
| 验证命令 | 手动检查文档 |
| Codex 执行提示 | 请补充飞书配置说明，只写变量名和用途，不写真实值。 |
### FS-8-002 全量相关测试
| 项目 | 内容 |
| --- | --- |
| 任务类型 | 测试 / 回归 |
| 前置任务 | FS-8-001 |
| 涉及文件 | 无固定文件 |
| 目标 | 运行飞书新增测试和三个工作流关键回归 |
| 开发步骤 | 1. 运行 Django check；2. 运行飞书新增测试；3. 运行三个工作流关键测试；4. 修复与本功能相关失败；5. 记录无法处理的既有失败 |
| 验收标准 | 新增测试通过，关键回归通过 |
| 验证命令 | `python manage.py check`; `pytest tests/test_feishu_*.py tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py` |
| Codex 执行提示 | 请运行飞书新增测试和三个工作流关键回归，确保首期飞书接入不破坏既有功能。 |
### FS-8 阶段验证
```bash
python manage.py check
pytest tests/test_feishu_*.py tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py
```
---
## 十四、建议提交切分
| 提交 | 建议提交信息 | 包含内容 |
| --- | --- | --- |
| 1 | `feat: add feishu notification data models` | 模型、迁移、Admin、配置项 |
| 2 | `feat: add feishu api notification services` | token、接收人、消息构造、消息 API client |
| 3 | `feat: add workflow notification dispatcher` | dispatcher、记录判重、三流程 adapter |
| 4 | `feat: wire feishu notifications into workflows` | 三个工作流接入 |
| 5 | `feat: show feishu notification status` | 页面展示 |
| 6 | `feat: add feishu notification test command` | 真实发送测试命令 |
| 7 | `feat: add feishu question preview services` | 问答预留查询、解析、日志、模拟命令 |
| 8 | `docs: document feishu configuration` | 配置说明和回归修正 |
---
## 十五、风险与处理策略
| 风险 | 影响 | 策略 |
| --- | --- | --- |
| 飞书应用权限不足 | 消息 API 返回无权限 | 手动测试命令先验证；错误码入库展示 |
| open_id/user_id 不正确 | 个人账号收不到消息 | 接收人配置缺失或错误时记录 failed，命令输出错误 |
| token 缓存过期处理不当 | 偶发发送失败 | token 失效时刷新并允许消息 API 同步重试一次 |
| 三流程状态差异 | 通知触发点不一致 | 用 adapter 隔离各流程摘要生成 |
| 页面展示影响既有模板 | 前端回归失败 | 使用小型通知状态区块，无记录时不改变主流程展示 |
| 问答预留过度设计 | 影响首期交付 | 只做规则解析和摘要查询，不接事件订阅、不接 LLM |