187 lines
5.0 KiB
Markdown
187 lines
5.0 KiB
Markdown
# 恢复流水线
|
|
|
|
## 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 输出摘要；成功时弹窗显示完整输出目录。
|