docs(materials): 整理文档目录并补充法规材料

docs/2.功能设计/1.自动汇总.md

@@ -0,0 +1,597 @@
+# 自动汇总文件夹文件目录与页数流程功能设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 需求分析文档 | docs/需求分析/1.自动汇总.md |
+| 功能名称 | 自动汇总文件夹文件目录与页数 |
+| 所属模块 | 审核智能体 review_agent |
+| 设计日期 | 2026-06-05 |
+| 设计版本 | V1.0 |
+
+---
+
+## 一、设计目标
+
+本功能面向试剂盒 NMPA 注册申报资料审核场景，支持用户在 AI 对话页上传压缩包或多个文件，由后台异步执行文件汇总工作流，自动完成解压、文件清单扫描、页数统计、产品名识别、Markdown 报告生成和 Excel 导出。
+
+前台 AI 对话页需要展示一个工作流卡片，实时呈现“上传中、解压中、扫描中、解析中、识别中、输出中、完成/失败”等节点状态；工作流完成后，AI 对话框展示 Markdown 简表，并提供 Markdown 报告和 Excel 明细下载链接。上传文件、批次、节点状态、文件明细和导出结果均需要与当前对话绑定，一个对话对应一套文件，不能跨对话串用。
+
+---
+
+## 二、总体架构
+
+### 2.1 架构原则
+
+| 原则 | 说明 |
+| --- | --- |
+| 对话绑定 | 上传文件、处理批次、结果文件均绑定当前 Conversation |
+| 按需加载 | 将文件处理流程拆分为多个可单独执行的 Skill，按工作流节点调用 |
+| 后台异步 | 用户提交后后台执行工作流，前台通过 SSE 接收状态事件 |
+| 失败隔离 | 解压失败导致批次失败；单文件解析失败最多重试 3 次后记录异常并继续 |
+| 可迁移 MCP | Demo 阶段使用项目内 Skill 注册与调用，后续可迁移为 MCP Tool |
+| 可追溯 | 每个节点状态、文件统计结果、导出文件均持久化入库 |
+
+### 2.2 逻辑架构
+
+```mermaid
+flowchart TD
+    A["AI 对话页"] --> B["上传接收接口"]
+    B --> C["工作流任务表"]
+    C --> D["后台工作流执行器"]
+    D --> E["Skill 注册表"]
+    E --> F1["上传接收 Skill"]
+    E --> F2["压缩包解压 Skill"]
+    E --> F3["文件清单扫描 Skill"]
+    E --> F4["文档页数统计 Skill"]
+    E --> F5["产品信息识别 Skill"]
+    E --> F6["汇总报告生成 Skill"]
+    E --> F7["Excel 导出 Skill"]
+    D --> G["数据库存档"]
+    D --> H["导出文件存储"]
+    D --> I["SSE 状态事件"]
+    I --> A
+```
+
+### 2.3 技术选型
+
+| 设计项 | Demo 方案 | 后续演进 |
+| --- | --- | --- |
+| 工作流编排 | 项目内 LangGraph 风格节点图执行器 | 接入 LangGraph |
+| Skill 形态 | Python 类或函数注册表，按节点名称动态调用 | 封装为 MCP Tool |
+| 后台任务 | Django 后台线程 + 数据库状态 | Celery/RQ + Redis |
+| 实时更新 | 沿用现有 SSE 流式能力，新增 workflow 事件 | 独立任务事件通道 |
+| 文件存储 | 本地 media 目录 | 对象存储或加密文件服务 |
+| Markdown 渲染 | 前端引入安全 Markdown 渲染 | 统一富文本渲染组件 |
+
+---
+
+## 三、工作流设计
+
+### 3.1 节点图
+
+```mermaid
+flowchart LR
+    N1["上传中"] --> N2{"是否压缩包"}
+    N2 -->|"是"| N3["解压中"]
+    N2 -->|"否"| N4["扫描中"]
+    N3 --> N4
+    N4 --> N5["解析页数中"]
+    N5 --> N6["识别产品名中"]
+    N6 --> N7["输出中"]
+    N7 --> N8["完成"]
+    N3 -->|"解压失败"| F["失败"]
+    N7 -->|"导出失败"| F
+```
+
+### 3.2 节点定义
+
+| 节点编码 | 节点名称 | 触发 Skill | 成功条件 | 失败处理 |
+| --- | --- | --- | --- | --- |
+| upload | 上传中 | 上传接收 Skill | 原始文件保存成功，批次创建成功 | 批次失败 |
+| extract | 解压中 | 压缩包解压 Skill | zip/rar/7z 等压缩包解压成功 | 批次失败 |
+| inventory | 扫描中 | 文件清单扫描 Skill | 生成文件清单 | 批次失败或空文件提示 |
+| page_count | 解析页数中 | 文档页数统计 Skill | 支持类型完成页数统计或异常记录 | 单文件失败不阻断 |
+| product_detect | 识别产品名中 | 产品信息识别 Skill | 识别到产品名或返回空 | 不阻断 |
+| report | 输出中 | 汇总报告生成 Skill | Markdown 报告与对话简表生成成功 | 批次失败 |
+| export | 输出中 | Excel 导出 Skill | Excel 明细生成成功 | 批次失败或记录导出异常 |
+| completed | 完成 | 工作流执行器 | 所有必需产物完成 | 写入完成状态 |
+
+### 3.3 状态机
+
+| 状态 | 含义 |
+| --- | --- |
+| pending | 已创建，等待执行 |
+| running | 执行中 |
+| retrying | 单文件解析失败，正在重试 |
+| success | 节点执行成功 |
+| failed | 节点或批次失败 |
+| skipped | 当前节点不需要执行，例如非压缩包跳过解压 |
+
+---
+
+## 四、Skill 设计
+
+### 4.1 Skill 注册与调用
+
+Demo 阶段在项目内定义 Skill 注册表，工作流执行器根据节点编码按需加载并执行对应 Skill。
+
+```text
+WorkflowExecutor
+-> 根据当前节点读取 Skill 名称
+-> 从 SkillRegistry 获取 Skill
+-> 执行 skill.run(context)
+-> 写入节点状态与结果
+-> 发送 SSE 状态事件
+-> 进入下一节点
+```
+
+后续 MCP 化时，每个 Skill 可映射为独立 MCP Tool，输入输出保持稳定 JSON 契约。
+
+### 4.2 上传接收 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 上传接收 Skill |
+| 职责 | 接收对话页上传的压缩包或多个文件，保存原始文件，创建上传批次 |
+| 输入 | conversation_id、user_id、uploaded_files |
+| 输出 | batch_id、upload_file_ids、upload_type、original_storage_paths |
+| 数据写入 | FileSummaryBatch、UploadedSourceFile |
+| 关键规则 | 文件必须绑定当前 Conversation；同一对话只使用本对话上传的文件 |
+
+### 4.3 压缩包解压 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 压缩包解压 Skill |
+| 职责 | 识别并解压 zip、rar、7z 等常见压缩包，保留目录结构 |
+| 输入 | batch_id、source_file_path |
+| 输出 | extract_root、extracted_file_count |
+| 数据写入 | WorkflowNodeRun、批次工作目录 |
+| 关键规则 | 防止路径穿越；解压目录必须限定在批次工作目录内；解压失败批次失败 |
+
+### 4.4 文件清单扫描 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 文件清单扫描 Skill |
+| 职责 | 遍历解压目录或散装文件目录，生成文件清单 |
+| 输入 | batch_id、scan_root |
+| 输出 | inventory_items |
+| 数据写入 | FileSummaryItem |
+| 关键规则 | 保留目录层级；散装文件归入同一批次根目录；隐藏文件和空文件可标记跳过 |
+
+### 4.5 文档页数统计 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 文档页数统计 Skill |
+| 职责 | 对支持类型统计页数或数量 |
+| 输入 | batch_id、FileSummaryItem 列表 |
+| 输出 | page_count、statistics_status、error_message |
+| 数据写入 | FileSummaryItem |
+| 关键规则 | 支持 pdf、doc、docx、xls、xlsx、ppt、pptx；单文件失败最多重试 3 次，仍失败则记录异常并继续 |
+
+页数统计口径：
+
+| 文件类型 | 统计口径 |
+| --- | --- |
+| pdf | PDF 页面数量 |
+| doc/docx | 优先转 PDF 后统计页面数量 |
+| xls/xlsx | Demo 阶段按工作表数量统计 |
+| ppt/pptx | 按幻灯片数量统计 |
+
+### 4.6 产品信息识别 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 产品信息识别 Skill |
+| 职责 | 尝试识别产品名称，并用于更新对话标题 |
+| 输入 | batch_id、文件名、目录名、可读取文本片段 |
+| 输出 | product_name、confidence、evidence |
+| 数据写入 | FileSummaryBatch.product_name、Conversation.title |
+| 关键规则 | 优先从文件名和目录名识别；其次读取文档首页或关键文本；识别失败不阻断流程 |
+
+会话标题规则：
+
+| 场景 | 标题处理 |
+| --- | --- |
+| 识别到产品名 | 更新为“产品名-文件汇总” |
+| 未识别产品名 | 保持原对话标题 |
+| 用户已手动命名 | 可保留用户标题，产品名写入批次信息 |
+
+### 4.7 汇总报告生成 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | 汇总报告生成 Skill |
+| 职责 | 生成完整 Markdown 报告和对话框展示简表 |
+| 输入 | batch_id、统计摘要、文件明细、异常清单 |
+| 输出 | markdown_report_path、assistant_markdown_summary |
+| 数据写入 | ExportedSummaryFile、Message |
+| 关键规则 | Markdown 简表需要适合前端对话框渲染；完整报告包含全部文件明细 |
+
+### 4.8 Excel 导出 Skill
+
+| 项目 | 说明 |
+| --- | --- |
+| 中文名称 | Excel 导出 Skill |
+| 职责 | 生成 Excel 汇总文件 |
+| 输入 | batch_id、统计摘要、文件明细 |
+| 输出 | excel_path、download_url |
+| 数据写入 | ExportedSummaryFile |
+| 关键规则 | 至少包含“汇总信息”“文件明细”两个 Sheet |
+
+---
+
+## 五、数据模型设计
+
+### 5.1 FileSummaryBatch
+
+文件汇总批次，表示一次对话内的文件汇总任务。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BigAutoField | 主键 |
+| conversation | ForeignKey(Conversation) | 绑定对话 |
+| user | ForeignKey(User) | 上传用户 |
+| batch_no | CharField | 批次编号 |
+| product_name | CharField | 识别出的产品名，可为空 |
+| upload_type | CharField | archive、multi_file |
+| status | CharField | pending、running、success、failed |
+| total_files | Integer | 文件总数 |
+| supported_files | Integer | 支持统计的文件数 |
+| success_files | Integer | 统计成功数 |
+| failed_files | Integer | 统计失败数 |
+| unsupported_files | Integer | 不支持文件数 |
+| total_pages | Integer | 总页数 |
+| work_dir | CharField | 批次工作目录 |
+| error_message | TextField | 批次异常说明 |
+| created_at | DateTimeField | 创建时间 |
+| started_at | DateTimeField | 开始时间 |
+| finished_at | DateTimeField | 完成时间 |
+
+### 5.2 UploadedSourceFile
+
+上传原始文件记录。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BigAutoField | 主键 |
+| batch | ForeignKey(FileSummaryBatch) | 所属批次 |
+| original_name | CharField | 原始文件名 |
+| storage_path | CharField | 保存路径 |
+| file_size | BigInteger | 文件大小 |
+| content_type | CharField | MIME 类型 |
+| created_at | DateTimeField | 上传时间 |
+
+### 5.3 FileSummaryItem
+
+文件明细记录。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BigAutoField | 主键 |
+| batch | ForeignKey(FileSummaryBatch) | 所属批次 |
+| file_index | Integer | 文件序号 |
+| directory_level | CharField | 目录层级 |
+| file_name | CharField | 文件名 |
+| file_type | CharField | 文件类型 |
+| relative_path | CharField | 相对路径 |
+| storage_path | CharField | 实际处理路径 |
+| page_count | Integer | 页数，可为空 |
+| statistics_status | CharField | success、failed、unsupported、skipped |
+| retry_count | Integer | 页数统计重试次数 |
+| error_message | TextField | 异常说明 |
+| created_at | DateTimeField | 创建时间 |
+| updated_at | DateTimeField | 更新时间 |
+
+### 5.4 WorkflowNodeRun
+
+工作流节点运行记录。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BigAutoField | 主键 |
+| batch | ForeignKey(FileSummaryBatch) | 所属批次 |
+| node_code | CharField | 节点编码 |
+| node_name | CharField | 节点名称 |
+| status | CharField | pending、running、retrying、success、failed、skipped |
+| progress | Integer | 进度百分比 |
+| message | TextField | 节点提示 |
+| started_at | DateTimeField | 开始时间 |
+| finished_at | DateTimeField | 完成时间 |
+
+### 5.5 ExportedSummaryFile
+
+导出文件记录。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BigAutoField | 主键 |
+| batch | ForeignKey(FileSummaryBatch) | 所属批次 |
+| export_type | CharField | markdown、excel |
+| file_name | CharField | 文件名 |
+| storage_path | CharField | 保存路径 |
+| download_url | CharField | 下载链接 |
+| status | CharField | success、failed |
+| error_message | TextField | 导出异常说明 |
+| created_at | DateTimeField | 生成时间 |
+
+---
+
+## 六、后端接口设计
+
+### 6.1 上传并启动工作流
+
+| 项目 | 内容 |
+| --- | --- |
+| URL | POST /api/review-agent/conversations/{conversation_id}/file-summary/start/ |
+| 认证 | 登录用户 |
+| 请求类型 | multipart/form-data |
+| 请求参数 | files[]、prompt |
+| 响应 | batch_id、status、workflow_nodes |
+
+处理逻辑：
+
+```text
+校验 conversation 属于当前用户
+-> 保存上传文件
+-> 创建 FileSummaryBatch
+-> 创建 WorkflowNodeRun 初始节点
+-> 启动后台线程执行工作流
+-> 返回 batch_id 和初始节点状态
+```
+
+### 6.2 工作流 SSE 事件流
+
+| 项目 | 内容 |
+| --- | --- |
+| URL | GET /api/review-agent/file-summary/{batch_id}/events/ |
+| 认证 | 登录用户 |
+| 响应类型 | text/event-stream |
+
+事件类型：
+
+| 事件 | 说明 |
+| --- | --- |
+| workflow_started | 工作流开始 |
+| node_started | 节点开始 |
+| node_progress | 节点进度更新 |
+| node_retrying | 单文件解析重试 |
+| node_completed | 节点完成 |
+| node_failed | 节点失败 |
+| workflow_completed | 工作流完成 |
+| workflow_failed | 工作流失败 |
+
+示例：
+
+```json
+{
+  "batch_id": 12,
+  "node_code": "page_count",
+  "node_name": "解析页数中",
+  "status": "retrying",
+  "progress": 42,
+  "message": "检测报告.pdf 解析失败，正在第 2 次重试"
+}
+```
+
+### 6.3 查询批次状态
+
+| 项目 | 内容 |
+| --- | --- |
+| URL | GET /api/review-agent/file-summary/{batch_id}/ |
+| 认证 | 登录用户 |
+| 响应 | 批次摘要、节点状态、文件简表、导出文件链接 |
+
+用途：
+
+| 场景 | 说明 |
+| --- | --- |
+| 页面刷新恢复 | 前端重新加载后恢复工作流卡片状态 |
+| 历史记录查看 | 从会话历史进入后展示已完成汇总结果 |
+
+### 6.4 下载导出文件
+
+| 项目 | 内容 |
+| --- | --- |
+| URL | GET /api/review-agent/file-summary/exports/{export_id}/download/ |
+| 认证 | 登录用户 |
+| 响应 | 文件流 |
+
+权限规则：
+
+```text
+export_id -> batch -> conversation -> user
+必须等于当前登录用户，才允许下载。
+```
+
+---
+
+## 七、前端设计
+
+### 7.1 AI 对话页改造
+
+现有 `templates/home.html` 和 `static/js/app.js` 需要增强：
+
+| 改造点 | 说明 |
+| --- | --- |
+| 附件选择 | 在输入框旁增加文件上传按钮，支持压缩包和多个文件 |
+| 工作流卡片 | 用户提交后在对话流中插入工作流状态卡片 |
+| SSE 监听 | 监听后台节点事件，实时更新卡片节点状态 |
+| Markdown 渲染 | AI 回复支持 Markdown 表格和下载链接渲染 |
+| 状态恢复 | 页面刷新后查询批次状态，恢复工作流卡片 |
+
+### 7.2 工作流卡片
+
+卡片包含节点列表：
+
+| 节点 | 前台展示文案 |
+| --- | --- |
+| upload | 上传中 |
+| extract | 解压中 |
+| inventory | 扫描中 |
+| page_count | 解析页数中 |
+| product_detect | 识别产品名中 |
+| report/export | 输出中 |
+| completed | 已完成 |
+
+节点状态样式：
+
+| 状态 | 展示 |
+| --- | --- |
+| pending | 灰色等待 |
+| running | 高亮进行中 |
+| retrying | 黄色重试中 |
+| success | 绿色完成 |
+| failed | 红色失败 |
+| skipped | 灰色跳过 |
+
+### 7.3 对话框结果展示
+
+工作流完成后，AI 对话框新增助手消息，内容为 Markdown：
+
+```markdown
+已完成文件目录与页数汇总。
+
+| 指标 | 数量 |
+| --- | --- |
+| 文件总数 | 24 |
+| 统计成功 | 21 |
+| 统计失败 | 2 |
+| 不支持 | 1 |
+| 总页数 | 386 |
+
+| 序号 | 目录层级 | 文件名 | 类型 | 页数 | 状态 | 异常说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | 注册资料/说明书 | 说明书.docx | docx | 12 | 成功 |  |
+| 2 | 注册资料/检测报告 | 检测报告.pdf | pdf | 38 | 成功 |  |
+
+[下载 Markdown 报告](download-url)
+[下载 Excel 明细](download-url)
+```
+
+---
+
+## 八、后台服务设计
+
+### 8.1 WorkflowExecutor
+
+负责批次级工作流编排。
+
+| 方法 | 说明 |
+| --- | --- |
+| start(batch_id) | 启动后台任务 |
+| run(batch_id) | 串行执行节点图 |
+| run_node(node_code, context) | 执行单个节点 |
+| emit_event(batch_id, event_type, payload) | 写入并推送事件 |
+| complete(batch_id) | 完成批次 |
+| fail(batch_id, error) | 标记批次失败 |
+
+### 8.2 SkillRegistry
+
+负责 Skill 注册与按需加载。
+
+| 方法 | 说明 |
+| --- | --- |
+| register(name, skill_cls) | 注册 Skill |
+| get(name) | 获取 Skill |
+| run(name, context) | 执行 Skill |
+
+### 8.3 PageCountService
+
+负责具体文件页数统计。
+
+| 方法 | 说明 |
+| --- | --- |
+| count_pdf(path) | 统计 PDF 页面数 |
+| count_word(path) | doc/docx 转 PDF 后统计页面数 |
+| count_excel(path) | 统计工作表数量 |
+| count_ppt(path) | 统计幻灯片数量 |
+| count_with_retry(item, max_retry=3) | 单文件重试统计 |
+
+### 8.4 ExportService
+
+负责 Markdown 和 Excel 导出。
+
+| 方法 | 说明 |
+| --- | --- |
+| build_markdown_report(batch) | 生成完整 Markdown 报告 |
+| build_chat_summary(batch) | 生成对话简表 |
+| build_excel(batch) | 生成 Excel 明细 |
+| create_download_record(batch, path, type) | 创建下载记录 |
+
+---
+
+## 九、异常与重试设计
+
+### 9.1 批次级失败
+
+| 场景 | 处理 |
+| --- | --- |
+| 上传保存失败 | 批次不创建或标记失败 |
+| 压缩包无法解压 | 批次失败，工作流终止 |
+| 文件清单为空 | 批次失败，提示未检测到可处理文件 |
+| 报告导出失败 | 批次失败或标记导出异常 |
+
+### 9.2 文件级失败
+
+| 场景 | 处理 |
+| --- | --- |
+| 单文件页数解析失败 | 最多重试 3 次 |
+| 重试仍失败 | statistics_status=failed，记录异常说明，继续处理其他文件 |
+| 不支持类型 | statistics_status=unsupported，不重试 |
+| 加密或损坏文件 | statistics_status=failed，记录“文件加密或损坏” |
+
+---
+
+## 十、安全设计
+
+| 设计点 | 说明 |
+| --- | --- |
+| 对话隔离 | 所有批次查询和下载必须校验 conversation.user |
+| 防串文件 | 工作流只能读取当前 batch 绑定的 UploadedSourceFile |
+| 解压安全 | 禁止压缩包内路径跳出批次工作目录 |
+| 文件执行安全 | 不执行上传文件中的脚本、宏或外部链接 |
+| 下载权限 | 下载接口必须验证当前用户拥有批次所属对话 |
+| 存储隔离 | 按 user_id/conversation_id/batch_id 建立存储目录 |
+
+---
+
+## 十一、验收设计
+
+| 序号 | 验收项 | 验收标准 |
+| --- | --- | --- |
+| 1 | 对话绑定 | A 对话上传的文件不会出现在 B 对话的汇总结果中 |
+| 2 | 压缩包处理 | 支持 zip、rar、7z 常见压缩包解压并保留目录结构 |
+| 3 | 多文件处理 | 支持一次上传多个散装文件并生成同一批次结果 |
+| 4 | 工作流卡片 | 前台能实时展示上传中、解压中、扫描中、解析中、输出中、完成状态 |
+| 5 | 解析重试 | 单文件解析失败最多重试 3 次，失败后记录异常并继续 |
+| 6 | Markdown 展示 | 对话框能正确渲染 Markdown 表格和下载链接 |
+| 7 | 导出下载 | Markdown 报告和 Excel 明细可通过对话框链接下载 |
+| 8 | 数据存档 | 数据库保留批次、上传文件、节点状态、文件明细、导出文件记录 |
+| 9 | 标题更新 | 识别到产品名后，可将会话标题更新为“产品名-文件汇总” |
+
+---
+
+## 十二、待确认事项
+
+| 序号 | 问题 | 当前建议 | 状态 |
+| --- | --- | --- | --- |
+| 1 | 是否接入真实 LangGraph 依赖 | Demo 先按 LangGraph 节点图思想自实现轻量编排器 | 待确认 |
+| 2 | rar/7z 解压依赖 | 可选 py7zr、rarfile、系统 7z 命令 | 待技术验证 |
+| 3 | doc/docx 转 PDF 依赖 | 建议使用 LibreOffice headless | 待技术验证 |
+| 4 | 用户手动命名对话时是否允许覆盖 | 建议不覆盖，仅写入产品名字段 | 待确认 |
+| 5 | 后台任务是否需要取消能力 | Demo 可不做，正式版建议支持取消 | 待确认 |
+
+---
+
+## 十三、实施建议
+
+1. 先补充数据模型和迁移，建立批次、文件明细、节点状态和导出文件表。
+2. 增加上传并启动工作流接口，确保文件和当前对话强绑定。
+3. 实现轻量 WorkflowExecutor 和 SkillRegistry，先完成 zip、pdf、xlsx、pptx 的主链路。
+4. 改造前端对话框，增加附件上传、工作流卡片和 Markdown 渲染。
+5. 补齐 doc/docx、rar、7z 等依赖能力，再完善异常重试和下载权限测试。