导出数据转spine
This commit is contained in:
tianmo
@@ -0,0 +1,217 @@
|
||||
# 系统架构
|
||||
|
||||
## 1. 技术基线
|
||||
|
||||
| 项目 | 选择 |
|
||||
|---|---|
|
||||
| 语言 | C++20（第三方 Runtime target 可使用其原生标准） |
|
||||
| UI | Qt 6 Widgets |
|
||||
| 预览画布 | `QOpenGLWidget` + 自研批次渲染器 |
|
||||
| 构建 | CMake 3.25+、CMake Presets |
|
||||
| Windows 编译器 | Visual Studio 2022 / MSVC v143 |
|
||||
| macOS 编译器 | Apple Clang |
|
||||
| 进程管理 | `QProcess` |
|
||||
| 设置存储 | `QSettings` |
|
||||
| JSON | Qt JSON |
|
||||
| 图片加载 | Qt Image plugins，随程序离线部署 |
|
||||
| 测试 | Qt Test 或 Catch2，原型结束时二选一 |
|
||||
|
||||
CMake 只用于开发构建，不是最终用户的运行依赖。Windows 可以使用 Visual Studio Generator 或 Ninja + MSVC。
|
||||
|
||||
## 2. 分层结构
|
||||
|
||||
```text
|
||||
UI
|
||||
├─ 资源组表格
|
||||
├─ 预览与播放控制
|
||||
├─ Editor 管理
|
||||
└─ 任务、日志与报告
|
||||
↓
|
||||
Application Services
|
||||
├─ ScanService
|
||||
├─ PreviewService
|
||||
├─ EditorRegistry
|
||||
├─ RecoveryCoordinator
|
||||
└─ ReportService
|
||||
↓
|
||||
Domain
|
||||
├─ AssetGroup
|
||||
├─ SpineVersion
|
||||
├─ EditorInstallation
|
||||
├─ RecoveryJob
|
||||
└─ RecoveryResult
|
||||
↓
|
||||
Infrastructure
|
||||
├─ Filesystem / Process
|
||||
├─ Runtime Plugin Host
|
||||
├─ Spine CLI Adapter
|
||||
├─ Atlas Unpackers
|
||||
└─ Output Publisher
|
||||
```
|
||||
|
||||
UI 只表达状态和用户意图，不能直接调用 Spine CLI 或解析 Atlas。
|
||||
|
||||
## 3. 建议目录
|
||||
|
||||
```text
|
||||
DateToSpine/
|
||||
CMakeLists.txt
|
||||
CMakePresets.json
|
||||
cmake/
|
||||
docs/
|
||||
licenses/
|
||||
resources/
|
||||
icons/
|
||||
shaders/
|
||||
translations/
|
||||
src/
|
||||
app/
|
||||
domain/
|
||||
scan/
|
||||
atlas/
|
||||
editor/
|
||||
preview/
|
||||
recovery/
|
||||
report/
|
||||
platform/
|
||||
macos/
|
||||
windows/
|
||||
ui/
|
||||
util/
|
||||
runtime-api/
|
||||
runtime-plugins/
|
||||
spine38/
|
||||
spine40/
|
||||
spine41/
|
||||
spine42/
|
||||
spine43/
|
||||
third_party/
|
||||
spine-runtimes/
|
||||
licenses/
|
||||
tests/
|
||||
unit/
|
||||
integration/
|
||||
compatibility/
|
||||
manifests/
|
||||
fixtures/
|
||||
generated/
|
||||
external/
|
||||
packaging/
|
||||
macos/
|
||||
windows/
|
||||
```
|
||||
|
||||
`tests/fixtures/external/` 用于本地准备的官方测试资源，不进入发行包。
|
||||
|
||||
## 4. 多版本 Runtime 隔离
|
||||
|
||||
五套 Runtime 不能直接链接进同一个主程序命名空间。每个版本编译成独立动态模块，并隐藏所有上游 C++ 符号，只导出稳定的 DateToSpine C ABI。
|
||||
|
||||
```text
|
||||
dts-runtime-3_8
|
||||
dts-runtime-4_0
|
||||
dts-runtime-4_1
|
||||
dts-runtime-4_2
|
||||
dts-runtime-4_3
|
||||
```
|
||||
|
||||
公共 ABI 只允许：
|
||||
|
||||
- 固定宽度整数
|
||||
- POD 结构体
|
||||
- UTF-8 字节串
|
||||
- 不透明句柄
|
||||
- 显式长度的数组
|
||||
- 函数指针回调
|
||||
|
||||
禁止跨模块传递 Qt 对象、STL 容器、异常或 Spine Runtime 类。
|
||||
|
||||
每个适配模块承担：
|
||||
|
||||
- 对应版本 JSON/SKEL 读取
|
||||
- Atlas 绑定
|
||||
- 动画状态推进
|
||||
- Skin/Animation 查询和切换
|
||||
- 把绘制结果转换为统一顶点、索引和 draw command
|
||||
- 把上游错误转换为统一错误码
|
||||
|
||||
## 5. 预览渲染边界
|
||||
|
||||
Runtime 插件负责骨骼计算和裁剪；主程序渲染器负责：
|
||||
|
||||
- 纹理创建和缓存
|
||||
- 顶点/索引上传
|
||||
- Shader
|
||||
- Blend mode
|
||||
- 相机、背景和调试覆盖层
|
||||
- DPI 和窗口生命周期
|
||||
|
||||
Runtime 不直接创建 Qt 或 OpenGL 对象。这使 Runtime 适配可独立测试，也避免上下文所有权问题。
|
||||
|
||||
## 6. Spine CLI 边界
|
||||
|
||||
所有 Editor 调用必须经过 `ISpineCli`：
|
||||
|
||||
```text
|
||||
probe installation
|
||||
probe version
|
||||
import data
|
||||
export normalized json
|
||||
unpack atlas
|
||||
inspect project
|
||||
```
|
||||
|
||||
实现要求：
|
||||
|
||||
- 使用 `QProcess::setProgram` 和 `setArguments`。
|
||||
- 不经过 shell。
|
||||
- 每次调用有超时、取消令牌、工作目录和独立日志。
|
||||
- 只终止本软件启动的子进程。
|
||||
- 对 Windows 优先选择 `Spine.com`。
|
||||
- 对 macOS 把 `.app` 规范化为内部可执行文件。
|
||||
|
||||
## 7. 任务并发
|
||||
|
||||
- 扫描、哈希、图片头校验可以在线程池执行。
|
||||
- OpenGL 资源操作只在所属渲染线程执行。
|
||||
- Spine Editor 调用默认全局串行。
|
||||
- Spine 官方 Atlas 解包与工程导入全局串行，并受任务取消状态约束。
|
||||
- 每个恢复任务有独立临时目录和取消状态。
|
||||
|
||||
## 8. 文件长度和复杂度约束
|
||||
|
||||
自研代码执行以下软上限，超过时必须在评审中说明或拆分：
|
||||
|
||||
| 文件类型 | 建议上限 |
|
||||
|---|---:|
|
||||
| 头文件 | 200 行 |
|
||||
| 普通 `.cpp` | 350 行 |
|
||||
| UI `.cpp` | 450 行 |
|
||||
| 单元测试文件 | 500 行 |
|
||||
|
||||
同时执行：
|
||||
|
||||
- 一个类只有一个主要职责。
|
||||
- `MainWindow` 不包含解析、转换和进程逻辑。
|
||||
- 禁止无边界的 `Utils` 类。
|
||||
- 平台代码不得散落到业务模块。
|
||||
- 版本差异留在 Runtime adapter 和 version policy 中。
|
||||
- 第三方上游源码保持原样，位于 `third_party/`，不纳入自研文件行数限制。
|
||||
|
||||
CI 将检查自研源文件行数、循环依赖和禁止目录引用。
|
||||
|
||||
## 9. 可测试性
|
||||
|
||||
核心依赖使用小接口注入：
|
||||
|
||||
```text
|
||||
IFileSystem
|
||||
IProcessRunner
|
||||
ISpineCli
|
||||
IRuntimePlugin
|
||||
IAtlasUnpacker
|
||||
IClock
|
||||
IReportSink
|
||||
```
|
||||
|
||||
单元测试不启动真实 Editor；集成和兼容测试才调用本地 Spine Editor。
|
||||
Reference in New Issue
Block a user