172 lines
7.2 KiB
Markdown
172 lines
7.2 KiB
Markdown
# 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 的物理迁移应分批进行，不应在第一阶段一次性搬迁。
|