6.3 KiB
6.3 KiB
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 第一轮建议执行顺序
- 建立 P2 package 结构方案和迁移边界。
- 补 Addressables 真实集成验收或人工验收记录。
- 编写安装与最小 bootstrap 文档。
- 做最小 Editor 诊断入口。
- 整理 MainMenuP0 sample 文档和 package sample 候选路径。
新对话启动提示
新对话可以直接使用以下目标：
根据 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 内开发模式。
- 文档能说明安装、接入、验证和已知限制。