docs(详细设计): 新增资料包导入与目录汇总设计

docs/详细设计/skill/文档页数统计Skill.md

@@ -0,0 +1,126 @@
+# 文档页数统计Skill 设计
+
+## 1. Skill 定位
+
+`文档页数统计Skill` 负责为注册申报资料文件生成页数统计结果。页数是题面明确要求的关键指标，因此本 Skill 必须把页数、统计方法和可信度分开记录。
+
+本 Skill 不负责文档正文抽取，不负责 OCR，不负责合规判断。
+
+英文实现标识建议使用 `DocumentPageCountSkill`，用于 Python 类名和 Tool Registry 注册处理器。
+
+## 2. 输入
+
+```python
+@dataclass
+class DocumentPageCountInput:
+    document_id: int
+    file_path: Path
+    file_type: str
+    options: dict = field(default_factory=dict)
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class PageCountResult:
+    document_id: int
+    page_count: int | None
+    method: str
+    confidence: str
+    status: str
+    message: str = ""
+```
+
+## 4. 页数统计策略
+
+| 文件类型 | 策略 | 可信度 |
+|---|---|---|
+| `pdf` | 使用 `pypdf` 或 `PyMuPDF` 读取页数 | `exact` |
+| `docx` | 优先读取 Word 统计信息，必要时转换 PDF 后统计 | `exact` |
+| `doc` | 尝试转换后统计，失败则待复核 | `manual_review_required` |
+| `txt` | 页数不适用 | `not_applicable` |
+| `md` | 页数不适用 | `not_applicable` |
+
+DOCX 是 V1 验收重点，不能用字数、段落数或估算分页代替精确页数。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> PageCountResult`
+
+根据文件类型路由到具体统计方法。
+
+### 5.2 `count_pdf_pages(path) -> PageCountResult`
+
+推荐使用 `pypdf` 或 `PyMuPDF`。
+
+失败处理：
+
+1. 文件损坏：`failed`
+2. 加密 PDF：`manual_review_required`
+3. 无法读取：`failed`
+
+### 5.3 `count_docx_pages(path) -> PageCountResult`
+
+DOCX 精确页数建议采用两级策略：
+
+1. 读取文档内部统计属性中的页数。
+2. 若统计属性不可用，使用 LibreOffice headless 转 PDF，再统计 PDF 页数。
+
+如果两级策略均失败，输出 `manual_review_required`，并在页面突出显示。
+
+### 5.4 `count_doc_pages(path) -> PageCountResult`
+
+DOC 文件首版策略：
+
+1. 尝试用兼容转换工具转 PDF。
+2. 转换成功后统计 PDF 页数。
+3. 转换失败则标记待人工复核。
+
+### 5.5 `count_text_pages(path) -> PageCountResult`
+
+TXT/MD 首版不做页数强制验收。
+
+返回：
+
+1. `page_count = None`
+2. `method = "not_applicable"`
+3. `confidence = "not_applicable"`
+
+## 6. 技术实现
+
+建议依赖：
+
+1. `pypdf`
+2. `PyMuPDF`
+3. `python-docx`
+4. LibreOffice headless，可作为增强能力
+
+如果 V1 Docker 环境暂不内置 LibreOffice，应在配置中显式标注 `DOCX_PAGE_COUNT_STRATEGY`，并保证演示样本能通过已实现策略得到精确页数。
+
+## 7. 状态设计
+
+| 状态 | 含义 |
+|---|---|
+| `success` | 页数统计成功 |
+| `not_applicable` | 文本类文件不适用 |
+| `manual_review_required` | 需要人工复核 |
+| `failed` | 统计失败 |
+
+## 8. 落库字段
+
+建议写入 `RegistrationDocument`：
+
+1. `page_count`
+2. `page_count_method`
+3. `page_count_confidence`
+4. `page_count_status`
+5. `processing_message`
+
+## 9. 测试要点
+
+1. PDF 返回精确页数。
+2. DOCX 返回精确页数。
+3. DOC 无法统计时标记待人工复核。
+4. TXT/MD 返回不适用。
+5. 损坏文件返回失败状态。