# 风险与架构决策

## 1. 风险台账

| ID | 风险 | 影响 | 应对 |
|---|---|---|---|
| R-01 | 不同 Spine 版本二进制格式不兼容 | 错误预览或导入失败 | 五套匹配 Runtime；Editor 主/次版本强校验 |
| R-02 | 3.8 早期格式变化 | 部分 3.8 文件无法读取 | 正式范围从 3.8.20 开始；旧文件尽力识别 |
| R-03 | SKEL 不含可直接修改的图片路径 | 生成工程显示 Missing | Editor 双重导入/导出原型；输出布局降级方案 |
| R-04 | 五套 Runtime 符号/API 冲突 | 无法链接或运行不稳定 | 独立动态模块、隐藏符号、稳定 C ABI |
| R-05 | 损坏输入使 Runtime 崩溃 | 主程序退出 | 有界预检、模糊测试；必要时改 helper process |
| R-06 | Spine Launcher 缺少目标缓存版本 | 离线转换失败 | 版本能力预检；不自动下载；明确修复提示 |
| R-07 | Editor 自身的联网或授权行为 | 离线验收失败 | 真正断网测试；明确前置条件；不修改或绕过 Editor |
| R-08 | PMA/WebP 边缘错误 | 预览或解包出现色边 | 格式矩阵与 Alpha 视觉回归；Alpha 处理交给官方解包器 |
| R-09 | Polygon-packed Mesh 难以还原原图 | 图片包含邻近像素或裁切错误 | 仅使用官方解包器；失败时报告限制并终止 |
| R-10 | 官方测试素材误入安装包 | 许可与体积风险 | 打包白名单、哈希禁止清单、发行物解包检查 |
| R-11 | Qt/Runtime 许可遗漏 | 无法合规发行 | 依赖清单、licenses、About 页面、发行关卡 |
| R-12 | 自定义路径和 Unicode 处理错误 | Editor 无法启动 | 参数数组、canonical path、双平台路径测试 |
| R-13 | 巨大资源耗尽内存 | 卡死或崩溃 | 输入限制、预算检查、按需解码、可取消任务 |
| R-14 | 跨补丁 Editor 行为变化 | 同一主/次版本结果不同 | 记录实际补丁；固定测试矩阵；报告转换环境 |

## 2. 已接受架构决策

### ADR-001：生成 `.spine` 使用官方 Editor

- 状态：接受
- 决策：调用本地已授权 Spine Editor，不自行写 `.spine`。
- 原因：`.spine` 是编辑工程格式；官方 CLI 已提供数据导入能力。

### ADR-002：版本范围为 3.8.20+ 至 4.3

- 状态：接受
- 决策：3.8.20+、4.0、4.1、4.2、4.3；不支持 3.8 以下。
- 原因：覆盖目标游戏资源，同时控制旧格式维护成本。

### ADR-003：预览进入首版

- 状态：接受
- 决策：用户确认转换前必须可离线预览。
- 原因：避免批量生成后才发现配对、Scale、Alpha 或版本错误。

### ADR-004：每个主/次版本独立 Runtime

- 状态：接受
- 决策：五个 Runtime 插件，通过统一 C ABI 接入。
- 原因：官方要求 Runtime 与数据主/次版本同步，API 也会变化。

### ADR-005：仅使用官方 Atlas 解包

- 状态：接受
- 决策：官方 Texture Unpacker 是唯一纹理解包实现；失败时任务失败。
- 原因：官方对自身 Atlas、PMA、旋转和多边形打包语义最权威，且软件以前置正版 Spine 为使用条件。

### ADR-006：运行期全离线

- 状态：接受
- 决策：无 CDN、下载、遥测、资源上传和在线 API。
- 原因：资源敏感性、稳定性和用户要求。

### ADR-007：官方测试资源不发行

- 状态：接受
- 决策：官方资源只用于开发/CI，最终安装包不包含。
- 原因：用户明确要求，并减少许可与安装体积风险。

### ADR-008：Qt 6 + CMake + MSVC/Apple Clang

- 状态：接受
- 决策：主程序 C++20，CMake 3.25+，Windows MSVC v143。
- 原因：跨平台 UI、进程管理、图片插件和成熟构建生态。

## 3. 原型后待决策事项

### ADR-P01：Runtime 插件还是 helper process

默认先验证动态插件。若损坏文件可导致不可接受的进程级崩溃，则采用 helper process 隔离。

### ADR-P02：macOS 架构

首发 Apple Silicon 或 Universal 2，根据目标用户和五套 Runtime 构建成本决定。

### ADR-P03：测试框架

Qt Test 与 Catch2 二选一，以 Runtime 插件和参数化兼容矩阵的便利性为主要标准。

### ADR-P04：SKEL 图片路径自动化方案

由 Editor 双重导入/导出原型结果决定正式流程及是否存在可接受降级。

### ADR-P05：Windows 安装器

在 MSIX、WiX/MSI、Inno Setup 中选择，需满足离线安装、签名和干净卸载。

## 4. 决策变更规则

变更已接受决策时必须记录：

- 变更原因
- 新证据或测试结果
- 对范围、兼容性和许可的影响
- 数据迁移或设置迁移方案
- 负责人和日期