补齐 package Tests 第一刀

2026-06-06 16:14:17 +08:00
parent 0930e7c173
commit 7b2243a40b
13 changed files with 334 additions and 169 deletions
--- a/docs/guides/flowscope-package-layout.md
+++ b/docs/guides/flowscope-package-layout.md
@@ -1,86 +1,88 @@
-# FlowScope Package 目标结构
+# FlowScope Package 结构与迁移边界

-日期：2026-05-26
+日期：2026-06-06

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

 ## 当前状态

-当前 FlowScope 仍处于项目内开发模式：
+FlowScope 当前采用双轨结构：

 ```text
-My project/
-  Assets/
-    FlowScope/
-      Runtime/
-      Addressables/
-      Samples/
-      Tests/
+My project/Assets/FlowScope
+Packages/com.flowscope.gamecore
 ```

-当前尚未建立标准 Unity Package 根目录，未发现包级 `package.json`、`Samples~`、`Tests~`、`Documentation~` 目录。`MainMenuP0` 示例仍位于 `Assets/FlowScope/Samples/MainMenuP0`。
+`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
-    LICENSE.md
+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 版本与依赖。 |
-| `Runtime/` | FlowScope 核心运行时代码，包括 Container、Feature、GameFlow、Resource、Config、Save、Audio、UI 等能力。 |
+| `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`。示例可以依赖 Runtime 与所演示的适配包。 |
-| `Tests/` | 包内测试，按 EditMode 与 PlayMode 分层保留测试 asmdef。 |
-| `Documentation~/` | Package Manager 文档入口，包含安装、接入、诊断与示例说明。 |
+| `Editor/` | Editor-only 诊断入口，不承载运行时逻辑，不自动修改用户资源。 |
+| `Samples~/` | Package Manager 可导入示例。当前包含 `MainMenuP0`。 |
+| `Tests~/` | package 内测试候选。当前先放最小 EditMode smoke 测试，不替代开发工程内完整测试。 |
+| `Documentation~/` | Package Manager 文档入口，包含安装和接入说明。 |

-## package.json 建议形态
-
-目标包元数据建议保持最小可识别：
+## package.json 当前形态

 ```json
 {
  "name": "com.flowscope.gamecore",
  "displayName": "FlowScope Game Core",
-  "version": "0.2.0",
+  "version": "0.2.0-preview.1",
  "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"
-  }
+  },
+  "samples": [
+    {
+      "displayName": "MainMenuP0",
+      "description": "Minimal FlowScope bootstrap, feature, UI, save, and preload sample.",
+      "path": "Samples~/MainMenuP0"
+    }
+  ]
 }
 ```

-依赖说明：
-
- `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 或嵌入式依赖策略。
+注意：`com.cysharp.r3` 和 `org.nuget.r3` 当前由消费方项目显式声明，原因是 Unity Package Manager 不可靠支持 package 内 Git dependency 传递解析。

 ## asmdef 依赖方向

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

 ```text
 FlowScope.Runtime
@@ -93,45 +95,49 @@ FlowScope.Addressables

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

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

-FlowScope.Tests.EditMode / FlowScope.Tests.PlayMode
-  -> 被测程序集
+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`，但文件处于 `Assets/FlowScope/Addressables` 并编译进 `FlowScope.Addressables` 程序集；迁移时应保留程序集边界，不应因为命名空间相同而把 Addressables 适配代码并回 Runtime。
+`AddressablesResourceService` 当前命名空间为 `FlowScope.Resources`，但文件位于 Addressables 适配程序集；迁移和镜像时必须保留程序集边界，不应因为命名空间相同而把 Addressables 适配代码并回 Runtime。

-## 第一阶段暂不搬迁 Assets/FlowScope 的原因
+## 双轨边界

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

-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 试迁移按批次验证，而不是一次性大搬迁。
+1. `Assets/FlowScope` 仍承载完整 EditMode / PlayMode 回归测试。
+2. 主项目内 Addressables 真实 fixture 和 settings 是当前真实验收来源。
+3. `Samples~/MainMenuP0` 是 package sample 候选，但尚未完成消费方导入验收。
+4. 一次性把 Samples、Tests 和 Addressables fixture 全部迁入 package 会扩大验证面。

-## 建议迁移顺序
+当前迁移策略是“镜像 + 逐步验收”：

-后续进入 P2 第二阶段时，建议按以下顺序迁移，每一步都保留独立验证记录：
+1. package 内保留 Runtime / Addressables / Editor 镜像。
+2. package sample 先镜像 MainMenuP0，不删除 Assets 样例。
+3. package tests 先建立最小 smoke 测试，不删除 Assets 测试。
+4. 待 package 导入、Tests~、空白项目验证完成后，再决定是否把 package 作为源码主线。

-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 发现与执行。
+## 后续 P2 顺序

-每一步完成前都应验证 generated csproj build、Unity Test Runner 和关键示例路径；如果某一步失败，应先回到该步骤修复，不继续叠加后续搬迁。
+建议继续按以下顺序收口：
+
+1. 完成 package `Tests~` 第一刀并验证静态结构。
+2. 决定哪些测试可迁入 package，哪些仍留在开发工程。
+3. 在消费方导入 `Samples~/MainMenuP0` 做人工验收。
+4. 在空白 Unity 项目中复验 Git URL 安装。
+5. 根据最新 package 内容打下一个 preview tag。