DEMO-AGENT/docs/详细设计/skill/资料包导入Skill.md

资料包导入Skill 设计

1. Skill 定位

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

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

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

2. 触发场景

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

3. 输入

@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. 输出

@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

建议注册名：

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

8. 异常处理

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

9. 测试要点

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