# FlowScope Runtime 使用规范

## Bootstrap

Bootstrap 负责组合运行时依赖，而不是把业务流程写进场景脚本。推荐顺序是创建根 `Container`、注册 Config/Resource/Save/UI/Audio 等服务、注册首个 Feature 的工厂，最后调用 `GameFlow.StartupAsync<TInitialFeature>`。

Bootstrap 必须持有生命周期 `CancellationToken`，退出时先保存必要状态，再调用 `GameFlow.ShutdownAsync`，最后释放预加载资源、音频句柄或其他根级缓存。

## Container 注册规则

容器注册应显式、可读、可追踪。稳定服务使用 `RegisterInstance`，带运行时参数或 Feature 私有依赖使用 `RegisterFactory`。不要依赖类型扫描或名称约定来猜测注册关系。

Feature 只从自己的 scope 解析依赖。跨 Feature 的共享服务放在 root container，Feature 内部临时对象放在 Feature scope，并随 `FeatureContext` 一起释放。

## Feature 生命周期

`LoadAsync` 只准备数据、ViewModel 和轻量状态；`EnterAsync` 打开 UI、订阅输入或启动表现；`ExitAsync` 必须关闭本 Feature 打开的 UI 并释放订阅；`Dispose` 只做最后的托底清理。

不要在 `Dispose` 中启动新的异步工作。需要异步关闭的行为放在 `ExitAsync`。

## 资源所有权

P1 的资源入口是 `ResourceService`，后端由 `IResourceBackend` 适配。业务层只持有 `IResourceHandle<T>` 或 `IResourceGroup`，不直接调用 Addressables 或样例 backend。

谁创建 handle，谁负责释放。预加载资源由 `UIPreloadService` 持有，UI 实例关闭时不释放预加载 handle，Bootstrap 或上层流程退出时调用 `Release<TPanel>` 或 `ReleaseAll`。

## UI 路径和层级

Panel 类型必须声明 `UIPanelAttribute`。优先显式填写资源路径，例如 `FlowScope/Samples/MainMenuP0/MainMenuPanel`；未填写时才使用 `UI/{PanelNameWithoutSuffix}/Prefab` 约定。

`UIManager` 维护层内 LIFO。`UIScreenNavigator` 只管理它自己 push 的页面，`GoBack` 保留最后一个页面，`Clear` 清空导航器打开的页面。

## 配置 DTO 约束

配置行实现 `IConfigRow`，`Id` 在同一表内必须唯一。DTO 应保持简单字段或属性，不把运行时对象、Unity 组件、服务实例放进配置。

配置加载通过 `IConfigSource` 读取文本，通过 `IConfigParser` 解析。生产环境可接文件或远端来源，测试和样例可使用 `InMemoryConfigSource`。

## 存档版本迁移

`JsonSaveSerializer` 的 `currentVersion` 大于 1 时会写入版本 envelope。旧版裸 JSON 被视为版本 1，并通过 `SaveMigrationRegistry` 迁移到当前版本。

每个迁移实现 `ISaveMigration`，`Key` 默认使用存档 DTO 类型全名，迁移链必须逐版本连续，例如 1 -> 2 -> 3。

## Addressables 后端接入

生产资源后端使用 `FlowScope.Addressables.AddressablesResourceBackend`。项目需要在 `Packages/manifest.json` 中包含 `com.unity.addressables`，并让 Unity 完成包解析后再运行 PlayMode 全量测试。

业务代码不直接依赖 Addressables API。需要替换后端时，只调整 Bootstrap 或平台装配层的 `IResourceBackend` 注册。

## 测试建议

窄单元测试优先覆盖接口契约：重复加载共享、取消不释放他人 handle、配置重复 ID、存档迁移缺链、UI LIFO 和预加载释放。

样例验收至少覆盖启动可见、按钮即时更新、关闭保存、重启恢复、资源释放。Unity Test Runner 全绿前，不要宣布生产化验收完成。