FlowScope Package 结构与迁移边界

日期：2026-06-06

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

当前状态

FlowScope 当前采用双轨结构：

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

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

当前 package 目录：

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 当前形态

{
  "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 依赖方向

必须保持以下方向：

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，原因：

Assets/FlowScope 仍承载完整 EditMode / PlayMode 回归测试。
主项目内 Addressables 真实 fixture 和 settings 是当前真实验收来源。
Samples~/MainMenuP0 是 package sample 候选，但尚未完成消费方导入验收。
一次性把 Samples、Tests 和 Addressables fixture 全部迁入 package 会扩大验证面。

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

package 内保留 Runtime / Addressables / Editor 镜像。
package sample 先镜像 MainMenuP0，不删除 Assets 样例。
package tests 先建立最小 smoke 测试，不删除 Assets 测试。
待 package 导入、Tests~、空白项目验证完成后，再决定是否把 package 作为源码主线。

后续 P2 顺序

建议继续按以下顺序收口：

完成 package Tests~ 第一刀并验证静态结构。
决定哪些测试可迁入 package，哪些仍留在开发工程。
在消费方导入 Samples~/MainMenuP0 做人工验收。
在空白 Unity 项目中复验 Git URL 安装。
根据最新 package 内容打下一个 preview tag。

4.6 KiB Raw Blame History Unescape Escape