将 ShopController 构建 Context 的功能迁移到 partial class 里，并调整了部分构建逻辑

2026-06-17 11:57:46 +08:00
parent 44f6729c1a
commit 43f81c8926
6 changed files with 344 additions and 217 deletions
@@ -308,6 +308,140 @@ SepCore.Presentation（Controller + Context + View）
 - UI 专用事件命名应体现模块归属，避免语义过宽
 - 同一 UI 可以按需要使用“多个精细事件”或“单一事件 + 子类型/按钮编号”的方式建模；例如当前 Dialog 使用 `DialogEventArgs + ButtonId`

+### 6.4 UseCase 与编排层（Procedure）的通信方式
+
+**推荐方式：接口式引用（主要方式）**
+
+UseCase 与编排层（Procedure）的通信采用 **依赖倒置原则（DIP）**，通过接口进行解耦。
+
+#### 核心模式
+
+```text
+Procedure (编排层)
+   ↓ 实现接口
+IProcedureXXX
+   ↓ 注入（构造函数传 this 作为接口）
+UseCase
+   ↓ 通过接口回调
+Procedure.ConfirmXXX(...)
+```
+
+#### 实现规范
+
+1. **定义接口契约**
+   - 命名：`IProcedureXXX`（`XXX` 对应用户或 UI 名称）
+   - 位置：`Runtime/ProcedureInterface/` 目录
+   - 内容：只包含 UI 真正需要的方法，遵循接口隔离原则（ISP）
+
+   ```csharp
+   // 示例：IProcedureMenu.cs
+   namespace SepCore.Procedure
+   {
+       public interface IProcedureMenu
+       {
+           void ConfirmSelectRole(int roleId);
+       }
+   }
+   ```
+
+2. **Procedure 实现接口**
+   - Procedure 类实现对应接口
+   - 在 `OnEnter` 中创建 UseCase 并注入自身（`this`）
+   - 接口方法中实现流程编排（状态变更、场景切换、数据传递等）
+
+   ```csharp
+   // 示例：ProcedureMenu.cs
+   public class ProcedureMenu : ProcedureBase, IProcedureMenu
+   {
+       private bool _startGame = false;
+       private int _selectedRoleId = 0;
+
+       public void ConfirmSelectRole(int roleId)
+       {
+           _selectedRoleId = roleId;
+           _startGame = true;
+       }
+
+       protected override void OnEnter(ProcedureOwner procedureOwner)
+       {
+           base.OnEnter(procedureOwner);
+           var useCase = new SelectRoleUseCase(this); // 注入接口
+           GameEntry.UIRouter.BindUIUseCase(UIFormType.SelectRoleForm, useCase);
+       }
+   }
+   ```
+
+3. **UseCase 接收接口**
+   - UseCase 构造函数只接收接口类型，不直接依赖具体 Procedure
+   - 业务完成时通过接口回调编排层
+   - UseCase 内部不保存 Procedure 的具体引用
+
+   ```csharp
+   // 示例：SelectRoleUseCase.cs
+   public class SelectRoleUseCase : IUIUseCase
+   {
+       private readonly IProcedureMenu _procedureMenu; // 依赖接口，而非具体类
+
+       public SelectRoleUseCase(IProcedureMenu procedureMenu)
+       {
+           _procedureMenu = procedureMenu;
+       }
+
+       public bool ConfirmSelectedRole()
+       {
+           // ... 业务校验逻辑 ...
+           _procedureMenu.ConfirmSelectRole(SelectedRoleId); // 通过接口回调
+           return true;
+       }
+   }
+   ```
+
+#### 接口式引用的核心优势
+
+| 优势 | 说明 |
+|------|------|
+| **依赖倒置** | UseCase 依赖抽象接口，而非具体实现，符合 DIP 原则 |
+| **接口隔离** | 接口只暴露 UI 需要的能力，Procedure 内部能力不泄露 |
+| **可测试性** | 单元测试时可用 Mock 实现接口，无需启动整个 Procedure |
+| **复用性** | 不同 Procedure 可实现同一接口，复用同一个 UseCase |
+| **边界清晰** | 明确定义 UI 对编排层的操作权限，避免 UseCase 越权 |
+| **可扩展性** | 新增回调方法时直接在接口添加，无需修改构造函数签名 |
+
+#### 备选方式：委托回调（快速实现）
+
+对于简单场景或快速原型，可使用 `Action` / `Func` 委托作为轻量替代：
+
+```csharp
+// 委托方式示例（适用于单一回调场景）
+public class LevelUpUseCase : IUIUseCase
+{
+    private readonly Action _onCompleted;
+
+    public LevelUpUseCase(Player player, Action onCompleted)
+    {
+        _onCompleted = onCompleted;
+    }
+}
+```
+
+**适用场景**：
+- 只有 1-2 个简单回调
+- 临时功能或快速原型
+- 回调逻辑不需要复用
+
+**注意**：当回调超过 2 个或语义复杂时，应升级为接口方式。
+
+#### 决策矩阵
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 复杂流程，多个回调点 | 接口式引用 ✅ |
+| 需要单元测试 UseCase | 接口式引用 ✅ |
+| 多个 Procedure 复用同一 UI | 接口式引用 ✅ |
+| 单一简单回调（如关闭通知） | 委托回调 |
+| 临时功能或快速原型 | 委托回调 |
+| 回调参数复杂（多参数、泛型） | 接口式引用 ✅ |
+
 ## 7. 标准交互流程

 ### 7.1 有 UseCase 的标准流程