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