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

docs/详细设计/skill/目录汇总Skill.md

@@ -0,0 +1,185 @@
+# 目录汇总Skill 设计
+
+## 1. Skill 定位
+
+`目录汇总Skill` 负责把一个资料包批次中的文档主数据聚合为目录汇总报告。它是第一步“资料包导入与目录汇总”的最终输出 Skill。
+
+本 Skill 不重新扫描文件，不重新统计页数，只消费已经落库或已处理的文档事实。
+
+英文实现标识建议使用 `DirectorySummarySkill`，用于 Python 类名和 Tool Registry 注册处理器。
+
+## 2. 输入
+
+```python
+@dataclass
+class DirectorySummaryInput:
+    batch_id: int
+    include_unsupported: bool = true
+    include_warnings: bool = true
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RegistrationOverviewReport:
+    batch_id: int
+    batch_no: str
+    workflow_type: str
+    source_role: str
+    file_count: int
+    supported_file_count: int
+    unsupported_file_count: int
+    failed_file_count: int
+    manual_review_count: int
+    total_page_count: int
+    page_count_status: str
+    chapter_summary: list[dict]
+    documents: list[dict]
+    warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> RegistrationOverviewReport`
+
+主入口方法。
+
+执行顺序：
+
+1. 读取批次信息。
+2. 读取该批次所有文档记录。
+3. 计算总文件数。
+4. 计算支持文件、不支持文件、失败文件和待复核文件数量。
+5. 汇总页数。
+6. 按章节点聚合。
+7. 生成文档明细。
+8. 生成导入警告。
+9. 返回结构化报告。
+
+### 4.2 `summarize_counts(documents) -> dict`
+
+计算：
+
+1. `file_count`
+2. `supported_file_count`
+3. `unsupported_file_count`
+4. `failed_file_count`
+5. `manual_review_count`
+
+### 4.3 `summarize_pages(documents) -> dict`
+
+计算：
+
+1. `total_page_count`
+2. `exact_page_count`
+3. `manual_review_page_count`
+4. `page_count_status`
+
+`page_count_status` 规则：
+
+1. 全部精确：`exact`
+2. 部分待复核：`partial_review_required`
+3. 全部无法统计：`manual_review_required`
+
+### 4.4 `summarize_chapters(documents) -> list[dict]`
+
+按 `chapter_code` 聚合：
+
+1. 文件数。
+2. 页数。
+3. 待复核数。
+4. 主要资料角色。
+
+无章节点的文件归入 `unclassified`。
+
+### 4.5 `build_document_rows(documents) -> list[dict]`
+
+生成页面明细。
+
+字段：
+
+1. `document_id`
+2. `relative_path`
+3. `original_filename`
+4. `file_type`
+5. `page_count`
+6. `page_count_confidence`
+7. `chapter_code`
+8. `chapter_name`
+9. `document_role`
+10. `processing_status`
+11. `needs_manual_review`
+
+### 4.6 `build_warnings(documents) -> list[dict]`
+
+生成业务化提示。
+
+提示类型：
+
+1. `unsupported_file`
+2. `page_count_review_required`
+3. `chapter_unclassified`
+4. `file_type_mismatch`
+5. `duplicate_file`
+6. `archive_extract_warning`
+
+## 5. 技术实现
+
+使用技术：
+
+1. Django ORM 聚合查询
+2. Python dataclass 或 Pydantic
+3. JSONField 存储报告快照
+
+建议注册名：
+
+```python
+tool_registry.register(
+    name="build_directory_summary",
+    handler=DirectorySummarySkill().run,
+)
+```
+
+## 6. 报告存储
+
+建议将目录汇总报告快照写入批次模型或独立模型：
+
+```python
+class SubmissionBatchSummary(models.Model):
+    batch = models.OneToOneField(SubmissionBatch, on_delete=models.CASCADE)
+    report_type = models.CharField(max_length=64, default="registration_overview_report")
+    report_json = models.JSONField(default=dict)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+```
+
+## 7. 与页面接口
+
+Documents 页面直接消费 `RegistrationOverviewReport`：
+
+1. 顶部显示统计卡片。
+2. 中部显示按章节点聚合表。
+3. 底部显示文件明细。
+4. 侧边显示待人工复核提示。
+
+## 8. 与后续 Agent Core 接口
+
+法规完整性核查从本报告读取：
+
+1. `batch_id`
+2. `documents`
+3. `chapter_summary`
+4. `manual_review_count`
+5. `warnings`
+
+如果 `manual_review_count > 0`，后续完整性核查仍可执行，但最终报告应标记“存在资料处理不确定性”。
+
+## 9. 测试要点
+
+1. 空批次返回合理空报告。
+2. 多章节点文件能正确聚合。
+3. 页数合计只统计有明确页数的文档。
+4. 待复核文件数量正确。
+5. 不支持文件可选展示。
+6. 输出 schema 字段稳定。