# 通用游戏 Core 需求分档文档

## 文档说明

本文档定义 FlowScope Game Core 的需求分档。P0 的详细需求已经收敛到：

- `docs/requirements/p0-requirements-set.md`
- `docs/requirements/p0-container.md`
- `docs/requirements/p0-gameflow.md`
- `docs/requirements/p0-feature.md`
- `docs/requirements/p0-data-r3.md`
- `docs/requirements/p0-configprovider.md`
- `docs/requirements/p0-saveservice.md`
- `docs/requirements/p0-resourceservice.md`
- `docs/requirements/p0-uimanager.md`
- `docs/requirements/p0-audioservice.md`

如本文档与上述 P0 详细文档冲突，以 P0 详细文档为准。

---

## 分档原则

1. 先满足游戏开发闭环，再追求通用框架完整性。
2. 显式接口优先，不暗猜业务模型，不预设具体 Data 类。
3. P0 必须能支撑一个真实休闲游戏的最小纵向切片。
4. P1 扩展常用生产能力，但不破坏 P0 核心接口。
5. P2 才考虑包分发、编辑器体验、多后端生态和跨项目复用。
6. P3 作为长期演进方向，不进入近期交付承诺。

---

## P0：最小可运行核心

目标：跑通一个休闲/超休闲 Unity 游戏的启动、配置加载、存档加载、进入初始 Feature、打开 MVVM UI、响应 ViewModel/Data 变化、退出并保存。

P0 包含：

| 模块 | 决策 |
|------|------|
| Container | 显式工厂、Attribute + Source Generator、Attribute + 运行时反射均进入 P0 |
| GameFlow | 负责创建 Feature scope、FeatureContext，并编排启动/切换/关闭 |
| Feature | 只负责业务行为，消费 GameFlow 提供的 FeatureContext |
| R3 + Data | 直接使用 R3，不自研响应式系统 |
| ConfigProvider | P0 只支持 JSON 强类型读取 |
| SaveService | P0 只支持本地轻量存档，File 或 PlayerPrefs |
| ResourceService | P0 支持引用计数和 ResourceGroup，默认只支持 Addressables |
| UIManager | P0 支持可配置层级和层内 LIFO 栈 |
| AudioService | P0 支持 BGM/SFX、音量、静音、简单 SFX 池和轻量 AudioHandle |

P0 不包含：

- CSV / Luban / ScriptableObject 配置。
- 云存档、加密、压缩、复杂版本迁移。
- Resources / AssetBundle / YooAsset 资源后端。
- 完整 UI 路由系统。
- 全局 EventBus。
- AudioMixer、3D 音频、动态音乐。
- 编辑器配置检查和资源分析工具。

P0 完成后应能做到：

- Unity 启动后进入 `GameBootstrap`。
- 注册核心服务和业务 Data。
- 加载 JSON 配置。
- 加载或创建存档数据。
- 进入 `MainMenuFeature`。
- 打开 `MainMenuPanel`。
- ViewModel 使用 R3 驱动 UI 刷新。
- 切换或关闭 Feature 时释放资源和订阅。
- 关闭游戏时保存数据。

---

## P1：常用生产能力

目标：在 P0 核心稳定后，扩展常用生产能力，仍然保持 Core 主接口稳定。

候选能力：

| 能力 | 建议形式 |
|------|----------|
| 按模块配置加载 | `IConfigSource` 扩展 |
| CSV / Luban 配置 | `IConfigParser` 插件 |
| 存档版本迁移 | `ISaveMigration` 插件 |
| Resources 后端 | `IResourceBackend` 插件 |
| YooAsset 后端 | `IResourceBackend` 插件 |
| UI 返回策略 | `IUIScreenNavigator` 扩展 |
| Panel 预加载 | UIManager 扩展服务 |
| AudioMixer 分组 | AudioService 扩展 |
| 3D 音频 | AudioService 扩展 |

---

## P2：包分发与生态化

目标：当多个项目复用需求明确后，把 Game Core 整理为更标准的 Unity Package 和可插拔生态。

候选能力：

- `com.flowscope.gamecore` 包结构。
- `package.json` / `README.md` / `CHANGELOG.md` / `Samples~`。
- 独立 asmdef 拆分。
- Editor 导入向导。
- 配置校验工具。
- 资源扫描和分析工具。
- 云存档适配包。
- AssetBundle 适配包。
- UI 路由包。

---

## P3：长期演进方向

目标：只作为方向保留，不进入近期交付范围。

候选能力：

- Source Generator 深度优化。
- `[Inject]` 属性/方法注入。
- 全局 EventBus 并支持 R3/默认实现切换。
- 完整网络长连接、断线重连、心跳机制。
- 云存档冲突解决。
- 热更新框架。
- UI 自动绑定框架。
- 大型项目资源预算和内存分析工具。

---

## 当前实施建议

当前只实施 P0。P0 的并行实施计划见：

- `docs/superpowers/plans/2026-05-15-p0-parallel-implementation-plan.md`

执行顺序：

1. 先完成 `p0-contracts`。
2. 合并共享契约。
3. 再并行执行各模块 worktree。
4. 最后由 `p0-integration` 做统一集成和 Sample 验证。