XCEngine/docs/plan/target-architecture.md

# XCEngine 重构计划

## 1. 目标

这份计划用于定义 XCEngine 当前一轮重构的执行顺序和架构边界。

本轮重构的目标是：

- 在代码和构建层面拆开 runtime、pipeline、shared 三类职责
- 在拆分过程中保持 editor 日常迭代路径稳定
- 先理顺依赖和 API，再做物理目录调整
- 每个阶段结束后都执行一次 `XCEditor` 编译和 12 秒冒烟测试

## 2. 本轮范围

这份计划描述的是当前引擎重构阶段，不是最终交付产物布局。

当前阶段的项目侧数据根目录是：

- `project/Assets`
- `project/Settings`
- `project/Library`

当前阶段的基本要求是：

- editor 日常迭代继续基于现有项目工作流
- import、cache、rebuild 等职责逐步从 runtime 侧 API 中拆出去
- 顶层 `editor` 目录结构在前几个阶段保持稳定
- 物理目录调整放到依赖边界稳定之后再做

打包输出路径和产物布局放到单独的交付阶段再定义。

## 3. 架构规则

### 3.1 阶段划分

代码库按执行阶段拆分为：

- `engine/foundation`：基础设施层
- `engine/shared`：跨阶段稳定契约层
- `engine/runtime`：运行时系统
- `pipeline`：导入、构建、烘焙系统
- `editor`：当前编辑器应用树
- `programs`：各类可执行入口

### 3.2 依赖方向

目标依赖关系收敛为：

```text
foundation
  ^
  |
shared
  ^        ^
  |        |
runtime   pipeline
  ^        ^
  |        |
  +--------editor

programs -> runtime / pipeline
```

约束如下：

- `runtime` 只向下依赖 `foundation` 和 `shared`
- `pipeline` 只向下依赖 `foundation` 和 `shared`
- `editor` 负责编排 runtime 和 pipeline
- `shared` 只保留稳定数据契约

### 3.3 项目数据职责

当前阶段的项目侧数据职责为：

- `project/Assets`：源资源
- `project/Settings`：项目配置
- `project/Library`：导入缓存、中间产物、索引、日志、脚本编译输出

`Library` 归 pipeline 侧职责管理。
runtime 可以消费现有工作流准备好的资源数据，但 import 和 build 编排必须继续往 pipeline 侧收拢。

## 4. 目标目录结构

```text
XCEngine/
  CMakeLists.txt
  cmake/
  engine/
    foundation/
      base/
      containers/
      memory/
      threading/
      diagnostics/
      filesystem/
      math/
      serialization/
    shared/
      asset/
        AssetRef/
        LocalID/
        ResourceType/
        CatalogFormat/
        PackageFormat/
      cooked/
        CompiledTexture/
        CompiledMaterial/
        CompiledShader/
        CompiledModel/
        CompiledUIDocument/
        CompiledVolume/
        CompiledGaussianSplat/
    runtime/
      platform/
      asset/
        AssetManager/
        ResourceStore/
        AsyncLoad/
        Catalog/
        Package/
        CookedReaders/
      resources/
        Texture/
        Mesh/
        Material/
        Shader/
        Model/
        UI/
        Volume/
        GaussianSplat/
      scene/
      rendering/
        core/
        passes/
        pipelines/
        frame_graph/
        gpu_cache/
      audio/
      physics/
      scripting/
  pipeline/
    core/
      SourceAssetDB/
      ArtifactDB/
      SourceIndex/
      DependencyGraph/
      BuildCache/
      BuildGraph/
      ImportService/
    importers/
      TextureImporter/
      MaterialImporter/
      ShaderImporter/
      ModelImporter/
      UIDocumentImporter/
      VolumeImporter/
      GaussianSplatImporter/
    compilers/
      ShaderCompiler/
      UIDocumentCompiler/
    writers/
      ArtifactWriter/
      CatalogWriter/
      PackageWriter/
    cook/
    tools/
  editor/
  programs/
    xcgame/
    xcassetbuild/
    xccook/
    xcshadercook/
  managed/
    runtime/
    editor/
  project/
    Assets/
    Settings/
    Library/
      SourceDB/
      ArtifactDB/
      Artifacts/
      ImportLogs/
      ScriptAssemblies/
  tests/
    foundation/
    shared/
    runtime/
    pipeline/
    editor/
    e2e/
  docs/
  tools/
  third_party/
```

## 5. 各层职责

### 5.1 `engine/foundation`

基础设施层承载全仓通用能力：

- 基础类型
- 日志与诊断
- 字符串和容器
- 数学库
- 线程和同步
- 内存管理
- 序列化
- 文件系统封装

### 5.2 `engine/shared`

共享契约层承载跨阶段稳定数据结构：

- 资源标识
- 本地标识
- 资源类型枚举
- catalog / package 描述结构
- 各类 cooked payload 结构
- 版本常量

这一层只放数据契约，不放 manager、loader、cache、importer、orchestrator。

### 5.3 `engine/runtime`

运行时层负责：

- 资源加载与解析
- 运行时对象缓存
- 异步加载调度
- scene 系统
- rendering
- audio
- physics
- scripting

runtime 侧收敛原则：

- 面向运行时消费资源
- 不承载源资源导入
- 不承载构建缓存管理
- 不直接持有 pipeline 服务实现

### 5.4 `pipeline`

pipeline 层负责：

- 源资源数据库
- 中间产物数据库
- 源资源索引
- 依赖关系图
- 构建缓存
- 构建图
- import service
- 各类 importer 和 compiler
- 中间产物写入和后续打包写入

`project/Library` 下的导入和构建状态由这一层统一负责。

### 5.5 `editor`

当前阶段保留现有顶层 `editor` 应用树，职责包括：

- workspace / project 相关交互
- runtime 与 pipeline 的编排
- editor 场景和工具工作流

editor 内部目录重组不属于第一阶段工作。

### 5.6 `programs`

各类可执行入口统一放在这里，例如：

- 游戏程序
- 资源构建工具
- 烘焙工具
- shader 工具

## 6. 当前系统到目标结构的映射

当前主要系统映射如下：

- `ResourceManager` -> `engine/runtime/asset/AssetManager`
- `ResourceCache` -> `engine/runtime/asset/ResourceStore`
- `AsyncLoader` -> `engine/runtime/asset/AsyncLoad`
- `ProjectAssetIndex` -> `pipeline/core/SourceIndex`
- `AssetImportService` -> `pipeline/core/ImportService`
- `AssetDatabase` -> `pipeline/core/SourceAssetDB` + `pipeline/core/ArtifactDB`
- `RenderResourceCache` -> `engine/runtime/rendering/gpu_cache`

重构过程中，editor 迭代路径先保持在现有项目工作流上，再逐步完成职责分拆。

## 7. 构建目标规划

建议的目标族如下：

```text
xc_foundation
xc_shared_asset
xc_shared_cooked

xc_runtime_platform
xc_runtime_asset
xc_runtime_resources
xc_runtime_scene
xc_runtime_rendering
xc_runtime_audio
xc_runtime_physics
xc_runtime_scripting
xc_runtime

xc_pipeline_core
xc_pipeline_importers
xc_pipeline_compilers
xc_pipeline_writers
xc_pipeline_cook
xc_pipeline

xcgame
xcassetbuild
xccook
xcshadercook
```

构建侧落地原则：

- 运行时可执行程序链接 `xc_runtime`
- 资源工具链接 `xc_pipeline`
- editor 入口结构在前几个阶段保持现状

## 8. 分阶段执行计划

### 阶段一：构建边界拆分

目标：

- 先把现有代码拆成 foundation、shared、runtime、pipeline 四类目标
- 这一阶段尽量少动物理文件位置

工作项：

- 拆分 CMake target
- 收敛公共头文件暴露面
- 消除 target 级别的 runtime / pipeline 混杂依赖

阶段验收：

1. 编译 `XCEditor`
2. 执行 12 秒 editor 冒烟测试

### 阶段二：API 边界拆分

目标：

- 把 runtime 侧资源访问接口和 pipeline 侧导入/构建职责拆开

工作项：

- 将 import / build 逻辑收拢到 pipeline 服务
- 将 runtime manager 收窄到 load / resolve / cache 范围
- 保持 editor 当前迭代工作流稳定

阶段验收：

1. 编译 `XCEditor`
2. 执行 12 秒 editor 冒烟测试

### 阶段三：物理目录迁移

目标：

- 让磁盘目录结构和依赖边界对齐

工作项：

- 把文件迁移到 `engine/foundation`、`engine/shared`、`engine/runtime`、`pipeline`
- 更新 include、CMake 和测试
- 除非前置拆分强依赖，否则不在这一阶段重组 editor 内部树

阶段验收：

1. 编译 `XCEditor`
2. 执行 12 秒 editor 冒烟测试

### 阶段四：交付与打包阶段

目标：

- 在 runtime、pipeline、editor 职责已经清晰之后，再引入独立交付流程

工作项：

- 增加专用 cook / build 可执行工具
- 明确交付产物格式和输出路径
- 将交付流程与 editor 日常迭代流程分离

阶段验收：

1. 编译 `XCEditor`
2. 执行 12 秒 editor 冒烟测试

## 9. 硬性规则

整个重构过程都遵守以下规则：

1. `Library` 是 pipeline 侧的缓存和中间状态。
2. runtime API 只收敛到运行时资源访问职责。
3. 大规模文件迁移必须排在 target 和 API 边界稳定之后。
4. shared 层只保留稳定数据契约。
5. phases 1 到 3 期间，editor 日常迭代路径保持连续可用。
6. 每个阶段完成后都要先编译 `XCEditor`，再执行 12 秒冒烟测试。