# FlowScope Package 结构与迁移边界

日期：2026-06-06

本文说明 FlowScope P2 阶段当前 package 结构、仍保留的 Assets 开发模式，以及后续迁移边界。

## 当前状态

FlowScope 当前采用双轨结构：

```text
My project/Assets/FlowScope
Packages/com.flowscope.gamecore
```

`Assets/FlowScope` 仍是开发工程内的测试和样例源；`Packages/com.flowscope.gamecore` 是面向消费方的 Unity Package 雏形。

当前 package 目录：

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

已完成：
- Runtime 镜像到 `Runtime/`。
- Addressables adapter 镜像到 `Addressables/`。
- Editor 诊断窗口镜像到 `Editor/`。
- MainMenuP0 镜像到 `Samples~/MainMenuP0`。
- `Tests~/EditMode` 已建立最小 smoke 测试。
- package 顶层 `.meta` 已补齐，避免 immutable package 导入错误。
- `v0.2.0-preview.2` 已完成空白消费方刷新确认。

不作为 P2 package/editor 收尾阻塞：
- package `Tests~` 全量迁移策略。
- 是否将 package 作为源码主线。

## 目录职责

| 目录 | 职责 |
| --- | --- |
| `package.json` | Unity Package Manager 元数据，声明包名、显示名、版本、Unity 版本、依赖和 sample。 |
| `Runtime/` | FlowScope 核心运行时代码，包括 Container、Feature、GameFlow、Resource、Config、Save、Audio、UI。 |
| `Addressables/` | Addressables 适配层，提供 `AddressablesResourceBackend` 与 `AddressablesResourceService`。 |
| `Editor/` | Editor-only 诊断入口，不承载运行时逻辑，不自动修改用户资源。 |
| `Samples~/` | Package Manager 可导入示例。当前包含 `MainMenuP0`。 |
| `Tests~/` | package 内测试候选。当前先放最小 EditMode smoke 测试，不替代开发工程内完整测试。 |
| `Documentation~/` | Package Manager 文档入口，包含安装和接入说明。 |

## package.json 当前形态

```json
{
  "name": "com.flowscope.gamecore",
  "displayName": "FlowScope Game Core",
  "version": "0.2.0-preview.2",
  "unity": "2022.3",
  "dependencies": {
    "com.unity.addressables": "1.21.21",
    "com.unity.ugui": "1.0.0"
  },
  "samples": [
    {
      "displayName": "MainMenuP0",
      "description": "Minimal FlowScope bootstrap, feature, UI, save, and preload sample.",
      "path": "Samples~/MainMenuP0"
    }
  ]
}
```

注意：`com.cysharp.r3` 和 `org.nuget.r3` 当前由消费方项目显式声明，原因是 Unity Package Manager 不可靠支持 package 内 Git dependency 传递解析。

## asmdef 依赖方向

必须保持以下方向：

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

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

FlowScope.Editor
  -> FlowScope.Runtime
  -> 诊断所需的 Editor 程序集

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

FlowScope.PackageTests.EditMode
  -> FlowScope.Runtime
  -> FlowScope.Addressables
  -> NUnit / Unity Test Framework
```

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

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

## 双轨边界

当前不删除 `Assets/FlowScope`，原因：

1. `Assets/FlowScope` 仍承载完整 EditMode / PlayMode 回归测试。
2. 主项目内 Addressables 真实 fixture 和 settings 是当前真实验收来源。
3. `Samples~/MainMenuP0` 是 package sample 候选，已在空白消费方手动导入验收。
4. 一次性把 Samples、Tests 和 Addressables fixture 全部迁入 package 会扩大验证面。

当前迁移策略是“镜像 + 逐步验收”：

1. package 内保留 Runtime / Addressables / Editor 镜像。
2. package sample 先镜像 MainMenuP0，不删除 Assets 样例。
3. package tests 先建立最小 smoke 测试，不删除 Assets 测试。
4. package preview gate 已由 `v0.2.0-preview.2` 收口；是否把 package 作为源码主线留到后续阶段决策。

## 后续迁移顺序

P2 package/editor 已收口，后续迁移建议按以下顺序单独规划：

1. 决定哪些测试可迁入 package，哪些仍留在开发工程。
2. 规划 package PlayMode 测试和 Addressables fixture 镜像策略。
3. 决定是否把 package 作为源码主线。