# DateToSpine 开发文档

## 文档状态

- 状态：技术原型开发中，极简主界面已形成
- 文档基线：2026-09-07
- 当前目录包含设计文档、C++/Qt 工程、Runtime 适配器和自动测试

## 产品概述

DateToSpine 是一个面向 macOS 和 Windows 的离线桌面工具，用于扫描、预览并批量恢复 Spine 游戏运行时资源：

```text
.skel/.json + .atlas/.atlas.txt + texture pages
                              ↓
                    可编辑的 .spine 工程
```

软件内置匹配版本的官方 `spine-cpp` Runtime 以实现转换前预览。生成 `.spine` 时，用户电脑必须已经安装、激活并准备好与资源版本匹配的 Spine Editor。

## 已确认的产品决策

1. 正式支持 Spine `3.8.20+`、`4.0.x`、`4.1.x`、`4.2.x`、`4.3.x`。
2. 不支持 Spine 3.8 以下版本。
3. 转换前必须支持离线预览，用户确认后才生成 `.spine`。
4. 五个 Spine 主/次版本使用各自对应的官方 Runtime。
5. 生成 `.spine` 必须调用本地已授权的 Spine Editor，不自行编写或逆向 `.spine` 文件。
6. Atlas 纹理只使用 Spine 官方 Texture Unpacker 解包，不提供自研兜底。
7. 软件运行期不使用 CDN、在线 API、在线依赖下载、遥测或资源上传。
8. 官方测试资源仅用于开发和 CI 测试，不进入最终安装包。
9. 最终安装包只携带 Runtime 许可、第三方许可和必要声明，不携带 Spine Editor 或官方示例资源。
10. 自研源文件按职责拆分，禁止出现数千行的业务代码文件。
11. 主界面只保留拖入资源、预览/动画切换和一键转换；仅在 Editor 自动识别失败时请求路径。

## 文档索引

- [01-产品需求.md](01-产品需求.md)：产品范围、用户流程和验收标准
- [02-系统架构.md](02-系统架构.md)：技术架构、模块边界和代码约束
- [03-版本识别与编辑器检测.md](03-版本识别与编辑器检测.md)：版本识别、本地 Editor 检测和自定义路径
- [04-恢复流水线.md](04-恢复流水线.md)：恢复流水线、输出规则和错误处理
- [05-离线预览器.md](05-离线预览器.md)：多版本 Runtime 与离线预览器
- [06-图集解包设计.md](06-图集解包设计.md)：官方唯一解包、PMA 与 Atlas Scale 设计
- [07-测试策略.md](07-测试策略.md)：测试矩阵、官方测试资源管理和验收
- [08-离线打包与许可.md](08-离线打包与许可.md)：离线、发行与许可要求
- [09-开发计划.md](09-开发计划.md)：阶段计划、技术关卡与完成定义
- [10-风险与架构决策.md](10-风险与架构决策.md)：风险台账与架构决策记录
- [11-阶段0技术原型记录.md](11-阶段0技术原型记录.md)：首批代码、构建证据和后续关卡
- [12-极简界面阶段记录.md](12-极简界面阶段记录.md)：精简后的界面范围、当前产出与未完成项
- [13-四点三动画预览记录.md](13-四点三动画预览记录.md)：4.3 真实骨骼绘制、动画切换和测试证据
- [14-离线转换与多版本回归记录.md](14-离线转换与多版本回归记录.md)：本地版本门禁、完整输出、PMA 开关和 3.8—4.3 回归证据

## 官方参考资料

- [Spine Command Line Interface](https://en.esotericsoftware.com/spine-command-line-interface)
- [Importing skeleton data](https://esotericsoftware.com/blog/Importing-skeleton-data)
- [Spine versioning](https://esotericsoftware.com/spine-versioning)
- [spine-cpp Runtime Documentation](https://esotericsoftware.com/spine-cpp)
- [Spine JSON format](https://esotericsoftware.com/spine-json-format)
- [Spine binary format](https://esotericsoftware.com/spine-binary-format)
- [Spine Runtimes repository](https://github.com/EsotericSoftware/spine-runtimes)
- [Spine Runtimes License](https://esotericsoftware.com/spine-runtimes-license)