完成 P2 第一阶段包与编辑器准备

docs/guides/flowscope-package-layout.md

@@ -0,0 +1,137 @@
+# 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 和关键示例路径；如果某一步失败，应先回到该步骤修复，不继续叠加后续搬迁。