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

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

@@ -0,0 +1,168 @@
+# 资料包导入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`。