# 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 内开发模式。
- 文档能说明安装、接入、验证和已知限制。