飞书通知与问答接入开发计划
文档信息
| 项目 |
内容 |
| 需求分析文档 |
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 问答解析 |
自动执行入口建议：
一、开发计划目标
本开发计划用于指导“飞书通知与问答接入”首期开发。首期目标是通过飞书官方智能体/应用机器人接口，把系统中三个工作流的结束结果发送到指定个人飞书账号，并为后续飞书内问答建立可测试的最小服务边界。
本期必须完成：
| 类别 |
内容 |
| 真实飞书通知 |
使用 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 阶段验证
七、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 阶段验证
八、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 阶段验证
九、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 阶段验证
十、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 阶段验证
十一、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 阶段验证
手动验证命令：
十二、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 阶段验证
十三、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 阶段验证
十四、建议提交切分
| 提交 |
建议提交信息 |
包含内容 |
| 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 |
