升级 P1 主菜单样例和使用规范

docs/guides/flowscope-runtime-usage.md

@@ -0,0 +1,55 @@
+# 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 全绿前，不要宣布生产化验收完成。

docs/guides/main-menu-p1-sample.md

@@ -0,0 +1,33 @@
+# MainMenuP0 P1 样例验收
+
+## 打开场景
+
+在 Unity 中打开：
+
+```text
+My project/Assets/FlowScope/Samples/MainMenuP0/Scenes/MainMenuP0.unity
+```
+
+进入 Play Mode 后，`GameBootstrap` 会注册 P1 运行时服务，预加载 `MainMenuPanel`，并启动 `MainMenuFeature`。
+
+## 预期画面
+
+画面中应出现主菜单面板、Gold 数字文本和一个递增按钮。若场景或 prefab 引用缺失，样例仍会创建运行时 fallback UI，但人工验收应优先检查场景和 prefab 引用是否正确。
+
+## Gold 递增
+
+按钮点击调用 `MainMenuViewModel.IncrementGold`，立即修改 `PlayerData.Gold`，并通过面板订阅同步刷新 Gold 文本。点击一次后，文本应从 `0` 变为 `1`。
+
+## 保存与恢复
+
+`ShutdownAsync` 会把 `PlayerData` 写入 `main-menu-player` 存档。再次启动样例时，`SaveService` 会读取同一 key 并恢复 Gold。
+
+P1 样例使用 `JsonSaveSerializer` 版本 envelope；旧版裸 JSON 会通过 no-op 的 1 -> 2 迁移链继续读取。
+
+## 资源释放
+
+样例资源通过 `ResourceService` 和样例 `IResourceBackend` 加载。`UIPreloadService` 持有预加载 handle；Feature 退出时关闭面板实例，Bootstrap 关闭时调用 `ReleaseAll` 释放预加载资源。
+
+## Console 输出
+
+验收期间不应出现未预期的 Error 或 Exception。Unity 引用版本冲突警告如果只出现在外部 `dotnet build` 中，属于当前 Unity 生成项目的已知警告，不作为样例失败条件。