完成 P2 第一阶段包与编辑器准备

This commit is contained in:
JSD\13999
2026-06-04 11:33:59 +08:00
parent 7cde2cfaec
commit 37e6d4ca57
49 changed files with 1996 additions and 2 deletions

View File

@@ -0,0 +1,77 @@
# FlowScope Addressables 集成验收记录
日期2026-06-04
## 验收目的
本文用于补齐 P2 第一阶段的 Addressables 真实集成验收缺口。目标不是重新设计资源系统,而是确认当前 `FlowScope.Addressables.AddressablesResourceBackend` 能通过真实 Addressables key 完成加载、释放和错误诊断。
## 项目配置
已确认:
- `My project/Packages/manifest.json` 包含 `com.unity.addressables`,当前版本为 `1.21.21`
- `My project/Assets/FlowScope/Addressables/FlowScope.Addressables.asmdef` 引用 `FlowScope.Runtime``Unity.Addressables``Unity.ResourceManager`
- `My project/Assets/FlowScope/Tests/PlayMode/FlowScope.Tests.PlayMode.asmdef` 引用 `FlowScope.Addressables`
- 当前项目已生成 `My project/Assets/AddressableAssetsData`
- `My project/ProjectSettings/EditorBuildSettings.asset` 已登记 Addressables settings config object。
## 测试资源
真实 Addressables 测试资源:
- 路径:`Assets/FlowScope/Tests/PlayMode/Resources_moved/Fixtures/Addressables/FlowScopeAddressablesText.txt`
- 内容:`FlowScope Addressables Acceptance`
- GUID`7e04733ce9dab74459592d3bd99fcafd`
- Addressables group`Default Local Group`
- Addressables key`FlowScope.Tests.Addressables.Text`
- 资源类型:`TextAsset`
`Default Local Group.asset` 中已确认存在:
```yaml
m_GUID: 7e04733ce9dab74459592d3bd99fcafd
m_Address: FlowScope.Tests.Addressables.Text
```
## 自动化验收
已在 `My project/Assets/FlowScope/Tests/PlayMode/Resources/AddressablesResourceBackendTests.cs` 补充真实 PlayMode 集成测试:
- `LoadAsync_WithRealTextAssetKey_LoadsTextAsset`
- `LoadAsync_WithMissingKey_ThrowsDiagnosticException`
- `LoadAsync_WithMismatchedType_ThrowsDiagnosticException`
覆盖范围:
- `AddressablesResourceBackend.LoadAsync<TextAsset>` 能通过真实 key 加载真实 `TextAsset`
- `AddressablesResourceBackend.Release` 能释放已加载资源。
- 缺失 key 会产生可捕获诊断异常,并包含缺失 key。
- 类型不匹配会产生可捕获诊断异常,并包含 key 和请求类型。
本轮同时修复了 `AddressablesResourceBackend.LoadAsync<T>` 的失败状态处理:当 Addressables handle 存在 `OperationException``Status` 不是 `Succeeded``Result``null`backend 会抛出包含 key、请求类型和 backend 名称的 `InvalidOperationException`
## 验收结果
用户已在 Unity Test Runner 中执行全量 EditMode / PlayMode结果全绿。
本轮针对 Addressables 集成用例的最终结果:
| 项目 | 结果 | 证据 |
| --- | --- | --- |
| 真实 `LoadAsync<TextAsset>` | 通过 | `FlowScope.Tests.Addressables.Text` 加载真实 `TextAsset` |
| `Release<TextAsset>` | 通过 | 成功释放已加载资源,未产生未处理日志 |
| 缺失 key 诊断 | 通过 | `FlowScope.Tests.Addressables.Missing` 产生可捕获异常 |
| 类型不匹配诊断 | 通过 | `TextAsset` key 以 `GameObject` 请求时产生可捕获异常 |
| Unity Test Runner EditMode | 通过 | 用户反馈全量 EditMode 全绿 |
| Unity Test Runner PlayMode | 通过 | 用户反馈全量 PlayMode 全绿 |
## 剩余注意事项
- 当前 Addressables 测试资源位于 `Resources_moved` 路径下;这是本轮真实验收的有效路径,但后续 package 迁移时应统一测试资源目录命名。
- `Assets/FlowScope/Tests/PlayMode/Resources/Fixtures` 当前只剩空目录 meta属于提交前清理候选。
- 当前验收仍在主项目内完成P2 后续 package 阶段还需要在干净 Unity 项目中验证本地 package path 或 Git URL 安装。
## 结论
P2 第一阶段的 Addressables 真实集成验收已完成。当前不再只是编译通过或人工步骤文档,而是已有真实 PlayMode 自动化测试覆盖成功加载、释放、缺失 key 和类型不匹配诊断。

View File

@@ -0,0 +1,171 @@
# 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 APackage / 安装接入文档
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 BAddressables 真实验收
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 CEditor 最小诊断入口
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 的物理迁移应分批进行,不应在第一阶段一次性搬迁。

View File

@@ -0,0 +1,180 @@
# FlowScope P2 第一阶段完成报告
日期2026-06-04
## 范围
本阶段根据 `docs/requirements/p2-package-editor-requirements.md` 执行第一轮 P2 准备工作。范围限定为:
- 锁定 P0/P1 当前基线。
- 建立 package 目标结构与迁移边界文档。
- 编写安装与最小接入文档。
- 补 Addressables 真实验收入口。
- 添加最小 Editor 诊断入口。
- 整理 MainMenuP0 样例说明。
本阶段没有重写 P0/P1 Runtime 生命周期,没有搬迁 `Assets/FlowScope`,没有创建正式 package 根目录。Addressables 项目设置由用户准备测试资源时生成,本轮仅接入测试、修复 backend 失败诊断并记录验收结果。
## 已完成
### 1. 基线审查
新增:
- `docs/reviews/p2-phase1-baseline-audit.md`
内容包括:
- 当前分支与工作树状态。
- P0/P1 Runtime、Addressables、Samples、Tests 的现状。
- Package / Editor 缺口。
- Addressables 真实验收缺口。
- P2 第一阶段并行任务边界。
- 第一阶段完成 Gate 和下一阶段方向。
### 2. Package 结构与安装文档
新增:
- `docs/guides/flowscope-package-layout.md`
- `docs/guides/flowscope-installation.md`
已覆盖:
- 目标 package 结构:`package.json``Runtime``Addressables``Editor``Samples~``Tests``Documentation~`
- 第一阶段暂不搬迁 `Assets/FlowScope` 的原因。
- asmdef 依赖方向和禁止反向依赖。
- 本地 package path、Git URL、项目内 Assets 开发模式。
- 基于当前真实 API 的最小 Bootstrap 示例。
- 常见误用与当前限制。
### 3. Addressables 验收入口
新增:
- `docs/reviews/addressables-integration-acceptance.md`
结论:
- 当前项目有 `com.unity.addressables``FlowScope.Addressables` asmdef。
- 当前项目已有 `Assets/AddressableAssetsData`、默认 Addressables settings、`Default Local Group` 和可复用测试 key。
- 已新增真实 PlayMode 自动化验收,覆盖真实 `TextAsset` 加载、释放、缺失 key 诊断和类型不匹配诊断。
剩余缺口:
- 当前 Addressables 测试资源路径为 `Assets/FlowScope/Tests/PlayMode/Resources_moved/Fixtures/Addressables/FlowScopeAddressablesText.txt`,后续 package 迁移时应统一测试资源目录命名。
- `Assets/FlowScope/Tests/PlayMode/Resources/Fixtures` 当前只剩空目录 meta属于提交前清理候选。
### 4. Editor 最小诊断入口
新增:
- `My project/Assets/FlowScope/Editor.meta`
- `My project/Assets/FlowScope/Editor/FlowScope.Editor.asmdef`
- `My project/Assets/FlowScope/Editor/FlowScope.Editor.asmdef.meta`
- `My project/Assets/FlowScope/Editor/FlowScopeDiagnosticsWindow.cs`
- `My project/Assets/FlowScope/Editor/FlowScopeDiagnosticsWindow.cs.meta`
能力:
- 菜单入口:`Tools/FlowScope/Diagnostics`
- 只读检查,不自动生成、移动、删除或修复用户资源。
- 检查 `com.unity.addressables` package、Runtime asmdef、Addressables asmdef、MainMenuP0 scene、MainMenuPanel prefab。
- Addressables package 状态通过 `UnityEditor.PackageManager.Client.List(true)` 异步刷新,不阻塞 Editor。
### 5. MainMenuP0 样例说明
新增:
- `My project/Assets/FlowScope/Samples/MainMenuP0/README.md`
- `My project/Assets/FlowScope/Samples/MainMenuP0/README.md.meta`
内容包括:
- 样例目的。
- 当前仍保留在 `Assets/FlowScope/Samples/MainMenuP0` 的原因。
- 后续迁移到 `Samples~/MainMenuP0` 的候选路径。
- 运行方式、验收点、自动化测试位置和已知限制。
## 验证结果
### Unity batchmode 导入 / 编译
已执行:
```powershell
& 'C:\Program Files\Unity\Hub\Editor\2022.3.62f2c1\Editor\Unity.exe' -batchmode -quit -projectPath 'C:\Users\13999\Documents\FlowScope\My project' -logFile 'C:\tmp\flowscope-p2-phase1-editor-compile.log'
```
结果:
- Unity 导入新增 Editor 文件。
- 生成 `My project\FlowScope.Editor.csproj`
- 日志中未发现 `error CS``Compilation failed``Scripts have compiler errors`
### generated csproj build
已执行:
```powershell
dotnet build "My project\FlowScope.Editor.csproj" --no-restore
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.Editor.csproj`0 error。
- `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``System.Threading.Tasks.Extensions`
### Unity Test Runner
已执行:
- 全量 EditMode。
- 全量 PlayMode。
结果:
- 用户反馈全量 EditMode / PlayMode 全绿。
- `AddressablesResourceBackendTests` 已覆盖真实 Addressables key`FlowScope.Tests.Addressables.Text`
- 缺失 key 和类型不匹配路径已通过可捕获 backend 诊断异常验收。
### 静态检查
已执行:
```powershell
rg -n "<占位词扫描表达式>" <本阶段新增文档与 Editor 脚本>
git diff --check
```
结果:
- 未发现占位词命中。
- `git diff --check` 无 whitespace error。
## 未完成 Gate
以下事项不在本阶段内完成,但必须在 P2 后续阶段继续追踪:
1. 尚未创建正式 package 根目录和 `package.json` 文件。
2. 尚未在干净 Unity 项目中验证本地 package path 或 Git URL 安装。
3. 尚未实际打开 `Tools/FlowScope/Diagnostics` 做人工 UI 检查。
4. Addressables 测试资源目录命名仍需在 package 迁移前统一。
## 下一阶段建议
进入 P2 第二阶段:本地 package 试迁移。
建议顺序:
1. 创建 `Packages/com.flowscope.gamecore` 和最小 `package.json`
2. 先复制或镜像 Runtime 到 package 目录,不删除 `Assets/FlowScope`
3. 在当前项目和一个干净 Unity 项目中验证本地 package path。
4. 整理 Addressables 测试资源目录,再迁移 package 内 Tests。
5. 再考虑 `Samples~/MainMenuP0` 和 Tests 的分批迁移。