# 结算结果传递(RoomEndResult)设计

日期:2026-07-09
状态:已与用户确认(方案 A:`IRoomCtx.EndRoom` 加带结果重载)

## 背景 / 问题

对局结束后框架结算弹框只能显示"游戏结束 + 房间号":网关 `ServerLoop.OnRoomEnded` 硬编码
`RoomEndMsg { WinnerPlayerId = 0, ResultBlob = empty }`(ServerLoop.cs:412),而游戏逻辑
(`RpsServerRoom`)的胜负与比分只写了日志,框架 `IRoomCtx.EndRoom()` 没有传结果的通道。
这是既有占位欠账(见 minigame 进度备忘"`RoomEndMsg.WinnerPlayerId=0` 是占位")。

协议层 `RoomEndMsg`(FrameworkMessages.cs:219)早已有 `WinnerPlayerId` + `ResultBlob`
两字段,客户端 `MiniGameHost.ShowResultDialog` 也已按这两字段渲染——缺的只是服务端从
游戏逻辑到网关的管道。**零协议改动。**

用户确认的结算内容:**胜负 + 比分**(标题胜利/失败/平局,正文最终比分文本)。

## 设计

### 1. 共享接口(`Client/Assets/Framework/Shared/`)

(实施修订:`RoomEndResult` 按仓库 DTO 惯例落在 `GameTypes.cs`,接口重载在 `IGameServerRoom.cs`。)

```csharp
public sealed class RoomEndResult
{
    public int WinnerPlayerId; // 0 = 平局/无胜者(与 RoomEndMsg 语义一致)
    public byte[] ResultBlob;  // 小游戏自定义结算数据;约定:放 UTF-8 文本时框架弹框直接显示
}

public interface IRoomCtx
{
    // ...现有成员不变...
    void EndRoom();                      // 保留:等价 EndRoom(null)
    void EndRoom(RoomEndResult result);  // 新增
}
```

兼容性:游戏 DLL 只**消费**不**实现** `IRoomCtx`,给接口加成员不破坏已发布旧模块
(旧模块调无参版 → 结果为 null → 弹框行为同现状)。实现方仅框架内 `RoomCtx` 与测试
fake,一起改。不使用默认接口方法(避开 HybridCLR/mono DIM 运行时风险)。

### 2. 服务端宿主(`Server/Server.Host/`)

- `RoomCtx`:构造参数 `Action endRoom` → `Action<RoomEndResult>`;
  `EndRoom()` → 回调(null);`EndRoom(result)` → 回调(result)。
- `Room`:`RequestEnd(RoomEndResult result)` 存入 `public RoomEndResult EndResult`
  属性(多次调用以最后一次为准);保留无参 `RequestEnd()` = 传 null。
- `RoomHost.TickAll` 返回 `IReadOnlyList<string>` → `IReadOnlyList<EndedRoom>`:
  `public readonly struct EndedRoom { public string RoomId; public RoomEndResult Result; }`,
  在 `ReleaseRoom` 前捕获 `room.EndResult`。现有使用 TickAll 的调用点与测试同步更新。
- "Start 即结束"路径:`ServerLoop.CreateRoomForSeats` 持有 `Room` 引用,直接读
  `room.EndResult`。

### 3. 网关(`Server/Gateway/ServerLoop.cs`)

`OnRoomEnded(string roomId, RoomEndResult result)`:

```csharp
var msg = new RoomEndMsg {
    WinnerPlayerId = result?.WinnerPlayerId ?? 0,
    ResultBlob     = result?.ResultBlob ?? Array.Empty<byte>()
};
```

### 4. RPS 服务端(`Server/games-src/RPS/RPS.Server/RpsServerRoom.cs`)

- `OnRoomStart` 记录 `_pidOfSeat[2]`(座位→pid;AI 玩家也有 pid)。
- 结束时(`Phase == Finished`):
  - `Winner == 2`(平局)→ `WinnerPlayerId = 0`,文本 `"平局 {s0} : {s1}"`;
  - 否则 → `WinnerPlayerId = _pidOfSeat[winner]`,文本 `"最终比分 {s0} : {s1}"`。
  - 文本按座位序,双端同文本(广播);UTF-8 编码进 `ResultBlob`,调 `EndRoom(result)`。

### 5. 客户端弹框(`Client/Assets/Script/xmain/MiniGame/MiniGameHost.cs`,框架层)

RPS 客户端零改动。

- `ResultTitle`:
  - `winner == _selfPlayerId`(非 0)→ "胜利";
  - `winner != 0` 且非自己 → "失败";
  - `winner == 0`:blob 有文本 → "平局";blob 空 → "游戏结束"
    (旧模块/异常结束无结果时保持中性标题,不误报平局)。
- `ResultMessage`:blob 解出非空文本 → 只显示 blob 文本(去掉裸 pid 行);
  空 → 维持现状回退(房间号)。

## 测试(TDD)

- **Server.Host.Tests**:①`RoomCtx.EndRoom(result)` → `Room.EndResult` 捕获;
  ②`TickAll` 返回的 `EndedRoom` 携带结果;③未设结果时 `Result == null`;
  ④`RpsServerRoomTests`:对局打完,以正确胜者 pid 与比分文本调了 `EndRoom`
  (含平局→pid 0 分支)。
- **Gateway.Tests**:RPS 端到端断言收到的 RoomEnd 帧 `WinnerPlayerId`/`ResultBlob`
  非占位;`build-test-games.sh` 重建 rps 测试夹具(RPS.Server 源码变更)。
- **客户端**(本环境无 Unity):IDE 诊断/csc 0 错;用户 Unity Play 一局人工核对弹框
  (胜利/失败/平局标题 + 比分文本,点确定正常退出)。

## 部署影响

- 服务端:网关 + Server.Host 一体重编部署即生效。
- RPS 服务器模块:须经发布流水线重发 `deploy/minigame/rps/<ver>/`
  (旧包兼容不崩,只是弹框无结算内容)。
- 客户端:`XWorld.Link` 与 `XWorld.Framework.Shared` 热更 DLL 重出。

## 不做(YAGNI)

- `SetResult()` 两步接口(无场景);
- 结构化结算(每回合出招记录等,用户选了胜负+比分);
- 宿主强制结束时的结果通道(结果恒 null → 弹框中性"游戏结束",可接受)。