138 lines
5.5 KiB
Markdown
138 lines
5.5 KiB
Markdown
# 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 和关键示例路径；如果某一步失败，应先回到该步骤修复，不继续叠加后续搬迁。
|