SpineParticlesWeb/DateToSpine/docs/04-恢复流水线.md

恢复流水线

1. 状态机

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

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

2. 资源组

一个 AssetGroup 包含：

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

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

3. 预检

转换前检查：

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

预检不修改输入。

4. 用户确认边界

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

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

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

5. 临时工作区

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. 输出结构

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

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