635 lines
38 KiB
Markdown
635 lines
38 KiB
Markdown
# 自动汇总文件夹文件目录与页数流程开发计划
|
||
|
||
## 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 需求分析文档 | docs/1.需求分析/1.自动汇总.md |
|
||
| 功能设计文档 | docs/2.功能设计/1.自动汇总.md |
|
||
| 详细设计文档 | docs/3.详细设计/1.自动汇总.md |
|
||
| 数据库设计文档 | docs/4.数据库设计/1.自动汇总.md |
|
||
| 功能名称 | 自动汇总文件夹文件目录与页数 |
|
||
| 所属模块 | 审核智能体 review_agent |
|
||
| 执行方式 | 单人开发 + Codex 流水线自动化执行 |
|
||
| 计划日期 | 2026-06-05 |
|
||
| 计划版本 | V1.0 |
|
||
|
||
---
|
||
|
||
## 一、开发计划目标
|
||
|
||
本开发计划用于指导 Codex 按阶段自动完成“自动汇总文件夹文件目录与页数”功能开发。任务拆分按可交付阶段组织，每个任务都需要具备明确目标、涉及文件、前置依赖、开发步骤、验收标准、验证命令和 Codex 执行提示。
|
||
|
||
本功能不按 MVP 缩减范围，必须按需求分析、功能设计、详细设计、数据库设计中的全部范围完成。
|
||
|
||
---
|
||
|
||
## 二、已确认开发规则
|
||
|
||
| 规则项 | 内容 |
|
||
| --- | --- |
|
||
| 拆分方式 | 按可交付阶段拆分 |
|
||
| 任务粒度 | 每个任务写到可直接交给 Codex 执行 |
|
||
| 执行对象 | 一个开发者使用 Codex 流水线自动化执行 |
|
||
| 单任务范围 | 尽量控制在 1 到 3 类文件 |
|
||
| Codex 提示 | 每个任务都提供“Codex 执行提示” |
|
||
| 功能范围 | 必须完成全部需求，不允许降级为最小闭环 |
|
||
| 前端验证 | 使用 Playwright 做真实浏览器端到端测试 |
|
||
| 测试数据 | 测试代码中可动态创建登录用户和临时文件 |
|
||
| Git 提交 | 每个阶段完成并验证通过后提交一次 |
|
||
| 提交摘要 | 使用执行机器上的 `git-commit-summary` skill |
|
||
| 分支规则 | 从 `V2` 创建日期 + 中文功能名分支，完成后合并回 `V2` |
|
||
|
||
---
|
||
|
||
## 三、总体验收标准
|
||
|
||
| 类别 | 完成标准 |
|
||
| --- | --- |
|
||
| 数据库 | 7 张 `ra_` 表全部通过 Django migration 落库，约束、索引、枚举齐全 |
|
||
| 上传 | 当前对话右侧上传区支持多文件和压缩包上传，上传即存储，附件不跨对话 |
|
||
| 触发 | 用户发送命中提示词后才启动自动汇总工作流，普通对话不误触发 |
|
||
| 工作流 | 后台异步执行，节点状态可实时更新，事件可持久化和恢复 |
|
||
| 解压 | 支持 zip、7z、rar，解压安全检查必须完成 |
|
||
| 统计 | 支持 pdf、doc、docx、xls、xlsx、ppt、pptx，失败重试 3 次，失败不阻断批次 |
|
||
| 输出 | 生成 Markdown 报告、Excel 明细，对话框展示 Markdown 简表和下载链接 |
|
||
| 前端 | 三栏布局、上方拖拽上传、下方工作流卡片、Markdown 表格渲染正常 |
|
||
| 存档 | 批次、附件、文件明细、节点、事件、导出文件全部入库 |
|
||
| 标题 | 识别到产品名后按规则更新对话标题 |
|
||
| 权限 | 上传、查询、下载都校验当前用户和当前对话 |
|
||
| 测试 | 单元、接口、集成、Playwright 端到端测试全部覆盖 |
|
||
| 部署 | requirements 可安装，Docker 部署说明包含 7z/p7zip，rar/7z 解压验证通过 |
|
||
|
||
---
|
||
|
||
## 四、阶段总览
|
||
|
||
| 阶段 | 名称 | 目标 | 阶段验收 |
|
||
| --- | --- | --- | --- |
|
||
| P0 | 流水线准备 | 建立开发分支，确认依赖、规范和现状 | 分支创建完成，开发前检查通过 |
|
||
| P1 | 数据模型与迁移 | 完成 7 张 ra_ 表 ORM 与 migration | SQLite 可建表，模型约束正确 |
|
||
| P2 | 上传与对话绑定 | 实现上传即存储、同名版本和附件权限 | 上传接口可用，附件不跨对话 |
|
||
| P3 | 工作流触发与后台执行 | 实现提示词触发、批次创建、后台节点执行和事件持久化 | 命中提示词可启动工作流，状态可查询 |
|
||
| P4 | Skill 与文件处理能力 | 实现解压、扫描、页数统计、重试和产品名识别 | 支持格式全部进入处理流程 |
|
||
| P5 | 报告生成与下载 | 实现 Markdown 报告、Excel 导出、下载权限和助手消息 | 可下载报告，数据库留痕完整 |
|
||
| P6 | 前端三栏与工作流卡片 | 实现右侧上传区、工作流卡片、SSE 更新和 Markdown 渲染 | Playwright 验证前端主流程 |
|
||
| P7 | 测试、部署与总体验收 | 补齐自动化测试、端到端测试、Docker 说明和最终合并 | 全部测试通过，合并回 V2 |
|
||
|
||
---
|
||
|
||
## 五、P0 流水线准备
|
||
|
||
### FS-P0-001 创建开发分支并检查现状
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | Git / 准备 |
|
||
| 前置任务 | 无 |
|
||
| 涉及文件 | 无固定文件 |
|
||
| 目标 | 从 `V2` 分支创建日期 + 中文功能名开发分支，并确认工作区状态 |
|
||
| 开发步骤 | 1. 切换到 `V2`；2. 拉取或确认本地最新状态；3. 创建 `codex/YYYYMMDD-自动汇总文件目录页数` 分支；4. 检查 `git status`；5. 确认已有设计文档存在 |
|
||
| 验收标准 | 开发分支创建成功；工作区变更来源清楚；不会覆盖用户已有未提交改动 |
|
||
| 验证命令 | `git branch --show-current`; `git status --short` |
|
||
| Codex 执行提示 | 请从 `V2` 创建 `codex/YYYYMMDD-自动汇总文件目录页数` 开发分支，检查当前工作区状态，不要回滚用户已有变更。 |
|
||
|
||
### FS-P0-002 补充依赖清单与部署前置说明
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 依赖 / 部署准备 |
|
||
| 前置任务 | FS-P0-001 |
|
||
| 涉及文件 | `requirements.txt`、部署说明文档、前端静态资源引入位置 |
|
||
| 目标 | 增加文件解析与导出所需 Python 依赖，并说明 rar/7z 的系统依赖 |
|
||
| 开发步骤 | 1. 在 `requirements.txt` 增加 `pypdf`、`python-docx`、`python-pptx`、`openpyxl`、`xlrd`、`olefile`、`py7zr`；2. 在前端任务中明确 `marked + DOMPurify` 通过模板或静态资源引入；3. 在部署说明中写明 Docker 需要安装 7z/p7zip；4. 明确不强制依赖 LibreOffice |
|
||
| 验收标准 | Python 依赖可安装；部署说明明确 rar 依赖系统 7z/p7zip；未引入 LibreOffice 强依赖 |
|
||
| 验证命令 | `pip install -r requirements.txt` |
|
||
| Codex 执行提示 | 请按详细设计补充轻量依赖，并在部署说明中写清 Docker 需安装 7z/p7zip 支持 rar/7z，禁止把 LibreOffice 作为必需依赖。 |
|
||
|
||
---
|
||
|
||
## 六、P1 数据模型与迁移
|
||
|
||
### FS-P1-001 新增文件汇总 ORM 模型
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 数据库 / 后端 |
|
||
| 前置任务 | P0 |
|
||
| 涉及文件 | `review_agent/models.py` |
|
||
| 目标 | 新增文件汇总相关 7 个模型和状态枚举 |
|
||
| 开发步骤 | 1. 定义 `FileAttachment`；2. 定义 `FileSummaryBatch`；3. 定义 `FileSummaryBatchAttachment`；4. 定义 `FileSummaryItem`；5. 定义 `WorkflowNodeRun`；6. 定义 `WorkflowEvent`；7. 定义 `ExportedSummaryFile`；8. 使用 Django `TextChoices` 管理枚举 |
|
||
| 验收标准 | 模型字段、关联、默认值、`db_table`、`indexes`、`constraints` 与数据库设计一致 |
|
||
| 验证命令 | `python manage.py check` |
|
||
| Codex 执行提示 | 请按 `docs/4.数据库设计/1.自动汇总.md` 在 `review_agent/models.py` 新增 7 个 `ra_` 表模型，使用 Django ORM、TextChoices、短表名、索引和唯一约束。 |
|
||
|
||
### FS-P1-002 生成并验证数据库迁移
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 数据库 / 迁移 |
|
||
| 前置任务 | FS-P1-001 |
|
||
| 涉及文件 | `review_agent/migrations/` |
|
||
| 目标 | 生成 migration 并验证 SQLite 可落表 |
|
||
| 开发步骤 | 1. 执行 `makemigrations`；2. 检查 migration 是否只包含本功能相关模型；3. 执行 `migrate`；4. 检查表结构和索引 |
|
||
| 验收标准 | migration 可执行；SQLite 中生成 7 张 `ra_` 表；约束和索引生效 |
|
||
| 验证命令 | `python manage.py makemigrations review_agent`; `python manage.py migrate`; `python manage.py check` |
|
||
| Codex 执行提示 | 请为文件汇总模型生成 Django migration 并执行迁移验证，确保 SQLite 下 7 张 `ra_` 表均可创建。 |
|
||
|
||
### FS-P1-003 增加模型级测试
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 测试 / 数据库 |
|
||
| 前置任务 | FS-P1-002 |
|
||
| 涉及文件 | `tests/test_file_summary_models.py` |
|
||
| 目标 | 覆盖附件版本、批次绑定、唯一约束和权限查询基础逻辑 |
|
||
| 开发步骤 | 1. 测试同一对话同名附件版本号递增；2. 测试 active 版本切换；3. 测试批次绑定附件唯一；4. 测试同批次 relative_path 唯一；5. 测试导出文件能追溯到用户和对话 |
|
||
| 验收标准 | 模型测试全部通过，关键约束失败时能暴露错误 |
|
||
| 验证命令 | `pytest tests/test_file_summary_models.py` |
|
||
| Codex 执行提示 | 请新增模型级测试，覆盖文件汇总表的版本、绑定、唯一约束和对话隔离规则。 |
|
||
|
||
### P1 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `python manage.py check`; `pytest tests/test_file_summary_models.py` |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P1 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 七、P2 上传与对话绑定
|
||
|
||
### FS-P2-001 实现附件存储服务
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 存储 |
|
||
| 前置任务 | P1 |
|
||
| 涉及文件 | `review_agent/file_summary/storage.py`、`review_agent/file_summary/constants.py` |
|
||
| 目标 | 实现上传文件保存、版本号生成、存储目录生成和逻辑删除基础能力 |
|
||
| 开发步骤 | 1. 创建 `file_summary` 目录；2. 实现按 `user/conversation/attachments` 保存文件；3. 实现同名附件版本递增；4. 新版本设为 active 并关闭旧 active；5. 实现路径安全处理 |
|
||
| 验收标准 | 上传文件保存到受控目录；附件记录绑定当前用户和对话；同名多版本不覆盖 |
|
||
| 验证命令 | `pytest tests/test_file_summary_storage.py` |
|
||
| Codex 执行提示 | 请实现文件汇总附件存储服务，保证上传即存储、同名多版本、当前对话绑定和路径安全。 |
|
||
|
||
### FS-P2-002 实现附件上传接口
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 接口 |
|
||
| 前置任务 | FS-P2-001 |
|
||
| 涉及文件 | `review_agent/file_summary/views.py`、`review_agent/file_summary/urls.py`、`config/urls.py` |
|
||
| 目标 | 新增对话附件上传接口，支持多文件和压缩包上传 |
|
||
| 开发步骤 | 1. 新增 `POST /api/review-agent/conversations/{conversation_id}/attachments/`；2. 校验 conversation 属于 request.user；3. 保存多个文件；4. 返回 attachment 列表；5. 接入 URL |
|
||
| 验收标准 | 当前用户只能向自己的对话上传；接口返回附件 ID、文件名、大小、版本和状态 |
|
||
| 验证命令 | `pytest tests/test_file_summary_views.py -k upload` |
|
||
| Codex 执行提示 | 请新增对话附件上传 API，支持一次上传多个文件，所有附件必须绑定当前 Conversation，禁止跨用户上传。 |
|
||
|
||
### FS-P2-003 实现附件列表和删除接口
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 接口 |
|
||
| 前置任务 | FS-P2-002 |
|
||
| 涉及文件 | `review_agent/file_summary/views.py`、`review_agent/file_summary/urls.py` |
|
||
| 目标 | 支持前端右侧上传区展示当前对话附件，并允许逻辑删除 |
|
||
| 开发步骤 | 1. 新增当前对话附件列表接口；2. 返回 active 和历史版本信息；3. 新增附件逻辑删除接口；4. 删除时设置 `upload_status=deleted`、`is_active=false` |
|
||
| 验收标准 | 附件列表只返回当前对话文件；逻辑删除不影响历史批次追溯 |
|
||
| 验证命令 | `pytest tests/test_file_summary_views.py -k attachment` |
|
||
| Codex 执行提示 | 请实现当前对话附件列表和逻辑删除接口，支持同名版本展示，删除不得物理移除历史批次需要的文件。 |
|
||
|
||
### P2 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `pytest tests/test_file_summary_storage.py tests/test_file_summary_views.py -k "upload or attachment"` |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P2 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 八、P3 工作流触发与后台执行
|
||
|
||
### FS-P3-001 实现提示词触发判断
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 意图识别 |
|
||
| 前置任务 | P2 |
|
||
| 涉及文件 | `review_agent/file_summary/services/workflow_trigger.py`、`review_agent/services.py` |
|
||
| 目标 | 根据提示词决定是否启动自动汇总工作流 |
|
||
| 开发步骤 | 1. 定义触发关键词；2. 判断当前对话是否存在可用 active 附件；3. 命中时返回 workflow 类型；4. 未命中走普通 LLM；5. 命中但无附件时返回提示 |
|
||
| 验收标准 | “自动汇总”“文件目录”“页数”等关键词可触发；普通对话不误触发 |
|
||
| 验证命令 | `pytest tests/test_file_summary_trigger.py` |
|
||
| Codex 执行提示 | 请实现自动汇总工作流触发判断，只有当前对话存在可用附件且提示词命中关键词时才启动工作流。 |
|
||
|
||
### FS-P3-002 实现批次创建与附件固化
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 工作流 |
|
||
| 前置任务 | FS-P3-001 |
|
||
| 涉及文件 | `review_agent/file_summary/workflow.py`、`review_agent/file_summary/storage.py` |
|
||
| 目标 | 用户消息触发时创建 FileSummaryBatch，并固化本次使用的附件版本 |
|
||
| 开发步骤 | 1. 创建批次编号；2. 创建 `FileSummaryBatch`；3. 绑定 active 附件到中间表；4. 标记附件为 bound；5. 创建初始节点记录 |
|
||
| 验收标准 | 同一对话可多次汇总；历史批次绑定历史附件版本；不会读取其他对话文件 |
|
||
| 验证命令 | `pytest tests/test_file_summary_workflow.py -k batch` |
|
||
| Codex 执行提示 | 请实现批次创建和附件版本固化，确保每次汇总只读取本批次绑定的附件。 |
|
||
|
||
### FS-P3-003 实现 WorkflowEvent 与 SSE 事件查询
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / SSE |
|
||
| 前置任务 | FS-P3-002 |
|
||
| 涉及文件 | `review_agent/file_summary/events.py`、`review_agent/file_summary/views.py` |
|
||
| 目标 | 持久化工作流事件，并支持前端按 batch 监听和断点续传 |
|
||
| 开发步骤 | 1. 实现事件写入；2. 实现 SSE 格式化；3. 新增 `GET /api/review-agent/file-summary/{batch_id}/events/?after=`；4. 新增批次状态查询接口；5. 校验用户权限 |
|
||
| 验收标准 | 节点事件可入库；SSE 可返回事件流；页面刷新可通过状态接口恢复 |
|
||
| 验证命令 | `pytest tests/test_file_summary_views.py -k "event or status"` |
|
||
| Codex 执行提示 | 请实现工作流事件持久化、事件 SSE 接口和批次状态查询接口，所有查询必须校验当前用户权限。 |
|
||
|
||
### FS-P3-004 实现轻量后台工作流执行器
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 工作流 |
|
||
| 前置任务 | FS-P3-003 |
|
||
| 涉及文件 | `review_agent/file_summary/workflow.py`、`review_agent/file_summary/skills/` |
|
||
| 目标 | 实现串行节点图执行器，后台异步执行并更新节点状态 |
|
||
| 开发步骤 | 1. 定义节点顺序；2. 实现后台线程启动；3. 实现节点开始、成功、失败、跳过状态；4. 每个节点写入 WorkflowNodeRun；5. 每个节点发送 WorkflowEvent |
|
||
| 验收标准 | 命中提示词后可后台创建并推进节点；节点状态可查询；异常能标记批次失败 |
|
||
| 验证命令 | `pytest tests/test_file_summary_workflow.py -k executor` |
|
||
| Codex 执行提示 | 请实现轻量 WorkflowExecutor，按节点图异步执行文件汇总流程，实时写入节点状态和事件。 |
|
||
|
||
### FS-P3-005 接入现有流式聊天接口
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 对话 |
|
||
| 前置任务 | FS-P3-004 |
|
||
| 涉及文件 | `review_agent/services.py`、`review_agent/views.py` |
|
||
| 目标 | 在现有 `stream_chat` 流程中按需启动自动汇总工作流 |
|
||
| 开发步骤 | 1. 用户消息入库后判断触发；2. 命中时创建批次并启动后台；3. SSE meta 返回 workflow 信息；4. 对话中返回“已启动工作流”类助手消息或后续由报告生成写入结果；5. 未命中时保持原 LLM 流式逻辑 |
|
||
| 验收标准 | 普通聊天不受影响；自动汇总触发后前端可拿到 batch_id；无附件时提示用户先上传 |
|
||
| 验证命令 | `pytest tests/test_chat.py tests/test_file_summary_workflow.py -k trigger` |
|
||
| Codex 执行提示 | 请把自动汇总触发接入现有流式聊天接口，保证普通 LLM 对话兼容，命中工作流时返回 workflow meta。 |
|
||
|
||
### P3 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `pytest tests/test_file_summary_trigger.py tests/test_file_summary_workflow.py tests/test_file_summary_views.py` |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P3 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 九、P4 Skill 与文件处理能力
|
||
|
||
### FS-P4-001 实现 Skill 基类与注册表
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / Skill |
|
||
| 前置任务 | P3 |
|
||
| 涉及文件 | `review_agent/file_summary/skills/base.py`、`review_agent/file_summary/skills/registry.py`、`review_agent/file_summary/schemas.py` |
|
||
| 目标 | 建立项目内 Skill 注册与调用机制，后续可迁移 MCP |
|
||
| 开发步骤 | 1. 定义 `WorkflowContext`；2. 定义 `SkillResult`；3. 定义 `BaseSkill`；4. 实现 `SkillRegistry`；5. 支持按名称获取和执行 Skill |
|
||
| 验收标准 | 工作流执行器通过注册表调用 Skill；Skill 输入输出保持 JSON 友好 |
|
||
| 验证命令 | `pytest tests/test_file_summary_skills.py -k registry` |
|
||
| Codex 执行提示 | 请实现文件汇总 Skill 基类、上下文、统一返回结构和注册表，使工作流节点能按需加载 Skill。 |
|
||
|
||
### FS-P4-002 实现压缩包解压 Skill
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 文件处理 |
|
||
| 前置任务 | FS-P4-001 |
|
||
| 涉及文件 | `review_agent/file_summary/services/archive.py`、`review_agent/file_summary/skills/archive_extract.py` |
|
||
| 目标 | 支持 zip、7z、rar 解压，并完成路径穿越防护 |
|
||
| 开发步骤 | 1. 实现压缩包识别；2. 使用 `zipfile` 解压 zip；3. 使用 `py7zr` 解压 7z；4. 使用系统 `7z` 解压 rar；5. 检查解压目标路径必须在批次工作目录内；6. 解压失败标记批次失败 |
|
||
| 验收标准 | zip、7z、rar 均进入解压流程；恶意路径压缩包被拒绝；解压目录保留层级 |
|
||
| 验证命令 | `pytest tests/test_file_summary_archive.py` |
|
||
| Codex 执行提示 | 请实现压缩包解压服务和 Skill，必须支持 zip、7z、rar，并对所有解压路径做 target_dir 内部校验。 |
|
||
|
||
### FS-P4-003 实现文件清单扫描 Skill
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 文件处理 |
|
||
| 前置任务 | FS-P4-002 |
|
||
| 涉及文件 | `review_agent/file_summary/services/inventory.py`、`review_agent/file_summary/skills/file_inventory.py` |
|
||
| 目标 | 扫描解压目录或散装文件，生成 FileSummaryItem 明细 |
|
||
| 开发步骤 | 1. 识别扫描根目录；2. 递归遍历文件；3. 生成相对路径；4. 生成目录层级；5. 标记支持、不支持、空文件或跳过状态；6. 按目录顺序生成 file_index |
|
||
| 验收标准 | 文件明细保留目录层级；散装文件进入同一批次根；relative_path 唯一 |
|
||
| 验证命令 | `pytest tests/test_file_summary_inventory.py` |
|
||
| Codex 执行提示 | 请实现文件清单扫描服务和 Skill，保留目录层级，生成文件序号、相对路径、文件类型和初始统计状态。 |
|
||
|
||
### FS-P4-004 实现页数统计服务
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 文件解析 |
|
||
| 前置任务 | FS-P4-003 |
|
||
| 涉及文件 | `review_agent/file_summary/services/page_count.py` |
|
||
| 目标 | 支持 pdf、doc、docx、xls、xlsx、ppt、pptx 页数或数量统计 |
|
||
| 开发步骤 | 1. pdf 使用 `pypdf` 统计页面；2. docx 使用 `python-docx` 读取内置页数属性；3. doc 使用 `olefile` 读取 OLE 元数据；4. xlsx 使用 `openpyxl` 统计工作表；5. xls 使用 `xlrd` 统计工作表；6. pptx 使用 `python-pptx` 统计幻灯片；7. ppt 使用 `olefile` 读取元数据；8. 无可靠页数时标记 uncertain |
|
||
| 验收标准 | 7 类格式全部有处理分支；读不到页数不崩溃；状态区分 success、failed、unsupported、uncertain |
|
||
| 验证命令 | `pytest tests/test_file_summary_page_count.py` |
|
||
| Codex 执行提示 | 请实现页数统计服务，覆盖 pdf/doc/docx/xls/xlsx/ppt/pptx，老格式读不到可靠页数时标记 uncertain，不允许中断批次。 |
|
||
|
||
### FS-P4-005 实现页数统计 Skill 与三次重试
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / Skill |
|
||
| 前置任务 | FS-P4-004 |
|
||
| 涉及文件 | `review_agent/file_summary/skills/document_page_count.py`、`review_agent/file_summary/services/page_count.py` |
|
||
| 目标 | 对每个支持文件执行页数统计，失败最多重试 3 次 |
|
||
| 开发步骤 | 1. 遍历 FileSummaryItem；2. 支持类型调用 page_count 服务；3. 失败重试 3 次；4. 更新 retry_count、statistics_status、page_count、error_message；5. 更新节点进度事件；6. 汇总批次数量 |
|
||
| 验收标准 | 单文件失败不阻断其他文件；重试事件可记录；批次统计字段更新正确 |
|
||
| 验证命令 | `pytest tests/test_file_summary_page_count.py -k retry` |
|
||
| Codex 执行提示 | 请实现文档页数统计 Skill，对单文件解析失败最多重试 3 次，仍失败则记录异常并继续处理其他文件。 |
|
||
|
||
### FS-P4-006 实现产品名识别 Skill 与会话标题更新
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 识别 |
|
||
| 前置任务 | FS-P4-005 |
|
||
| 涉及文件 | `review_agent/file_summary/services/product_detect.py`、`review_agent/file_summary/skills/product_detect.py` |
|
||
| 目标 | 从目录名、文件名和少量元数据中识别产品名，并按规则更新对话标题 |
|
||
| 开发步骤 | 1. 优先使用顶层目录名；2. 从含“产品”“试剂盒”“说明书”等关键词的文件名提取；3. 尝试读取 docx/PDF 元数据 title；4. 写入 batch.product_name；5. 默认标题时更新 Conversation.title；6. 用户自定义标题不覆盖 |
|
||
| 验收标准 | 识别失败不阻断；识别成功后批次记录产品名；默认对话标题可更新为“产品名-文件汇总” |
|
||
| 验证命令 | `pytest tests/test_file_summary_product_detect.py` |
|
||
| Codex 执行提示 | 请实现产品名识别 Skill，从目录名、文件名和轻量元数据识别产品名，识别成功后按规则更新批次和对话标题。 |
|
||
|
||
### P4 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `pytest tests/test_file_summary_skills.py tests/test_file_summary_archive.py tests/test_file_summary_inventory.py tests/test_file_summary_page_count.py tests/test_file_summary_product_detect.py` |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P4 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 十、P5 报告生成与下载
|
||
|
||
### FS-P5-001 实现 Markdown 报告生成
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 报告 |
|
||
| 前置任务 | P4 |
|
||
| 涉及文件 | `review_agent/file_summary/services/report.py`、`review_agent/file_summary/skills/summary_report.py` |
|
||
| 目标 | 生成完整 Markdown 报告和对话框展示简表 |
|
||
| 开发步骤 | 1. 构建统计摘要；2. 构建对话简表；3. 构建完整 Markdown 报告；4. 保存到批次 exports 目录；5. 创建 ExportedSummaryFile；6. 生成助手消息内容 |
|
||
| 验收标准 | Markdown 包含汇总信息、统计摘要、文件明细、异常清单、处理说明和下载链接占位 |
|
||
| 验证命令 | `pytest tests/test_file_summary_report.py -k markdown` |
|
||
| Codex 执行提示 | 请实现 Markdown 报告生成 Skill，完整报告和对话简表必须包含文件序号、目录层级、文件名、类型、页数、路径、状态、异常说明。 |
|
||
|
||
### FS-P5-002 实现 Excel 导出
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 导出 |
|
||
| 前置任务 | FS-P5-001 |
|
||
| 涉及文件 | `review_agent/file_summary/services/export_excel.py`、`review_agent/file_summary/skills/excel_export.py` |
|
||
| 目标 | 生成 Excel 明细文件 |
|
||
| 开发步骤 | 1. 使用 `openpyxl` 创建 Workbook；2. 创建“汇总信息”Sheet；3. 创建“文件明细”Sheet；4. 写入状态、重试次数和异常说明；5. 保存到 exports 目录；6. 创建 ExportedSummaryFile |
|
||
| 验收标准 | Excel 可打开；至少包含两个工作表；字段与需求一致 |
|
||
| 验证命令 | `pytest tests/test_file_summary_report.py -k excel` |
|
||
| Codex 执行提示 | 请实现 Excel 导出 Skill，生成包含“汇总信息”和“文件明细”两个 Sheet 的汇总文件。 |
|
||
|
||
### FS-P5-003 实现导出下载接口
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 下载 |
|
||
| 前置任务 | FS-P5-002 |
|
||
| 涉及文件 | `review_agent/file_summary/views.py`、`review_agent/file_summary/urls.py` |
|
||
| 目标 | 提供 Markdown 和 Excel 文件下载，并校验权限 |
|
||
| 开发步骤 | 1. 新增 `GET /api/review-agent/file-summary/exports/{export_id}/download/`；2. 校验 export -> batch -> conversation -> user；3. 返回文件流；4. 设置合适文件名；5. 文件不存在时返回错误 |
|
||
| 验收标准 | 当前用户可下载自己的导出文件；不能下载其他用户文件；下载链接可用于 Markdown |
|
||
| 验证命令 | `pytest tests/test_file_summary_views.py -k download` |
|
||
| Codex 执行提示 | 请实现导出文件下载接口，下载权限必须沿 export -> batch -> conversation -> user 校验。 |
|
||
|
||
### FS-P5-004 完成报告 Skill 与工作流衔接
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 后端 / 工作流 |
|
||
| 前置任务 | FS-P5-003 |
|
||
| 涉及文件 | `review_agent/file_summary/workflow.py`、`review_agent/file_summary/services/report.py` |
|
||
| 目标 | 工作流完成后写入助手消息，展示 Markdown 简表和真实下载链接 |
|
||
| 开发步骤 | 1. 报告和 Excel 导出完成后生成下载 URL；2. 替换对话简表中的下载链接；3. 创建 assistant Message；4. 标记 batch success；5. 发送 workflow_completed 事件 |
|
||
| 验收标准 | 工作流完成后对话中出现 Markdown 简表；下载链接可点击；批次状态成功 |
|
||
| 验证命令 | `pytest tests/test_file_summary_workflow.py -k report` |
|
||
| Codex 执行提示 | 请把 Markdown 报告、Excel 导出和工作流完成逻辑串起来，完成后向当前对话写入助手消息。 |
|
||
|
||
### P5 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `pytest tests/test_file_summary_report.py tests/test_file_summary_views.py -k download tests/test_file_summary_workflow.py -k report` |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P5 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 十一、P6 前端三栏与工作流卡片
|
||
|
||
### FS-P6-001 改造页面为三栏布局
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 前端 / 布局 |
|
||
| 前置任务 | P5 |
|
||
| 涉及文件 | `templates/home.html`、实际静态 CSS 文件 |
|
||
| 目标 | 在现有对话页增加右侧第三栏，上半部分上传区，下半部分工作流卡片 |
|
||
| 开发步骤 | 1. 确认真实静态样式文件路径；2. 调整 workspace 结构；3. 增加 `workflow-panel`；4. 增加 `upload-dropzone`；5. 增加 `workflow-card-list`；6. 保证桌面和移动端不遮挡 |
|
||
| 验收标准 | 页面显示左侧会话、中间聊天、右侧上传/工作流三栏；移动端布局可用 |
|
||
| 验证命令 | `pytest tests/test_file_summary_e2e.py -k layout` 或 Playwright 对应命令 |
|
||
| Codex 执行提示 | 请把审核智能体页面改造成三栏布局，右侧上半部分为拖拽上传区，下半部分为工作流卡片列表，并保持现有聊天能力可用。 |
|
||
|
||
### FS-P6-002 实现前端附件上传交互
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 前端 / 上传 |
|
||
| 前置任务 | FS-P6-001 |
|
||
| 涉及文件 | `static/js/app.js`、`templates/home.html`、实际静态 CSS 文件 |
|
||
| 目标 | 支持拖拽或选择多个文件上传，上传成功后展示附件列表 |
|
||
| 开发步骤 | 1. 绑定 dropzone；2. 支持点击选择文件；3. 调用附件上传 API；4. 展示文件名、版本、大小和状态；5. 上传失败展示错误 |
|
||
| 验收标准 | 上传即存储；前端展示当前对话附件；切换对话不串附件 |
|
||
| 验证命令 | Playwright 上传测试 |
|
||
| Codex 执行提示 | 请实现右侧上传区前端交互，支持拖拽和选择多个文件，调用附件上传接口并展示当前对话附件列表。 |
|
||
|
||
### FS-P6-003 实现工作流卡片与 SSE 更新
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 前端 / 工作流 |
|
||
| 前置任务 | FS-P6-002 |
|
||
| 涉及文件 | `static/js/app.js`、实际静态 CSS 文件 |
|
||
| 目标 | 在发送提示词触发工作流后创建卡片，并根据 SSE 更新节点状态 |
|
||
| 开发步骤 | 1. 解析 chat stream 中的 workflow meta；2. 创建 workflow card；3. 连接 batch events SSE；4. 更新节点 pending/running/retrying/success/failed/skipped；5. workflow_completed 后更新完成状态；6. 页面刷新后通过状态接口恢复 |
|
||
| 验收标准 | 工作流节点实时更新；刷新页面可恢复；失败状态可见 |
|
||
| 验证命令 | Playwright 工作流卡片测试 |
|
||
| Codex 执行提示 | 请实现工作流卡片前端逻辑，接收 workflow meta 后连接事件流，实时更新上传、解压、扫描、解析、识别、输出、完成等节点状态。 |
|
||
|
||
### FS-P6-004 实现 Markdown 安全渲染
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 前端 / 渲染 |
|
||
| 前置任务 | FS-P6-003 |
|
||
| 涉及文件 | `templates/home.html`、`static/js/app.js`、静态依赖文件或 CDN 引入 |
|
||
| 目标 | 让助手消息支持 Markdown 表格和下载链接渲染 |
|
||
| 开发步骤 | 1. 引入 `marked + DOMPurify`；2. 普通用户消息保持 escape；3. 助手消息使用安全 Markdown 渲染；4. 历史消息渲染兼容；5. 下载链接可点击 |
|
||
| 验收标准 | Markdown 表格渲染为 HTML table；链接渲染为 a 标签；无明显 XSS 风险 |
|
||
| 验证命令 | Playwright Markdown 渲染测试 |
|
||
| Codex 执行提示 | 请引入 marked + DOMPurify 实现助手消息安全 Markdown 渲染，确保文件汇总结果表格和下载链接正常显示。 |
|
||
|
||
### FS-P6-005 实现 Playwright 端到端测试
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 前端 / E2E |
|
||
| 前置任务 | FS-P6-004 |
|
||
| 涉及文件 | Playwright 测试文件、测试配置 |
|
||
| 目标 | 使用真实浏览器覆盖上传、触发、卡片、渲染、下载和恢复 |
|
||
| 开发步骤 | 1. 创建测试用户；2. 登录系统；3. 打开审核智能体页面；4. 上传动态生成的测试文件；5. 发送“自动汇总文件目录与页数”；6. 等待工作流卡片完成；7. 验证 Markdown table 和下载链接；8. 刷新后验证卡片恢复；9. 验证越权访问失败 |
|
||
| 验收标准 | Playwright 端到端测试通过；关键页面截图可生成；失败时能定位到具体断言 |
|
||
| 验证命令 | Playwright 对应执行命令 |
|
||
| Codex 执行提示 | 请使用 Playwright 增加真实浏览器端到端测试，从登录、上传、发送提示词一直验证到报告渲染、下载和刷新恢复。 |
|
||
|
||
### P6 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | Playwright 端到端测试 + 相关后端接口测试 |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| Codex 执行提示 | P6 验证通过后，请调用 `git-commit-summary` 分析本阶段变更，并按其输出提交到当前开发分支。 |
|
||
|
||
---
|
||
|
||
## 十二、P7 测试、部署与总体验收
|
||
|
||
### FS-P7-001 补齐后端测试矩阵
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 测试 / 后端 |
|
||
| 前置任务 | P6 |
|
||
| 涉及文件 | `tests/test_file_summary_*.py` |
|
||
| 目标 | 覆盖单元、接口、工作流集成和权限隔离 |
|
||
| 开发步骤 | 1. 覆盖触发词；2. 覆盖附件版本；3. 覆盖解压安全；4. 覆盖文件扫描；5. 覆盖页数统计；6. 覆盖报告导出；7. 覆盖下载权限；8. 覆盖完整工作流 |
|
||
| 验收标准 | 后端文件汇总测试全部通过；失败场景覆盖充分 |
|
||
| 验证命令 | `pytest tests/test_file_summary_*.py` |
|
||
| Codex 执行提示 | 请补齐文件汇总后端测试矩阵，覆盖单元、接口、工作流集成和权限隔离。 |
|
||
|
||
### FS-P7-002 补充部署与 Docker 说明
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 部署 / 文档 |
|
||
| 前置任务 | FS-P7-001 |
|
||
| 涉及文件 | README 或部署说明文档 |
|
||
| 目标 | 写明生产或 Docker 部署时的依赖安装和验证方式 |
|
||
| 开发步骤 | 1. 写明 Python 依赖安装；2. 写明 7z/p7zip 安装；3. 写明 rar/7z 验证命令；4. 写明 LibreOffice 非必需、仅未来增强使用；5. 写明 media 文件存储目录 |
|
||
| 验收标准 | 部署说明可指导在 Docker 中启用 rar/7z 解压；依赖边界清楚 |
|
||
| 验证命令 | `python manage.py check` |
|
||
| Codex 执行提示 | 请补充部署说明，明确 Docker 环境需要安装 7z/p7zip 支持 rar/7z，LibreOffice 不是必需依赖。 |
|
||
|
||
### FS-P7-003 执行总体验收
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | 验收 / 流水线 |
|
||
| 前置任务 | FS-P7-002 |
|
||
| 涉及文件 | 无固定文件 |
|
||
| 目标 | 运行全部测试和端到端验证，确认功能完整 |
|
||
| 开发步骤 | 1. 运行 Django check；2. 运行全量 pytest；3. 运行 Playwright E2E；4. 手工或自动验证下载文件可打开；5. 检查数据库记录；6. 检查 git status |
|
||
| 验收标准 | 总体验收标准全部满足；没有未解释的失败测试；没有意外文件变更 |
|
||
| 验证命令 | `python manage.py check`; `pytest`; Playwright 对应命令 |
|
||
| Codex 执行提示 | 请执行文件汇总功能总体验收，运行后端全量测试和 Playwright 端到端测试，确认所有验收标准已满足。 |
|
||
|
||
### FS-P7-004 合并回 V2 分支
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 任务类型 | Git / 收尾 |
|
||
| 前置任务 | FS-P7-003 |
|
||
| 涉及文件 | 无固定文件 |
|
||
| 目标 | 将开发分支合并回 `V2`，并在合并后再次运行总体验收 |
|
||
| 开发步骤 | 1. P7 通过后调用 `git-commit-summary` 提交阶段变更；2. 切换到 `V2`；3. 合并开发分支；4. 解决冲突但不得覆盖用户变更；5. 合并后运行总体验收；6. 保留最终 git status |
|
||
| 验收标准 | 开发分支成功合并到 `V2`；合并后测试通过；本地 Git 历史包含阶段提交 |
|
||
| 验证命令 | `git branch --show-current`; `git status --short`; `python manage.py check`; `pytest`; Playwright 对应命令 |
|
||
| Codex 执行提示 | 请在全部阶段完成后提交 P7 变更，切回 `V2` 并合并开发分支，合并后重新运行总体验收。 |
|
||
|
||
### P7 阶段提交规则
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 阶段验证 | `python manage.py check`; `pytest`; Playwright 端到端测试 |
|
||
| 提交动作 | 调用 `git-commit-summary` 生成提交摘要并提交 |
|
||
| 合并动作 | 所有阶段提交完成后合并回 `V2` |
|
||
| Codex 执行提示 | P7 验证通过后，请调用 `git-commit-summary` 提交本阶段变更，然后合并回 `V2` 并再次总体验收。 |
|
||
|
||
---
|
||
|
||
## 十三、测试分层要求
|
||
|
||
| 层级 | 验证内容 | 建议文件 |
|
||
| --- | --- | --- |
|
||
| 单元测试 | 触发词、附件版本、解压安全、文件扫描、页数统计、报告生成 | `tests/test_file_summary_*.py` |
|
||
| 接口测试 | 上传接口、批次状态接口、事件接口、下载接口、权限隔离 | `tests/test_file_summary_views.py` |
|
||
| 工作流集成测试 | 上传附件后发送提示词，完整执行到生成 Markdown/Excel | `tests/test_file_summary_workflow.py` |
|
||
| Playwright E2E | 登录、上传、触发、卡片更新、Markdown 渲染、下载、刷新恢复 | Playwright 测试文件 |
|
||
| 部署验证 | requirements 安装成功，Docker 中 7z/p7zip 可用，rar/7z 解压可跑通 | 部署说明和验证命令 |
|
||
|
||
说明：测试样例文件不单独拆任务，可在测试代码中动态生成临时 pdf、docx、xlsx、pptx、zip、7z、rar、损坏文件或不可读文件。
|
||
|
||
---
|
||
|
||
## 十四、Codex 自动化执行规则
|
||
|
||
| 规则 | 内容 |
|
||
| --- | --- |
|
||
| 顺序执行 | 必须从 P0 到 P7 顺序执行，不得跳阶段 |
|
||
| 当前阶段优先 | 某阶段测试失败时，必须先修复当前阶段，不得继续后续阶段 |
|
||
| 连续失败处理 | 同一阶段连续 3 次失败时，记录阻塞原因、已尝试方案和下一步建议 |
|
||
| 每任务验证 | 每个任务完成后运行对应验证命令或说明无法运行原因 |
|
||
| 每阶段提交 | 每个阶段全部任务完成并验证通过后，调用 `git-commit-summary` 后本地提交 |
|
||
| 前端强验证 | P6 完成后必须运行 Playwright 端到端测试和截图/断言验证 |
|
||
| 不覆盖变更 | 不得回滚或覆盖用户已有未提交变更 |
|
||
| 合并收尾 | 全部完成后必须合并回 `V2` 并再次总体验收 |
|
||
|
||
---
|
||
|
||
## 十五、推荐一键执行提示词
|
||
|
||
后续可直接对 Codex 输入：
|
||
|
||
```text
|
||
请按 docs/5.开发计划/1.自动汇总.md 执行，从 V2 创建 codex/YYYYMMDD-自动汇总文件目录页数 分支，按 P0 到 P7 顺序开发、验证和阶段提交。每个阶段完成后调用 git-commit-summary 生成提交摘要并本地提交。全部完成后合并回 V2，并重新运行总体验收。
|
||
```
|
||
|
||
---
|
||
|
||
## 十六、待执行前检查清单
|
||
|
||
| 检查项 | 状态 |
|
||
| --- | --- |
|
||
| 需求分析、功能设计、详细设计、数据库设计均已存在 | 待执行时确认 |
|
||
| 当前分支是否为 `V2` | 待执行时确认 |
|
||
| 是否存在用户未提交变更 | 待执行时确认 |
|
||
| Python 依赖是否可安装 | 待执行时确认 |
|
||
| Playwright 或对应 MCP/Skill 是否可用 | 待执行时确认 |
|
||
| 执行机器是否提供 `git-commit-summary` skill | 待执行时确认 |
|
||
| Docker 环境是否可安装 7z/p7zip | 待执行时确认 |
|