144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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 导入错误。
|
||
|
||
未完成：
|
||
- package `Tests~` 全量迁移策略。
|
||
- package sample 导入验收。
|
||
- 空白 Unity 项目安装复验。
|
||
- 下一个 preview tag。
|
||
|
||
## 目录职责
|
||
|
||
| 目录 | 职责 |
|
||
| --- | --- |
|
||
| `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 导入、Tests~、空白项目验证完成后，再决定是否把 package 作为源码主线。
|
||
|
||
## 后续 P2 顺序
|
||
|
||
建议继续按以下顺序收口：
|
||
|
||
1. 完成 package `Tests~` 第一刀并验证静态结构。
|
||
2. 决定哪些测试可迁入 package，哪些仍留在开发工程。
|
||
3. 在消费方导入 `Samples~/MainMenuP0` 做人工验收。
|
||
4. 在空白 Unity 项目中复验 Git URL 安装。
|
||
5. 根据最新 package 内容打下一个 preview tag。
|