# 资料包导入Skill 设计

## 1. Skill 定位

`资料包导入Skill` 是资料包导入工作流的总入口 Skill，负责把用户上传的文件集合转化为一个可处理的资料包批次，并协调解包、扫描、文档登记、页数统计、章节点识别和目录汇总。

它不直接处理法规完整性，不调用 LLM，不执行 RAG 入库。

英文实现标识建议使用 `SubmissionPackageImportSkill`，用于 Python 类名和 Tool Registry 注册处理器。

## 2. 触发场景

1. 用户在 Web 工作台上传单文件。
2. 用户批量上传多个文件。
3. 用户上传压缩包。
4. 飞书入口后续触发资料包导入任务。
5. 管理员导入平台内置法规资料。

## 3. 输入

```python
@dataclass
class SubmissionPackageImportInput:
    files: list[UploadedFileRef]
    batch_name: str
    workflow_type: str = "registration"
    source_role: str = "submission"
    created_by_id: int | None = None
    import_options: dict = field(default_factory=dict)
```

字段说明：

| 字段 | 说明 |
|---|---|
| `files` | 用户上传文件引用 |
| `batch_name` | 资料包批次名称 |
| `workflow_type` | 注册流程类型，V1 默认 `registration` |
| `source_role` | `submission` 或 `regulation` |
| `created_by_id` | 操作人 |
| `import_options` | 是否立即页数统计、是否跳过不支持文件等选项 |

## 4. 输出

```python
@dataclass
class SubmissionPackageImportOutput:
    batch_id: int
    batch_no: str
    status: str
    overview_report: dict
    warnings: list[dict]
    failed_items: list[dict]
```

## 5. 依赖 Skill

1. `压缩包解包Skill`
2. `资料包扫描Skill`
3. `文档页数统计Skill`
4. `章节点识别Skill`
5. `目录汇总Skill`

## 6. 核心方法

### 6.1 `run(input) -> SubmissionPackageImportOutput`

主入口方法。

执行顺序：

1. 创建 `SubmissionBatch`。
2. 保存上传文件到批次隔离目录。
3. 对压缩包调用 `压缩包解包Skill`。
4. 调用 `资料包扫描Skill` 扫描批次目录。
5. 创建 `RegistrationDocument` 记录。
6. 调用 `文档页数统计Skill`。
7. 调用 `章节点识别Skill`。
8. 调用 `目录汇总Skill`。
9. 更新批次状态。
10. 返回目录汇总结果。

### 6.2 `create_batch(input) -> SubmissionBatch`

创建资料包批次。

状态：

1. 初始为 `created`。
2. 文件保存开始后更新为 `importing`。
3. 汇总阶段更新为 `summarizing`。
4. 成功后更新为 `completed` 或 `partial_completed`。

### 6.3 `save_uploaded_files(batch, files) -> list[StoredUpload]`

保存原始上传文件，并记录上传文件来源。

安全要求：

1. 过滤路径穿越。
2. 原始文件名只用于展示。
3. 真实存储路径使用批次目录和安全文件名。

### 6.4 `create_document_records(batch, scanned_files) -> list[RegistrationDocument]`

把扫描结果落库为文档主数据。

落库字段：

1. `original_filename`
2. `relative_path`
3. `file_type`
4. `file_size`
5. `file_hash`
6. `source_archive_name`
7. `source_role`
8. `workflow_type`
9. `processing_status`

### 6.5 `finalize_batch_status(batch, overview_report) -> str`

根据结果决定批次状态。

规则：

1. 全部成功：`completed`
2. 存在待人工复核：`partial_completed`
3. 存在不支持文件但有有效文件：`partial_completed`
4. 无有效文件：`failed`

## 7. 技术实现

使用技术：

1. Django ORM
2. Django Storage
3. `pathlib`
4. `dataclasses` 或 Pydantic
5. Tool Registry

建议注册名：

```python
tool_registry.register(
    name="submission_package_import",
    handler=SubmissionPackageImportSkill().run,
)
```

## 8. 异常处理

| 异常 | 处理 |
|---|---|
| 上传文件为空 | 拒绝该文件，记录失败项 |
| 批次目录创建失败 | 整体失败 |
| 解包失败 | 批次部分失败或整体失败 |
| 无支持文件 | 批次失败 |
| 页数统计部分失败 | 批次部分完成 |
| 章节点识别失败 | 文档标记待人工确认 |

## 9. 测试要点

1. 单文件导入成功。
2. 多文件导入共用同一批次。
3. 压缩包导入保留相对路径。
4. 不支持文件不会阻断有效文件。
5. 部分失败时批次为 `partial_completed`。
6. 输出包含 `overview_report`。