3.5 KiB
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 全绿前，不要宣布生产化验收完成。