# FlowScope Package 目标结构

日期：2026-05-26

本文说明 FlowScope P2 阶段的目标 Unity Package 目录形态，以及第一阶段暂不搬迁 `Assets/FlowScope` 的边界。本文只描述目标结构与迁移约束，不代表当前仓库已经完成物理搬迁。

## 当前状态

当前 FlowScope 仍处于项目内开发模式：

```text
My project/
  Assets/
    FlowScope/
      Runtime/
      Addressables/
      Samples/
      Tests/
```

当前尚未建立标准 Unity Package 根目录，未发现包级 `package.json`、`Samples~`、`Tests~`、`Documentation~` 目录。`MainMenuP0` 示例仍位于 `Assets/FlowScope/Samples/MainMenuP0`。

## 目标包根目录

目标包建议使用独立目录承载，例如：

```text
Packages/
  com.flowscope.gamecore/
    package.json
    Runtime/
    Addressables/
    Editor/
    Samples~/
    Tests/
    Documentation~/
    README.md
    CHANGELOG.md
    LICENSE.md
```

目录职责如下：

| 目录 | 职责 |
| --- | --- |
| `package.json` | Unity Package Manager 元数据，声明包名、显示名、版本、Unity 版本与依赖。 |
| `Runtime/` | FlowScope 核心运行时代码，包括 Container、Feature、GameFlow、Resource、Config、Save、Audio、UI 等能力。 |
| `Addressables/` | Addressables 适配层，提供 `AddressablesResourceBackend` 与 `AddressablesResourceService`。 |
| `Editor/` | 只放编辑器诊断、检查、菜单入口等 Editor-only 内容，不承载运行时逻辑。 |
| `Samples~/` | Package Manager 可导入示例，例如 `MainMenuP0`。示例可以依赖 Runtime 与所演示的适配包。 |
| `Tests/` | 包内测试，按 EditMode 与 PlayMode 分层保留测试 asmdef。 |
| `Documentation~/` | Package Manager 文档入口，包含安装、接入、诊断与示例说明。 |

## package.json 建议形态

目标包元数据建议保持最小可识别：

```json
{
  "name": "com.flowscope.gamecore",
  "displayName": "FlowScope Game Core",
  "version": "0.2.0",
  "unity": "2022.3",
  "description": "A lightweight Unity game flow, resource, config, save, audio, and UI runtime foundation.",
  "dependencies": {
    "com.cysharp.r3": "https://github.com/Cysharp/R3.git?path=src/R3.Unity/Assets/R3.Unity#1.3.0",
    "com.unity.addressables": "1.21.21",
    "com.unity.ugui": "1.0.0"
  }
}
```

依赖说明：

- `com.cysharp.r3` 是当前 `FlowScope.Runtime.asmdef` 直接引用 `R3.Unity` 的来源。
- `com.unity.addressables` 只服务 `FlowScope.Addressables`，Runtime 不直接依赖 Addressables。
- `com.unity.ugui` 服务当前 UI 与示例中的 `Canvas`、`Button`、`Text` 等 UGUI 类型。

如果后续发布渠道不接受 Git URL 形式依赖，应在发布前改为团队确认过的 OpenUPM、内网 registry 或嵌入式依赖策略。

## asmdef 依赖方向

当前与目标结构都必须保持以下方向：

```text
FlowScope.Runtime
  -> R3.Unity

FlowScope.Addressables
  -> FlowScope.Runtime
  -> Unity.Addressables
  -> Unity.ResourceManager

FlowScope.Editor
  -> FlowScope.Runtime
  -> 需要诊断的编辑器程序集

FlowScope.Samples.MainMenuP0
  -> FlowScope.Runtime
  -> R3.Unity

FlowScope.Tests.EditMode / FlowScope.Tests.PlayMode
  -> 被测程序集
```

禁止反向依赖：

- `FlowScope.Runtime` 不依赖 `FlowScope.Addressables`。
- `FlowScope.Runtime` 不依赖 `FlowScope.Editor`。
- `FlowScope.Runtime` 不依赖 `FlowScope.Samples.*`。
- `FlowScope.Runtime` 不依赖测试程序集。
- Samples 不作为 Runtime 的依赖来源。

`AddressablesResourceService` 当前命名空间位于 `FlowScope.Resources`，但文件处于 `Assets/FlowScope/Addressables` 并编译进 `FlowScope.Addressables` 程序集；迁移时应保留程序集边界，不应因为命名空间相同而把 Addressables 适配代码并回 Runtime。

## 第一阶段暂不搬迁 Assets/FlowScope 的原因

P2 第一阶段只建立分发边界、安装接入文档、Addressables 验收与最小 Editor 诊断入口，不做物理搬迁，原因如下：

1. 当前 `Assets/FlowScope` 已承载 P0/P1 Runtime、Addressables、Samples、Tests 的稳定验证路径。
2. `MainMenuP0` 示例、PlayMode 测试与 Unity 生成的 csproj 仍依赖当前 Asset 路径。
3. 一次性移动 Runtime、Samples、Tests 会同时改变 asmdef 路径、资源路径、场景引用、prefab 引用与测试发现路径，容易把包结构问题和运行时回归混在一起。
4. 第一阶段还有并行 worker 处理 Addressables 验收与 Editor 诊断；Package 文档 worker 不应覆盖或移动他们的文件。
5. 先用文档锁定目标结构与依赖方向，可以让第二阶段本地 package 试迁移按批次验证，而不是一次性大搬迁。

## 建议迁移顺序

后续进入 P2 第二阶段时，建议按以下顺序迁移，每一步都保留独立验证记录：

1. 创建 package 根目录与 `package.json`，先不移动 Runtime。
2. 将 `Runtime/` 移入包目录并验证 `FlowScope.Runtime` 编译边界。
3. 将 `Addressables/` 移入包目录并验证 `FlowScope.Addressables` 仍只依赖 Runtime 与 Unity Addressables。
4. 将文档迁入 `Documentation~/` 或同步保留到仓库 `docs/`。
5. 将 `MainMenuP0` 作为包示例迁入 `Samples~/MainMenuP0`，验证场景、prefab、配置与测试路径。
6. 将 EditMode / PlayMode 测试整理进包内 `Tests/`，验证 Unity Test Runner 发现与执行。

每一步完成前都应验证 generated csproj build、Unity Test Runner 和关键示例路径；如果某一步失败，应先回到该步骤修复，不继续叠加后续搬迁。