# 飞书通知与问答接入开发计划

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 需求分析文档 | 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 |