# 目录汇总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 字段稳定。