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

docs/1.需求分析/1.自动汇总.md

@@ -0,0 +1,328 @@
+# 自动汇总文件夹文件目录与页数流程需求分析
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 原始材料 | docs/原始材料/【模拟题二】试剂盒临床注册文件准备与审核Agent.docx |
+| 功能主题 | 自动汇总注册申报资料文件目录与页数 |
+| 分析日期 | 2026-06-05 |
+| 分析版本 | V1.0 |
+
+---
+
+## 一、需求背景
+
+试剂盒 NMPA 注册申报过程中，研发或注册人员需要准备大量文件，包括产品技术要求、说明书、检测报告、临床评估资料等。原始材料中明确提出智能体需要具备“自动汇总注册申报文件夹中的所有文件及页数”的能力，作为后续法规完整性检查、缺失文件预警、信息提取和一致性核查的基础数据来源。
+
+本功能目标是：用户在 AI 对话框上传注册申报资料压缩包、文件夹或多个散装文件后，系统自动扫描资料结构，统计各文件的目录层级、文件类型、页数、路径和处理状态，生成 Markdown 汇总报告与 Excel 文件，并在 AI 对话框中展示简表和下载链接，同时将汇总结果存入数据库。
+
+---
+
+## 二、需求范围
+
+### 2.1 本期范围
+
+| 序号 | 范围项 | 说明 |
+| --- | --- | --- |
+| 1 | 文件上传入口 | 用户通过现有 AI 对话框上传压缩包、文件夹或多个散装文件 |
+| 2 | 文件解析 | 系统识别上传内容并展开为待扫描文件清单 |
+| 3 | 目录汇总 | 保留原始目录层级，散装文件归入默认上传批次目录 |
+| 4 | 页数统计 | 默认支持 pdf、doc、docx、xls、xlsx、ppt、pptx |
+| 5 | 结果展示 | AI 对话框中展示 Markdown 简表 |
+| 6 | 文件导出 | 生成 Markdown 报告与 Excel 汇总表，并在对话框提供下载链接 |
+| 7 | 数据存档 | 上传批次、文件明细、页数、异常状态、导出文件信息写入数据库 |
+
+### 2.2 非本期范围
+
+| 序号 | 范围项 | 说明 |
+| --- | --- | --- |
+| 1 | NMPA 法规完整性核查 | 依赖目录汇总结果，属于后续流程 |
+| 2 | 产品关键信息抽取 | 依赖具体文档内容解析，属于后续流程 |
+| 3 | 文档一致性核查 | 依赖信息抽取结果，属于后续流程 |
+| 4 | 合规风险预警 | 本功能仅输出文件扫描异常，不输出法规合规风险 |
+
+---
+
+## 三、用户角色与使用场景
+
+| 角色 | 诉求 | 典型场景 |
+| --- | --- | --- |
+| 注册人员 | 快速了解申报资料是否完整、页数是否可统计 | 上传供应商或研发团队整理好的注册资料压缩包 |
+| 审核人员 | 获得可复核的文件目录和页数清单 | 在审核前获取 Markdown 简表和 Excel 明细 |
+| 系统管理员 | 追踪上传批次和处理异常 | 查看数据库存档，定位文件解析失败原因 |
+
+---
+
+## 四、业务流程分析
+
+### 4.1 主流程
+
+```text
+用户进入 AI 对话框
+-> 上传压缩包、文件夹或多个散装文件
+-> 用户发送“自动汇总文件目录与页数”类指令
+-> 系统创建上传批次
+-> 系统保存原始上传文件
+-> 系统识别上传类型
+-> 如为压缩包则解压，如为文件夹或散装文件则直接扫描
+-> 系统遍历文件并识别目录层级
+-> 系统过滤支持的文件类型
+-> 系统计数每个支持文件的页数
+-> 系统记录不支持或统计失败的文件异常
+-> 系统生成 Markdown 报告与 Excel 文件
+-> 系统在 AI 对话框展示 Markdown 简表和下载链接
+-> 系统将批次和明细数据写入数据库
+-> 结束
+```
+
+### 4.2 分支流程
+
+| 分支场景 | 流程说明 |
+| --- | --- |
+| 上传压缩包 | 系统校验压缩包格式，解压至临时工作目录，按解压后的目录结构统计 |
+| 上传文件夹 | 系统保留文件夹层级，扫描所有子目录文件 |
+| 上传多个散装文件 | 系统生成默认批次目录，将所有文件视为同一层级 |
+| 存在不支持类型 | 文件进入明细表，页数为空，统计状态为“不支持”，异常说明记录文件类型 |
+| 单个文件页数统计失败 | 不中断整个批次，统计状态为“失败”，异常说明记录失败原因 |
+| 重名文件 | 以完整相对路径区分；散装文件重名时使用系统保存路径或自动重命名策略避免覆盖 |
+
+### 4.3 异常流程
+
+| 异常场景 | 处理方式 |
+| --- | --- |
+| 上传文件为空 | 对话框提示“未检测到可处理文件”，不生成报告 |
+| 压缩包损坏或无法解压 | 批次状态标记为失败，对话框展示错误原因 |
+| 文件被加密或受保护 | 明细记录该文件，页数统计失败，异常说明标记“文件加密或无法读取” |
+| 文件过大或处理超时 | 明细记录超时状态，批次可继续处理其他文件 |
+| Excel/Markdown 导出失败 | 对话框提示导出失败，数据库保留扫描明细与失败原因 |
+
+---
+
+## 五、功能模块梳理
+
+### 5.1 核心功能
+
+| 序号 | 功能名称 | 功能描述 | 优先级 |
+| --- | --- | --- | --- |
+| 1 | 上传资料接收 | 支持用户在 AI 对话框上传压缩包、文件夹或多个散装文件 | P0 |
+| 2 | 上传批次管理 | 为每次汇总创建批次编号，记录用户、时间、来源会话和处理状态 | P0 |
+| 3 | 压缩包解压 | 支持压缩包上传后的安全解压和目录结构保留 | P0 |
+| 4 | 文件遍历扫描 | 递归扫描上传范围内所有文件，生成相对路径和目录层级 | P0 |
+| 5 | 文件类型识别 | 根据扩展名和必要的文件头信息识别 pdf、doc、docx、xls、xlsx、ppt、pptx | P0 |
+| 6 | 页数统计 | 对支持文件统计页数或页签/幻灯片数量 | P0 |
+| 7 | Markdown 简表展示 | 在 AI 对话框展示可解析的 Markdown 表格摘要 | P0 |
+| 8 | Markdown 报告导出 | 生成完整 Markdown 汇总报告 | P0 |
+| 9 | Excel 明细导出 | 生成 Excel 文件，包含所有文件明细和统计状态 | P0 |
+| 10 | 数据库存档 | 保存批次、文件明细、统计结果、异常说明和导出文件记录 | P0 |
+
+### 5.2 辅助功能
+
+| 序号 | 功能名称 | 功能描述 | 优先级 |
+| --- | --- | --- | --- |
+| 1 | 下载链接生成 | 在 AI 回复中提供 Markdown 报告和 Excel 文件下载链接 | P0 |
+| 2 | 处理进度提示 | 对较大批次展示“上传中、解析中、统计中、导出中、已完成”等状态 | P1 |
+| 3 | 文件过滤规则 | 支持过滤系统隐藏文件、临时文件和空文件 | P1 |
+| 4 | 统计摘要 | 输出文件总数、支持文件数、统计成功数、失败数、总页数 | P1 |
+| 5 | 历史记录查询 | 可通过对话记录或批次记录回看历史汇总结果 | P1 |
+
+### 5.3 隐含功能
+
+| 序号 | 功能名称 | 功能描述 | 来源说明 |
+| --- | --- | --- | --- |
+| 1 | AI 对话框附件上传能力 | 现有对话框需要支持上传附件并关联会话消息 | 用户要求“在 AI 对话框中提供下载连接” |
+| 2 | Markdown 渲染能力 | 现有对话框需要能解析表格、链接等 Markdown 内容 | 用户要求“对话框能正常解析 md 格式” |
+| 3 | 文件访问权限控制 | 下载链接只能允许当前用户或授权用户访问 | 涉及注册资料敏感文件 |
+| 4 | 临时文件清理 | 解压目录和处理中间文件需要定期清理 | 压缩包和大文件处理会产生临时文件 |
+
+---
+
+## 六、数据实体分析
+
+### 6.1 实体列表
+
+| 序号 | 实体名称 | 字段说明 | 关联实体 |
+| --- | --- | --- | --- |
+| 1 | 汇总批次 | 批次编号、用户、会话、上传类型、文件数量、总页数、状态、创建时间、完成时间 | 会话、文件明细、导出文件 |
+| 2 | 文件明细 | 文件序号、目录层级、文件名、文件类型、页数、路径、统计状态、异常说明 | 汇总批次 |
+| 3 | 导出文件 | 文件类型、文件名、保存路径、下载地址、生成状态、生成时间 | 汇总批次 |
+| 4 | 上传原始文件 | 原始文件名、保存路径、大小、文件类型、上传时间 | 汇总批次 |
+
+### 6.2 文件明细字段
+
+| 字段 | 类型建议 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| file_index | Integer | 是 | 文件序号，按目录遍历顺序生成 |
+| directory_level | String | 是 | 目录层级，如“1/2/3”或“注册资料/产品技术要求” |
+| file_name | String | 是 | 文件名，不含目录 |
+| file_type | String | 是 | 文件扩展名或识别后的类型 |
+| page_count | Integer | 否 | 页数，统计失败或不支持时为空 |
+| relative_path | String | 是 | 相对上传根目录的路径 |
+| statistics_status | String | 是 | 成功、失败、不支持、跳过 |
+| error_message | Text | 否 | 异常说明 |
+
+### 6.3 实体关系
+
+```text
+会话 1:N 汇总批次
+汇总批次 1:N 上传原始文件
+汇总批次 1:N 文件明细
+汇总批次 1:N 导出文件
+```
+
+---
+
+## 七、输出要求
+
+### 7.1 AI 对话框简表
+
+AI 回复内容必须使用前端可解析的 Markdown 格式，至少包含统计摘要、文件简表和下载链接。
+
+示例：
+
+```markdown
+已完成文件目录与页数汇总。
+
+| 指标 | 数量 |
+| --- | --- |
+| 文件总数 | 24 |
+| 统计成功 | 21 |
+| 统计失败 | 2 |
+| 不支持 | 1 |
+| 总页数 | 386 |
+
+| 序号 | 目录层级 | 文件名 | 类型 | 页数 | 状态 | 异常说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | 注册资料/说明书 | 说明书.docx | docx | 12 | 成功 |  |
+| 2 | 注册资料/检测报告 | 检测报告.pdf | pdf | 38 | 成功 |  |
+
+[下载 Markdown 报告](download-url)
+[下载 Excel 明细](download-url)
+```
+
+### 7.2 Markdown 报告
+
+Markdown 报告应包含：
+
+| 模块 | 内容 |
+| --- | --- |
+| 汇总信息 | 批次编号、上传用户、上传时间、处理完成时间、上传类型 |
+| 统计摘要 | 文件总数、支持文件数、成功数、失败数、不支持数、总页数 |
+| 文件明细 | 文件序号、目录层级、文件名、文件类型、页数、路径、统计状态、异常说明 |
+| 异常清单 | 统计失败、不支持、解压失败、加密文件、超时文件 |
+| 处理说明 | 支持范围、页数统计口径、待确认事项 |
+
+### 7.3 Excel 导出
+
+Excel 至少包含两个工作表：
+
+| 工作表 | 内容 |
+| --- | --- |
+| 汇总信息 | 批次信息、统计摘要 |
+| 文件明细 | 文件序号、目录层级、文件名、文件类型、页数、路径、统计状态、异常说明 |
+
+---
+
+## 八、页数统计口径
+
+| 文件类型 | 统计口径 | 备注 |
+| --- | --- | --- |
+| pdf | PDF 页面数量 | 可使用 pdfplumber 或 PyMuPDF |
+| doc | Word 文档页数 | 可通过 LibreOffice 转 PDF 后统计，或读取文档属性；实现方案待技术验证 |
+| docx | Word 文档页数 | 可通过 LibreOffice 转 PDF 后统计，或读取文档属性；实现方案待技术验证 |
+| xls | Excel 工作表打印页数或页签数量 | 具体口径待确认 |
+| xlsx | Excel 工作表打印页数或页签数量 | 具体口径待确认 |
+| ppt | 幻灯片数量 | 可转换或读取演示文稿结构 |
+| pptx | 幻灯片数量 | 可读取演示文稿结构 |
+
+> 待确认：Excel 的“页数”是否按打印分页统计，还是按工作表数量统计。建议 Demo 阶段先按工作表数量统计，并在报告中明确口径。
+
+---
+
+## 九、非功能性需求
+
+### 9.1 性能要求
+
+| 项目 | 要求 |
+| --- | --- |
+| 小批次文件 | 50 个文件以内，应在 30 秒内完成汇总 |
+| 中等批次文件 | 200 个文件以内，应支持异步处理或进度提示 |
+| 大文件处理 | 单文件超时不影响其他文件统计 |
+
+### 9.2 安全要求
+
+| 项目 | 要求 |
+| --- | --- |
+| 上传安全 | 限制可处理类型，避免执行上传文件中的脚本或宏 |
+| 解压安全 | 防止路径穿越，限制解压目录在系统工作目录内 |
+| 下载权限 | 下载链接需要校验登录用户和会话权限 |
+| 数据隔离 | 不同用户上传文件和统计结果不可互相访问 |
+| 敏感资料保护 | 原始上传文件、报告和 Excel 文件应存储在受控目录 |
+
+### 9.3 可用性要求
+
+| 项目 | 要求 |
+| --- | --- |
+| 对话展示 | Markdown 表格、链接在现有 AI 对话框中可正常渲染 |
+| 失败可见 | 失败文件需要展示具体原因，便于用户补传或修复 |
+| 可追溯 | 每份导出报告能关联到具体上传批次和会话 |
+
+---
+
+## 十、疑问点与待确认事项
+
+### 10.1 功能疑问
+
+| 序号 | 疑问内容 | 建议 | 状态 |
+| --- | --- | --- | --- |
+| 1 | “文件目录参考附件”尚未上传，无法确认标准目录样例 | 附件上传后补充目录样例和字段映射 | 待确认 |
+| 2 | 文件夹上传在浏览器端是否采用目录上传能力 | 前端可使用 webkitdirectory 或改为要求用户上传压缩包 | 待确认 |
+| 3 | 散装文件是否需要用户手动指定归属目录 | Demo 阶段统一归入“散装上传”目录 | 待确认 |
+
+### 10.2 业务规则疑问
+
+| 序号 | 疑问内容 | 建议 | 状态 |
+| --- | --- | --- | --- |
+| 1 | Excel 页数统计口径不明确 | Demo 阶段按工作表数量，正式版可按打印分页 | 待确认 |
+| 2 | doc/docx 页数是否必须与 Word 打开后的实际页数完全一致 | 建议通过转换 PDF 后统计，提高一致性 | 待确认 |
+| 3 | 是否需要按 NMPA 申报资料目录自动排序 | 本功能先按上传目录顺序，后续法规完整性检查再做标准目录匹配 | 待确认 |
+
+### 10.3 技术方案疑问
+
+| 序号 | 疑问内容 | 可选方案 | 状态 |
+| --- | --- | --- | --- |
+| 1 | Office 文档页数统计依赖 | LibreOffice 转 PDF、文档属性读取、商业 Office 自动化 | 待确认 |
+| 2 | 大文件处理模式 | 同步处理、后台任务、队列任务 | 待确认 |
+| 3 | Markdown 渲染方案 | 前端引入 Markdown 渲染库，或后端转换为安全 HTML | 待确认 |
+
+### 10.4 数据定义疑问
+
+| 序号 | 疑问内容 | 建议 | 状态 |
+| --- | --- | --- | --- |
+| 1 | 导出文件保存周期未明确 | Demo 阶段永久保存，正式版增加过期清理策略 | 待确认 |
+| 2 | 原始上传文件是否长期保留 | 建议至少保留到关联审核流程结束 | 待确认 |
+| 3 | 下载链接是否需要一次性或有效期控制 | 注册资料敏感，建议正式版增加有效期和权限校验 | 待确认 |
+
+---
+
+## 十一、验收标准
+
+| 序号 | 验收项 | 验收标准 |
+| --- | --- | --- |
+| 1 | 压缩包上传汇总 | 上传包含多层目录的压缩包后，系统能保留层级并统计支持文件页数 |
+| 2 | 散装文件上传汇总 | 上传多个散装文件后，系统能生成同一批次汇总结果 |
+| 3 | Markdown 展示 | AI 对话框能展示摘要表和文件简表，表格格式正常 |
+| 4 | 下载链接 | AI 回复中提供 Markdown 报告和 Excel 明细下载链接，点击可下载 |
+| 5 | 数据存档 | 数据库中能查询到批次记录、文件明细和导出文件记录 |
+| 6 | 异常不中断 | 单个文件失败时不影响其他文件统计，失败原因可见 |
+| 7 | 支持类型覆盖 | pdf、doc、docx、xls、xlsx、ppt、pptx 均能进入处理流程 |
+
+---
+
+## 十二、下一步建议
+
+1. 上传“文件目录参考附件”，补充标准目录样例和演示数据。
+2. 明确 Excel 页数统计口径，决定 Demo 版是否按工作表数量统计。
+3. 设计数据库表结构，包括汇总批次、文件明细、上传原始文件和导出文件。
+4. 改造 AI 对话框，增加附件上传、Markdown 渲染和下载链接展示能力。
+5. 实现文件扫描与页数统计服务，优先打通 pdf、docx、xlsx、pptx 的 Demo 流程。