收口 P2 前预加载边界并补需求文档

docs/requirements/p2-package-editor-requirements.md

@@ -0,0 +1,163 @@
+# FlowScope Game Core P2 需求文档
+
+## 文档目的
+
+本文用于开启 P2 新对话时作为需求入口。P2 不再继续修补 P0/P1 内核语义，而是在当前已稳定的 Runtime 基础上，推进包分发、编辑器体验、真实集成验收和跨项目复用。
+
+## 当前基线
+
+- P0 已提供 Container、Feature、GameFlow、ResourceService、ConfigProvider、SaveService、AudioService、UIManager 等轻量核心能力。
+- P1 已完成生产化第一步：资源后端抽象、Addressables 独立适配、配置 source/parser、存档 migration、UI 导航与预加载、MainMenuP0 样例升级。
+- P2 前整改已收口 Container 生命周期、Feature scope、GameFlow shutdown、ResourceService 共享加载、UIPreloadService 取消/释放/重入边界。
+- 进入 P2 前，EditMode 与 PlayMode Unity Test Runner 已由人工确认全绿。
+
+## P2 总目标
+
+把 FlowScope 从“项目内 Runtime 骨架”推进到“可跨项目复用的 Unity Package 雏形”，让使用者能清楚安装、接入、验证、诊断，并避免误用 P0/P1 核心 API。
+
+## 核心原则
+
+- 不重写 P0/P1 核心生命周期。
+- 不引入大型 DI、全局 EventBus、完整生态或多后端大一统。
+- 先建立分发和验收边界，再扩展能力。
+- Runtime、Addressables、Editor、Samples、Tests 之间保持 asmdef 边界清晰。
+- 任何新增 API 必须有使用场景、测试和文档，不为了“框架完整感”提前扩张。
+
+## 本轮范围
+
+### 1. Package 分发结构
+
+目标：让 FlowScope 可以被整理成标准 Unity Package 形态，并保留当前 Assets 内开发体验的迁移路径。
+
+需求：
+
+- 定义包名、版本号、displayName、Unity 版本和依赖。
+- 明确 Runtime、Addressables adapter、Editor、Samples、Tests 的目录结构。
+- 明确 asmdef 依赖方向：
+  - `FlowScope.Runtime` 不依赖 Addressables、Editor、Samples。
+  - `FlowScope.Addressables` 依赖 `FlowScope.Runtime` 与 Unity Addressables。
+  - `FlowScope.Editor` 只依赖需要检查的 runtime/editor 程序集。
+  - Samples 依赖 Runtime 与需要演示的适配包。
+- 给出从 `Assets/FlowScope` 迁移到 package 结构的阶段方案，避免一次性大搬迁破坏现有测试。
+
+验收：
+
+- package 元数据完整。
+- Unity 能识别 package。
+- Runtime 与 Addressables asmdef 编译边界保持稳定。
+- 迁移方案能说明哪些文件先不移动，以及原因。
+
+### 2. 最小安装与接入文档
+
+目标：让新项目能按文档完成 FlowScope 接入。
+
+需求：
+
+- 编写安装方式：
+  - 本地 package 路径安装。
+  - Git URL 安装。
+  - 项目内 Assets 开发模式。
+- 编写最小 bootstrap 示例：
+  - 创建 Container。
+  - 注册 ResourceService 与 AddressablesResourceBackend。
+  - 注册 ConfigProvider、SaveService、AudioService、UIManager。
+  - 启动 GameFlow。
+  - Shutdown 时释放资源和订阅。
+- 明确常见误用：
+  - 不要把 transient 对象注册成 singleton factory。
+  - 不要业务层直接调用 Addressables。
+  - 不要用 `UIScreenNavigator` 当完整页面路由。
+  - 不要跳过 shutdown cleanup。
+
+验收：
+
+- 文档能独立指导一个空 Unity 项目接入 Runtime。
+- 文档中所有 API 名称与当前代码一致。
+- 示例代码能通过 generated csproj 编译或在 Unity 中编译。
+
+### 3. Addressables 真实集成验收
+
+目标：补齐 P1 留下的真实 Addressables load/release 验收缺口。
+
+需求：
+
+- 准备最小 Addressables 测试资源或人工验收场景。
+- 验证 `AddressablesResourceBackend.LoadAsync<T>` 成功加载真实资源。
+- 验证 `Release(object asset)` 能释放已加载资源，不产生重复释放异常。
+- 验证资源缺失或类型不匹配时错误可诊断。
+- 如自动化 PlayMode 测试成本过高，先记录可重复的人工验收步骤和结果。
+
+验收：
+
+- 至少有一种可重复验证方式证明 Addressables adapter 不只是编译通过。
+- 验收记录写入 docs，作为 package 发布前 gate。
+
+### 4. Editor 诊断工具第一步
+
+目标：只做最小检查工具，不做完整编辑器平台。
+
+需求：
+
+- 提供一个 FlowScope 菜单入口或 EditorWindow。
+- 检查项目是否具备必要依赖：
+  - Addressables package 是否存在。
+  - Runtime/Addressables asmdef 是否可见。
+  - Samples 是否缺失关键场景或 prefab 引用。
+- 输出可执行的诊断结果，不自动修改项目。
+
+验收：
+
+- 工具可在 Unity Editor 打开。
+- 检查结果不会误报为“已修复”。
+- 没有自动生成或删除用户资源。
+
+### 5. Samples 整理
+
+目标：让 MainMenuP0 从 P1 验收样例变成 P2 package sample 的候选。
+
+需求：
+
+- 明确 MainMenuP0 是否移动到 `Samples~`，或暂时保留在 `Assets/FlowScope/Samples`。
+- 补充 sample README，说明它覆盖的 Runtime 能力。
+- 保持启动、点击、保存恢复、shutdown cleanup 测试有效。
+
+验收：
+
+- 用户能通过 sample 看懂最小接入方式。
+- PlayMode sample 测试继续全绿。
+
+## 暂不进入 P2 的范围
+
+- YooAsset / AssetBundle / Resources 多后端完整实现。
+- 云存档、远程配置、热更新配置。
+- 完整 UI 路由、URL 跳转、跨 Feature 页面恢复。
+- AudioMixer、3D 音频、动态音乐系统。
+- 大型资源预算、内存分析和自动修复工具。
+- 完整发布流水线和版本兼容策略。
+
+## P2 第一轮建议执行顺序
+
+1. 建立 P2 package 结构方案和迁移边界。
+2. 补 Addressables 真实集成验收或人工验收记录。
+3. 编写安装与最小 bootstrap 文档。
+4. 做最小 Editor 诊断入口。
+5. 整理 MainMenuP0 sample 文档和 package sample 候选路径。
+
+## 新对话启动提示
+
+新对话可以直接使用以下目标：
+
+```text
+根据 docs/requirements/p2-package-editor-requirements.md，先不要直接写代码。请先审查当前 FlowScope P0/P1 基线、package/editor 相关现状和 Addressables 验收缺口，然后输出 P2 第一阶段实施计划。计划必须使用中文，并遵守 AGENTS.md 中的 Git/Plan 规则。
+```
+
+## 验收 Gate
+
+P2 第一阶段完成前必须满足：
+
+- EditMode 全绿。
+- PlayMode 全绿。
+- generated csproj build 0 error。
+- Addressables adapter 有真实集成验收记录。
+- package/editor 相关新增内容不破坏当前 Assets 内开发模式。
+- 文档能说明安装、接入、验证和已知限制。