# 恢复流水线

## 1. 状态机

```text
Discovered
  → Grouped
  → PreflightPassed
  → PreviewReady
  → UserConfirmed
  → EditorVerified
  → AtlasUnpacked
  → ProjectImported
  → ProjectVerified
  → Published
```

任一步骤失败进入 `Failed(stage, code, details)`。取消进入 `Cancelled`。失败与取消不能发布半成品。

## 2. 资源组

一个 `AssetGroup` 包含：

```text
id
skeletonDataPath
skeletonFormat
detectedVersion
atlasPath
atlasPages[]
candidateScore
scale
alphaMode
warnings[]
```

Atlas 页面名是纹理配对的权威来源。文件前缀只作为寻找数据与 Atlas 关系的辅助信号。

## 3. 预检

转换前检查：

- 数据格式和版本
- 版本是否在支持范围
- Atlas 基础语法
- 所有页面是否存在
- 图片解码和尺寸
- Atlas scale/PMA
- 输出命名冲突
- 目标 Editor 可用性
- 临时目录和输出目录可写性
- 磁盘空间粗略估计

预检不修改输入。

## 4. 用户确认边界

预览阶段不得生成正式 `.spine`。允许的临时操作仅包括：

- Runtime 加载
- 图片解码
- 静态校验
- Editor 只读版本探测

只有用户点击“开始转换”后，才能调用导入和解包命令。

## 5. 临时工作区

```text
job-<uuid>/
  source-links/
  normalized/
  unpacked-images/
  intermediate/
  logs/
  publish/
```

- 优先使用复制或只读访问，不能修改源文件。
- 是否允许安全硬链接作为优化，在跨平台验证后决定。
- 每个任务独立，名称使用内部 UUID，避免用户文件名注入路径。

## 6. Atlas 解包

1. 只调用匹配版本 Spine Editor 的官方 Texture Unpacker。
2. 校验页面、region 数量、输出尺寸和文件存在性。
3. 官方失败或验证失败时终止任务并显示原因，不使用其他解包实现。
4. 原始 `.atlas` 和打包纹理页只作为只读输入，不复制到最终结果。
5. 工程导入必须读取 Atlas 的 `scale` 并使用 `-s <数值>`，使骨骼与官方解包图片采用相同打包比例。

详细规则见 `06-图集解包设计.md`。

## 7. JSON 输入工程生成

1. 复制 JSON 到临时目录。
2. 保留所有未知字段。
3. 仅在必要时更新临时副本中的 `skeleton.images` 相对路径。
4. 使用匹配主/次版本的 Editor 导入。
5. 输出临时 `.spine`。
6. 使用 Editor info 或再次导出执行语义验证。

禁止修改源 JSON。

## 8. SKEL 输入工程生成

SKEL 的图片路径自动关联是技术原型重点。候选官方流程：

1. 匹配版本 Editor 把 SKEL 导入临时 `.spine`。
2. Editor 从临时工程导出规范化 JSON。
3. 在规范化 JSON 临时副本中设置 `skeleton.images`。
4. 匹配版本 Editor 再导入为最终候选 `.spine`。
5. 比较初次导入、规范化 JSON 和最终工程的语义计数。

此流程避免自行解析并序列化全部 SKEL，也避免修改未公开的 `.spine` 格式。

原型必须验证：

- 默认 JSON 导出是否保留全部运行时语义。
- 动画曲线、Deform、Linked Mesh、约束和事件是否无损。
- 图片相对路径是否被最终 `.spine` 保存。
- 3.8—4.3 是否行为一致。

若某版本失败，保留“工程 + images 目录 + 首次打开路径提示”作为降级方案，但正式自动化验收前必须由产品方确认是否接受。

## 9. Scale 与 Alpha

- Atlas 显式 `scale` 优先。
- 数据和 Atlas 都没有足够信息时，不猜测为确定值。
- 可提供 1、0.5、0.25 等候选并让用户预览比较。
- 用户可通过底部“去除预乘 Alpha”开关决定是否将解包图片转换为 Straight Alpha。
- 为保证各版本行为一致，官方解包使用临时 Atlas 副本并关闭其自动去预乘；开关开启后由本地像素处理统一完成转换。
- 临时 Atlas 不修改源文件，也不进入最终结果。

## 10. 结果验证

### 10.1 文件级

- `.spine` 存在且非空。
- 所有预期图片存在且可解码。
- 输出路径不逃逸目标目录。
- 临时文件未混入正式结果。

### 10.2 语义级

至少比较：

- 骨骼数和名称
- Slot 数和名称
- Skin 数和名称
- Attachment 类型与数量
- 约束类型与数量
- Animation 名称、数量和时长
- Event 名称和数量
- Deform timeline 存在性

Nonessential 缺失作为恢复等级，不作为运行时语义失败。

### 10.3 可读性

- 使用匹配 Editor 重新读取生成项目。
- 捕获所有 warning/error。
- 版本不匹配警告视为失败，除非用户启用实验模式。

## 11. 原子发布

验证通过后：

1. 在输出目录同一文件系统创建候选目录。
2. 应用重名策略。
3. 一次性重命名为正式结果。
4. 覆盖时先备份或移入可恢复位置。
5. 发布失败保留诊断，但不留下伪成功目录。

## 12. 输出结构

```text
Output/
  hero/
    hero.spine
    images/
      body.png
      face/
        eye.png
```

当前简化产品不输出原始 Atlas、打包纹理页、日志或恢复报告。发生错误时直接弹窗给出失败阶段和 Spine 输出摘要；成功时弹窗显示完整输出目录。