# Documents 模块需求分析

## 1. 模块定位

`apps.documents` 是本题最关键的业务入口之一。对于“试剂盒临床注册文件准备与审核”场景，它不只是一个上传附件页面，而是：

> 注册申报资料治理中心

该模块需要承接从资料接收、文件识别、内容抽取、章节点归类、页数统计、入库索引到状态反馈的完整过程。

## 2. 业务目标

本模块需要支撑以下真实业务目标：

1. 接收注册申报资料包中的各类文件。
2. 建立每份文件的结构化档案。
3. 自动形成目录汇总和页数统计结果。
4. 为法规完整性核查和一致性核查提供可靠的文档底座。
5. 为抽取、回填、审计和导出提供统一的文档主数据。

结合新增公告材料，本模块还应承担“法规原文资料资产管理”的基础职责，即把上传的业务资料与平台内置的法规依据材料区分管理。

## 3. 为什么 Documents 模块是本题核心

题面第一条就要求“自动汇总注册申报文件夹中的所有文件及页数”，第二条要求“对照 NMPA 法规要求核查文件完整性”。这两个要求都建立在一个前提上：

系统必须先“看懂当前资料包里到底有什么”。

因此，Documents 模块不是配角，而是全流程的第一责任模块。

## 4. 核心职责

### 4.1 原始文件接收

支持上传和保存：

- PDF
- DOCX
- DOC
- MD
- TXT

必要时为后续 OCR 或图片扫描件预留扩展位。

结合题面“自动汇总文件夹文件目录与页数”的要求，Documents 模块还需要支持资料包级导入，而不是只支持单文件：

- 多文件批量上传
- 文件夹选择或拖拽上传
- 压缩包上传并自动解包

压缩包覆盖 `zip`、`rar`、`7z` 等常见格式。解包后应保留压缩包内的原始相对路径，并将多层目录按原目录作为章节点识别依据，用于还原资料目录、识别章节点和判断是否存在目录层级异常。

`rar`、`7z` 解压必须采用纯 Python 实现，允许新增第三方 Python 包依赖，避免服务器部署时依赖系统级解压工具。

除用户上传的申报资料外，系统还需要支持管理平台内置法规资料，例如：

- 注册申报资料要求及说明
- 批准证明文件格式要求
- 安全和性能基本原则清单
- 注册证 / 变更注册（备案）文件格式

### 4.2 文件基础信息管理

每份资料至少要记录：

- 文件 ID
- 原始文件名
- 文件类型
- 文件大小
- 上传时间
- 所属项目 / 批次
- 所属任务或场景
- 当前处理状态

对于法规资料，建议额外记录：

- 法规类型
- 法规流程类型
- 版本来源
- 是否为系统内置规则依据

### 4.3 页数统计与目录归属

系统要能为每份文件识别：

- 页数
- 章节归属
- 资料名称
- 是否匹配法规目录项

这部分是题面要求中的显式能力，不能只靠 Chat 页面临时回答。

### 4.4 文本与表格抽取

为后续规则比对和字段提取，需要抽取：

- 正文文本
- 标题层级
- 表格内容
- 可能的关键信息段落

例如 `目标产品说明书.docx` 中大量关键信息位于结构化段落和表格中，若只做粗暴全文提取，会显著影响抽取质量。

### 4.5 入库索引

对适合检索的内容建立索引，供 `agent_core` 的 RAG 或规则定位使用。

对法规原文资料，建议单独建立“法规知识索引”，切片时优先保留以下结构语义：

- 所属法规文档
- 适用流程类型
- 章 / 条 / 清单项编号
- 模板字段或格式要求类型

### 4.6 状态反馈与异常处理

文件处理流程要有明确状态，例如：

- 已上传
- 已解析
- 已入库
- 解析失败
- 待人工确认

不能只记录一个“成功 / 失败”。

## 5. 注册资料业务下的文件模型需求

### 5.1 现有上传模型的不足

当前 `UploadedDocument` 更像一个通用文档记录，适合简单 RAG Demo，但对本题不够。至少还缺少以下业务字段：

- `project_id` 或 `submission_batch_id`
- `chapter_code`
- `chapter_name`
- `document_code`
- `declared_document_name`
- `page_count`
- `source_version`
- `extraction_status`
- `index_status`
- `consistency_status`
- `completeness_match_status`

### 5.2 建议新增的业务语义字段

#### 5.2.1 章节点字段

需要支持类似：

- `CH1.2`
- `CH1.4`
- `CH1.5`
- `CH1.11.5`

这样系统才能把法规模板、样例目录和实际文件真正对齐。

#### 5.2.2 文档类别字段

例如：

- 监管信息
- 综述资料
- 非临床资料
- 临床评价资料
- 产品说明书和标签样稿
- 质量管理体系文件

#### 5.2.3 处理质量字段

建议记录：

- 是否成功提取文本
- 是否成功提取表格
- 是否页数统计可信
- 是否疑似扫描件
- 是否需要 OCR

这些字段会直接影响后续审核可信度。

#### 5.2.4 规则来源字段

建议增加：

- `source_role`
  区分“业务申报资料”与“法规依据资料”。

- `workflow_type`
  区分 `registration`、`change`、`renewal` 等流程类型。

- `format_template_type`
  标记该文件是否属于批准证明文件格式模板。

## 6. 关键业务流程需求

### 6.1 文件上传流程

用户上传文件后，系统应完成：

1. 基础校验：格式、大小、文件名合法性。
2. 保存原始文件。
3. 创建文档记录。
4. 返回上传结果与下一步动作提示。

如果是批量导入，系统还应支持一次性上传多个资料。

如果上传的是压缩包，流程应扩展为：

1. 保存原始压缩包。
2. 校验压缩包格式和大小。
3. 解包到当前项目 / 批次的隔离目录。
4. 遍历解包后的文件并创建文档记录。
5. 保留每个文件的原始相对路径和所属压缩包来源。
6. 对解包失败、空包、嵌套异常或不支持格式给出业务化提示。

### 6.2 文件识别与归类流程

上传后，系统应尽量自动识别文件属于哪个章节点。识别依据可以包括：

- 文件名中的章节点编码
- 标题中的资料名称
- 正文中出现的标准标题
- 用户手工选择的类别

如果自动识别不确定，应标记为“待人工确认”，而不是强行归类。

对于法规资料，还应进一步识别其所属层级，例如：

1. 资料要求说明
2. 格式要求说明
3. 安全和性能基本原则
4. 批准证明文件格式

### 6.3 页数统计流程

页数统计是本题显式要求，需支持：

- PDF 精确页数统计
- DOCX 精确页数统计
- DOC 文件页数统计或待人工复核策略
- 目录页码与实际文件页数比对

DOCX 页数必须精确，不能以估算页数作为 V1 验收结果。DOC 如受格式限制无法精确统计，应标记为“待人工复核”。

页数结果建议拆分为：

- `page_count`
- `page_count_method`
- `page_count_confidence`

例如 PDF 和 DOCX 解析应标记为“精确”，DOC 或解析失败文件可标记为“待人工复核”。

### 6.4 文本抽取与索引流程

系统应按文档类型采用不同策略：

- PDF：优先文本解析，必要时 OCR 兜底
- DOCX：提取段落和表格
- DOC：首版可使用兼容方式提取正文，异常时提醒
- MD/TXT：直接读取

抽取成功后，生成：

- 全文文本
- 标题/章节结构
- 表格结构
- 可供索引的切片

### 6.5 目录汇总输出流程

Documents 模块应能直接输出一份“资料目录总览”，字段建议包括：

- 文件名
- 资料名称
- 章节点
- 文件类型
- 页数
- 上传时间
- 处理状态
- 是否命中法规模板

这份目录总览既可作为页面列表，也可作为后续报告输入。

## 7. 与题面和样例资料的强关联需求

### 7.1 要能识别目录型文档

如 `CH1.2 监管信息目录.docx`，它本身不是普通资料正文，而是全章目录。系统需要把这类文件识别为“目录类文档”，并作为后续完整性比对的重要基准。

### 7.2 要能识别声明类文档

如：

- `CH1.11.1 符合标准的清单.docx`
- `CH1.11.5 真实性声明.docx`
- `CH1.11.6 符合性声明.docx`

这些文件看起来篇幅短，但在法规齐套性里往往是必需项，Documents 模块需要保留它们的业务属性，而不是简单按长度或内容量弱化其价值。

### 7.3 要能识别历史沟通说明类文档

`CH1.9 产品申报前沟通的说明.doc` 体现出历史申报背景和监管沟通信息，这类文件在合规审查中重要性很高，应单独分类标记。

### 7.4 要能区分业务资料与法规依据资料

结合新增公告材料，Documents 模块应把以下两类材料明确分开管理：

1. 待审核的业务申报资料
2. 用于审核的法规依据与模板资料

否则后续在索引、引用和一致性检查时，容易把法规模板错误混入业务资料集合。

## 8. 列表页与上传页需求

### 8.1 文档列表页需求

文档列表页不应只是“文件上传记录”，而应成为资料治理面板。建议展示：

- 文件名
- 原始相对路径
- 章节点
- 资料名称
- 页数
- 页数可信度
- 所属项目 / 批次
- 解析状态
- 入库状态
- 风险提示
- 最后更新时间

### 8.2 上传页需求

上传页应支持：

- 选择所属项目或申报批次
- 选择任务类型或章节点
- 上传单文件或多文件
- 上传后立即触发解析或稍后批量处理

如果首版只保留单文件上传，也应在需求中明确“后续需要支持批量导入资料包”。

## 9. 与其他模块的协作边界

### 9.1 与 Scenarios 模块

Scenarios 负责定义当前任务需要什么资料；Documents 负责把资料真正落地并结构化。

### 9.2 与 Agent Core 模块

Agent Core 负责对文档内容做审核与抽取；Documents 提供可靠的原始内容、切片和元数据。

### 9.3 与 Audit 模块

Documents 不负责审计结论，但应为审计提供文档 ID、处理过程和失败原因等基础事实。

## 10. 异常与边界情况

本模块必须考虑以下情况：

1. 文件存在但正文为空。
2. 文件格式伪装，例如后缀为 `.docx` 但内容异常。
3. Word / PDF 无法正常抽取文本。
4. 文件内容与文件名章节点不一致。
5. 同一资料重复上传多个版本。
6. 同一批次中混入其他产品资料。

第 6 点尤其重要，因为当前样例材料已经体现出不同产品信息混杂的问题。

此外，还应避免把法规依据资料误当成业务申报资料写入同一业务索引集合。

## 11. 首版建议的可交付结果

首版建议 Documents 模块至少能产出三类结果：

1. 文档主数据列表
2. 文档解析结果
3. 目录汇总表

其中目录汇总表是本题最关键的页面成果之一，建议作为可单独展示的功能输出。

## 12. 当前代码基线下的重构建议

### 12.1 可以保留的部分

- 上传记录模型的基本思路
- 文档列表与上传页的页面骨架
- 入库和失败提示机制

### 12.2 需要增强的部分

1. 从“文档上传记录”升级为“注册资料记录”。
2. 增加章节点、页数、资料名称、项目批次等字段。
3. 增加表格抽取和目录类文件识别。
4. 增加文档归类与页数统计能力。
5. 增加重复版本识别和疑似混档识别。
6. 增加法规资料类型识别与业务资料 / 法规资料隔离管理。
7. 增加资料包导入、压缩包解包、原始相对路径记录和解包异常提示。

## 13. 验收标准

本模块验收时，应至少满足：

1. 能上传并管理题目中涉及的 Word、PDF、文本类资料。
2. 能为每份资料建立结构化记录。
3. 能输出文件目录与页数汇总结果。
4. 能为后续完整性核查和一致性核查提供可靠输入。
5. 出现解析失败时，页面有明确可理解的错误提示。