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

docs/详细设计/skill/资料包扫描Skill.md

@@ -0,0 +1,127 @@
+# 资料包扫描Skill 设计
+
+## 1. Skill 定位
+
+`资料包扫描Skill` 负责扫描资料包根目录，生成后续文档登记、页数统计和章节点识别所需的文件清单。
+
+它处理的是文件系统事实，不读取文档正文，不做页数统计。
+
+英文实现标识建议使用 `PackageFileScanSkill`，用于 Python 类名和 Tool Registry 注册处理器。
+
+## 2. 输入
+
+```python
+@dataclass
+class PackageFileScanInput:
+    root_dir: Path
+    batch_id: int
+    source_role: str = "submission"
+    allowed_extensions: set[str] = field(default_factory=set)
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class PackageFileScanOutput:
+    scanned_files: list[ScannedFile]
+    unsupported_files: list[ScannedFile]
+    skipped_files: list[SkippedFile]
+    warnings: list[dict]
+```
+
+`ScannedFile` 字段：
+
+1. `absolute_path`
+2. `relative_path`
+3. `original_filename`
+4. `extension`
+5. `file_size`
+6. `file_hash`
+7. `source_role`
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> PackageFileScanOutput`
+
+主入口方法。
+
+执行顺序：
+
+1. 遍历根目录。
+2. 过滤目录和临时文件。
+3. 识别文件类型。
+4. 生成文件大小和哈希。
+5. 区分支持文件、不支持文件和跳过文件。
+6. 返回扫描结果。
+
+### 4.2 `iter_files(root_dir) -> Iterator[Path]`
+
+使用 `pathlib.Path.rglob("*")` 遍历文件。
+
+### 4.3 `should_skip(path) -> bool`
+
+跳过规则：
+
+1. `.DS_Store`
+2. `Thumbs.db`
+3. `__MACOSX`
+4. Office 临时文件 `~$*.docx`
+5. 空文件
+
+### 4.4 `is_supported_document(path) -> bool`
+
+支持类型：
+
+1. `pdf`
+2. `docx`
+3. `doc`
+4. `txt`
+5. `md`
+
+压缩包在本 Skill 中不再进入支持文档列表，应由导入入口先交给 `压缩包解包Skill`。
+
+### 4.5 `build_relative_path(root_dir, path) -> str`
+
+生成统一的相对路径，使用 `/` 作为内部存储分隔符。
+
+### 4.6 `build_file_hash(path) -> str`
+
+使用 `sha256`。
+
+## 5. 技术实现
+
+使用技术：
+
+1. `pathlib`
+2. `hashlib`
+3. `mimetypes`
+4. 可选 `python-magic`
+
+## 6. 输出用途
+
+扫描结果用于：
+
+1. 创建 `RegistrationDocument`。
+2. 保留资料包原始目录结构。
+3. 识别重复文件。
+4. 后续章节点识别。
+5. 页面展示不支持文件提示。
+
+## 7. 异常处理
+
+| 异常 | 处理 |
+|---|---|
+| 根目录不存在 | 返回失败 |
+| 文件读取失败 | 加入 `skipped_files` |
+| 文件为空 | 加入 `skipped_files` |
+| 类型不支持 | 加入 `unsupported_files` |
+| 哈希计算失败 | 保留文件记录，标记警告 |
+
+## 8. 测试要点
+
+1. 多层目录扫描后相对路径正确。
+2. Office 临时文件被跳过。
+3. 不支持文件进入 `unsupported_files`。
+4. 支持文件进入 `scanned_files`。
+5. 哈希对同一文件稳定。