186 lines
4.1 KiB
Markdown
186 lines
4.1 KiB
Markdown
# 目录汇总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 字段稳定。
|