导出数据转spine

DateToSpine/docs/06-图集解包设计.md

@@ -0,0 +1,67 @@
+# Atlas 官方解包设计
+
+## 1. 唯一实现
+
+纹理恢复只调用用户本机、已授权且与数据版本匹配的 Spine Editor Texture Unpacker。项目不实现 Atlas 裁切、旋转、透明边恢复或图片重采样，也不存在自研兼容解包路径。
+
+```text
+本地匹配版本 Spine Texture Unpacker
+                 ↓
+             输出校验
+                 ↓
+       失败并向用户显示具体原因
+```
+
+官方解包失败、输出缺失或校验失败时，任务直接失败，不尝试以另一套图片算法生成看似成功的结果。
+
+## 2. 官方调用
+
+```text
+Spine -u <本地精确缓存版本>
+      -i <Atlas 纹理页目录>
+      -o <临时 images 目录>
+      -c <Atlas 文件>
+```
+
+- 只允许精确的本地缓存版本，禁止 `latest`、通配版本和强制下载参数。
+- 原始 Atlas 与纹理页保持只读。
+- 输出先写入任务临时目录，验证成功后再发布。
+- 记录退出码与进程输出；成功退出后仍检查是否实际生成图片。
+- 最终结果不复制原始 `.atlas` 和打包纹理页。
+
+## 3. PMA 处理
+
+PMA 转换同样交给官方 Texture Unpacker：
+
+- 开启“去除预乘 Alpha”时，原样传入源 Atlas，由 Spine 根据 `pma: true` 执行官方转换。
+- 关闭时，仅建立临时 Atlas 元数据副本并把 `pma: true` 改为 `pma: false`，使官方解包器保留打包像素。
+- 不再由 Qt 解码、逐像素处理或重新保存解包图片，避免 JPEG/WebP 二次有损编码以及错误的重复去预乘。
+
+## 4. Atlas Scale 与工程导入
+
+Texture Unpacker 输出的是 Atlas 实际打包尺寸。例如页面声明 `scale: 0.5` 时，解出的图片也是原图的一半像素尺寸，这不是压缩错误。
+
+生成工程时必须把同一 Atlas 传给官方导入参数：
+
+```text
+Spine -u <本地精确缓存版本>
+      -i <骨骼 JSON 或 SKEL>
+      -s <Atlas 的 scale 数值>
+      -o <目标 .spine>
+      --import
+```
+
+`-s <数值>` 让 Editor 按 Atlas 的打包比例缩放骨骼、附件和动画数据。使用数值是为了兼容 3.8—4.3；旧版 Editor 不接受 Atlas 路径作为 `-s` 的值。遗漏此参数会形成“附件位置沿用原始坐标、解包图片却是半尺寸”的工程，表现为局部图片缩小和脱节。
+
+多页 Atlas 必须使用一致的 `scale`；未声明时按 `1.0`。若各页比例不同，任务会说明原因并停止，避免生成内部尺寸不一致的工程。
+
+## 5. 验证与失败规则
+
+每次解包后至少检查：
+
+- 进程正常结束。
+- `images/` 中存在可识别的图片输出。
+- 最终 `.spine` 文件存在且非空。
+- 3.8、4.0、4.1、4.2、4.3 均使用对应版本 Editor 做导入回归。
+
+任何一步失败都弹窗显示所属阶段和 Spine 返回的原因，不切换到非官方实现。