# FlowScope P2 第一阶段基线审查

日期：2026-05-26

## 审查目的

本文用于锁定 P2 第一阶段执行边界。P2 第一阶段只推进 package 分发边界、安装接入文档、Addressables 真实验收、Editor 最小诊断入口和 MainMenuP0 样例说明，不重写 P0/P1 Runtime 生命周期，不扩大到完整包迁移或编辑器平台化。

## 当前分支与工作树

- 当前分支：`codex/pre-p2-architecture-fixes`
- 本文创建前 `git status --short --branch` 未显示待提交文件；命令输出包含本机 `C:\Users\13999/.config/git/ignore` 权限 warning。
- 本阶段提交信息必须使用中文。
- 本阶段计划、审查、报告必须使用中文。

## P0/P1 Runtime 基线

当前 P0/P1 基线以 `docs/requirements/p0-requirements-set.md`、`docs/requirements/p1-production-hardening.md`、`docs/reviews/p1-completion-report.md` 和 `docs/guides/flowscope-runtime-usage.md` 为主要依据。

已确认的实现状态：

- `FlowScope.Runtime` 已包含 Container、Feature、GameFlow、Config、Save、Resource、Audio、UI、UIPreload、UIScreenNavigator 等 P0/P1 Runtime 能力。
- `FlowScope.Runtime` 的 asmdef 只引用 `R3.Unity`，不直接引用 Addressables、Editor 或 Samples。
- 资源系统已拆成 Runtime 核心 `ResourceService` + `IResourceBackend`，Addressables 适配位于独立 `FlowScope.Addressables` 程序集。
- `UIPreloadService.Release<TPanel>()` 已包含 panel 级 in-flight invalidation，并有 `Release_WhenLoadInFlight_DoesNotCacheAndDisposesLoadedHandle` 测试覆盖；旧的第五轮审查中提到的该项中风险在当前代码中已收口。
- `MainMenuP0` 仍在 `Assets/FlowScope/Samples/MainMenuP0`，尚未迁移到 `Samples~`。

## Package / Editor 现状

当前项目仍是 `Assets/FlowScope` 内开发模式，不是标准 Unity Package 目录。

已确认缺口：

- 当前未发现根级或包级 `package.json`。
- 当前未发现 `Samples~`、`Tests~`、`Documentation~` 标准包目录。
- 当前未发现 `Assets/FlowScope/Editor` 或 `FlowScope.Editor.asmdef`。
- 当前还没有 package 安装说明覆盖本地 path、Git URL、项目内 Assets 开发模式三种路径。

第一阶段边界：

- 可以新增 package 结构方案文档和最小 package 元数据草案。
- 可以新增最小 Editor 诊断入口。
- 不在第一阶段直接搬迁 Runtime、Addressables、Samples 或 Tests。
- 不删除 `Assets/FlowScope` 当前开发模式。

## Addressables 验收缺口

当前 `FlowScope.Addressables` 程序集存在：

- `My project/Assets/FlowScope/Addressables/FlowScope.Addressables.asmdef`
- `My project/Assets/FlowScope/Addressables/AddressablesResourceBackend.cs`
- `My project/Assets/FlowScope/Addressables/AddressablesResourceService.cs`

当前 `AddressablesResourceBackendTests` 只验证：

- `Name_ReturnsAddressables`

缺失的真实验收：

- 使用真实 Addressables key 加载资源。
- 验证 `AddressablesResourceBackend.LoadAsync<T>` 成功返回真实资源。
- 验证 `Release<T>` 对已加载资源可重复进入释放流程且不产生业务层重复释放异常。
- 验证缺失 key 或类型不匹配时，错误信息能定位 key、类型和 backend。
- 如果自动化 PlayMode 准备成本过高，至少要有可重复人工验收步骤与结果记录。

## 当前验证证据

本轮已执行 generated csproj 编译验证：

```powershell
dotnet build "My project\FlowScope.Runtime.csproj" --no-restore
dotnet build "My project\FlowScope.Tests.EditMode.csproj" --no-restore
dotnet build "My project\FlowScope.Tests.PlayMode.csproj" --no-restore
```

结果：

- `FlowScope.Runtime.csproj`：0 error。
- `FlowScope.Tests.EditMode.csproj`：0 error。
- `FlowScope.Tests.PlayMode.csproj`：0 error。
- 存在 Unity generated csproj 常见引用冲突 warning，主要涉及 `System.Net.Http`、`System.Security.Cryptography.Algorithms`、`System.ComponentModel.Annotations`。

未完成验证：

- 本轮未执行 Unity Test Runner 全量 EditMode。
- 本轮未执行 Unity Test Runner 全量 PlayMode。
- 本轮未执行 MainMenuP0 人工场景验收。
- 本轮未执行真实 Addressables load/release 验收。

## P2 第一阶段并行任务边界

### Task A：Package / 安装接入文档

Owned files：

- `docs/guides/flowscope-package-layout.md`
- `docs/guides/flowscope-installation.md`
- 可选：`docs/reviews/p2-phase1-baseline-audit.md` 的补充备注

Do not modify：

- `My project/Assets/FlowScope/Runtime`
- `My project/Assets/FlowScope/Addressables`
- `My project/Assets/FlowScope/Editor`
- `My project/Assets/FlowScope/Samples`
- `My project/Assets/FlowScope/Tests`

验收：

- 文档说明标准 Unity Package 目标结构。
- 文档说明第一阶段为什么暂不搬迁 Runtime/Samples/Tests。
- 安装文档覆盖本地 package path、Git URL、Assets 开发模式。
- Bootstrap 示例只使用当前真实 API 名称。

### Task B：Addressables 真实验收

Owned files：

- `My project/Assets/FlowScope/Tests/PlayMode/Resources/AddressablesResourceBackendTests.cs`
- 必要的最小测试资源及 `.meta`
- `docs/reviews/addressables-integration-acceptance.md`

Do not modify：

- `My project/Assets/FlowScope/Runtime`
- `My project/Assets/FlowScope/Addressables/AddressablesResourceBackend.cs`，除非测试证明当前实现存在真实 bug
- Package 文档与 Editor 文件

验收：

- 优先提供自动化 PlayMode 测试证明真实资源 load/release。
- 若自动化资源维护成本过高，必须提供可重复人工验收步骤、预期结果和未自动化原因。
- `dotnet build "My project\FlowScope.Tests.PlayMode.csproj" --no-restore` 保持 0 error。

### Task C：Editor 最小诊断入口

Owned files：

- `My project/Assets/FlowScope/Editor/FlowScope.Editor.asmdef`
- `My project/Assets/FlowScope/Editor/FlowScopeDiagnosticsWindow.cs`
- 必要 `.meta`
- 可选：`docs/guides/flowscope-editor-diagnostics.md`

Do not modify：

- Runtime、Addressables、Samples、Tests 实现文件。
- 不自动生成、移动、删除用户资源。

验收：

- Unity Editor 中有 `Tools/FlowScope/Diagnostics` 菜单入口。
- 窗口只检查并输出状态，不自动修复。
- 检查 Addressables package、Runtime asmdef、Addressables asmdef、MainMenuP0 关键场景和 prefab 是否存在。
- generated csproj 编译保持 0 error。

## 第一阶段完成 Gate

P2 第一阶段完成前必须满足：

1. `FlowScope.Runtime.csproj`、`FlowScope.Tests.EditMode.csproj`、`FlowScope.Tests.PlayMode.csproj` generated build 均为 0 error。
2. Unity Test Runner 全量 EditMode / PlayMode 至少有明确执行记录；若无法执行，必须记录原因。
3. Addressables adapter 有真实集成验收记录，不再只靠 `Name_ReturnsAddressables`。
4. 新增 package/editor 内容不破坏 `Assets/FlowScope` 当前开发模式。
5. 文档说明安装、接入、验证、已知限制和后续迁移边界。
6. 所有提交信息使用中文。

## 第一阶段之后

第一阶段完成后进入 P2 第二阶段：本地 package 试迁移。

第二阶段才开始创建真正 package 目录雏形并用本地 path 在干净 Unity 项目验证安装。Runtime、Addressables、Samples、Tests 的物理迁移应分批进行，不应在第一阶段一次性搬迁。