# 服务端 WebSocket 网关 + Session + 路由（子项目 2b-1，传输核心）实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 给 2a 的 `RoomHost` 接上真实网络：一个 Kestrel WebSocket 网关，让单个玩家通过真 WS 连接 → 入房（单人 Hello）→ 持续收到状态快照 → 房间结束，并支持断线重连窗口；全部跑在**单线程 tick actor**（无锁、确定性）上。

**Architecture:** ASP.NET Core Kestrel 暴露 `/ws?pid=<id>` 端点。每个连接跑收/发两个异步循环：收到的 WS 消息用 `FrameCodec` 解码后**只把命令入队**（不碰 RoomHost）；发送侧有独立出站队列。一个 `ServerLoop`（actor）独占 RoomHost 与 SessionManager：它排空命令队列、按 tickRateHz 调 `RoomHost.TickAll`、把房间广播经 `IRoomOutput` 汇成 Game 通道帧塞回各玩家连接、并扫描重连窗口过期会话。actor 暴露 `Submit(cmd)`（线程安全）与 `DrainAndTick(dt)`（测试直调；真实循环周期性调它），使路由/房间生命周期逻辑可确定性单测，真 socket 管道走真 Kestrel 集成测试。

**Tech Stack:** C# / net10.0 · ASP.NET Core Kestrel WebSockets（`FrameworkReference Microsoft.AspNetCore.App`）· `System.Threading.Channels`（命令队列 + 每连接出站队列）· `System.Net.WebSockets.ClientWebSocket`（集成测试）· 复用子项目 1 的 `FrameCodec`/`FrameworkMessages`/`Frame`/`Channel` 与子项目 2a 的 `RoomHost`/`GameModuleRegistry`/`Room`。

---

## 背景与约定（务必遵守）

- 上游设计：`docs/superpowers/specs/2026-06-18-csharp-hotfix-minigame-architecture-design.md` §4.1（接入/路由/Session）。本计划落地 §9 第 2 步的网络前端部分（**传输核心**）。
- 依赖：子项目 1（`Server/Framework.Shared`，契约 + 协议）与子项目 2a（`Server/Server.Host`，`RoomHost`/`Room`/`GameModuleRegistry`/`GameModuleLoader`/`RoomCtx`/`IRoomOutput`/能力实现）均已完成，`dotnet test Server/Server.sln` 当前 73/73。
- **无 git**：跳过所有 git 步骤，其余照常。
- 工作目录 `D:/UD/AI/AIC#Project`，bash on Windows（正斜杠、`/dev/null`）。`dotnet` SDK 10.0.201（net10 自带 ASP.NET Core 共享框架）。
- **本计划不做**：匹配（按 (gameId,version) 分桶、凑齐 N 人、15s 超时 AI 兜底）与多人/AI ——这些随 RPS 重写（§9 第 5 步，届时有真正的 2 人游戏）一起做。本计划用单人 Hello 验证整条网络管道。

## 并发模型（单线程 tick actor，无锁）

- **网络线程**（每连接的收循环）：只解码帧 + `ServerLoop.Submit(cmd)`（写线程安全 Channel）。绝不直接调用 RoomHost/SessionManager。
- **actor 单线程**：`DrainAndTick(dt)` 内排空命令、处理路由、`RoomHost.TickAll`、发 RoomEnd、扫过期会话。RoomHost/SessionManager 只在此处被改 → 天然无锁、房间内确定性。
- **出站**：actor 经 `IClientConnection.Send(frame)` 把帧写进**该连接的出站 Channel**（线程安全）；连接的发循环排空该队列并 `WebSocket.SendAsync`（每 socket 仅一个发循环 → 发送天然串行化）。

## 命名与依赖

- 网关项目 `Server/Gateway/`，程序集 `XWorld.Server.Gateway`，命名空间 `XWorld.Server.Gateway`，net10.0，`FrameworkReference Microsoft.AspNetCore.App` + 引用 `Server.Host`。
- 命名冲突处理：协议帧通道枚举是 `XWorld.Framework.Protocol.Channel`；`System.Threading.Channels.Channel` 用别名 `using ChannelsNS = System.Threading.Channels;` 引入，写作 `ChannelsNS.Channel<T>`，而 `Channel.Framework`/`Channel.Game` 指协议枚举（`using XWorld.Framework.Protocol;`）。

## 文件结构

网关库 `Server/Gateway/`：

| 文件 | 职责 |
|---|---|
| `Gateway.csproj` | net10.0，FrameworkReference ASP.NET Core，引用 Server.Host |
| `IClientConnection.cs` | 出站抽象：`int PlayerId`、`void Send(byte[] frame)`（非阻塞入队） |
| `ServerCommand.cs` | actor 命令：Connect / Disconnect / Frame |
| `Session.cs` | 单会话状态：pid、当前连接、是否在线、所在房间、断线 tick |
| `SessionManager.cs` | pid→Session；连接/重连/断线/查连接/绑房/过期扫描 |
| `RoomOutputSink.cs` | `IRoomOutput` → 经 SessionManager 解析连接，包成 Game 通道帧入队 |
| `ServerLoop.cs` | actor：命令队列 + RoomHost + Session；Submit/DrainAndTick/路由/房间结束/心跳/RunAsync |
| `Connection.cs` | WebSocket 包装：收循环（解码帧→Submit FrameCommand）+ 发循环（排空出站→SendAsync） |
| `GameServerHost.cs` | 建 Kestrel WebApplication + `/ws` 端点 + 启停 + 解析实际端口 |

测试 `Server/Gateway.Tests/`：

| 文件 | 职责 |
|---|---|
| `Gateway.Tests.csproj` | net10.0 + xUnit，引用 Gateway，复用 Server.Host.Tests 的 TestGames |
| `Support/FakeConnection.cs` | `IClientConnection` 假实现，记录发出的帧 |
| `Support/TestGames.cs` | 定位输出目录的 TestGames 根 |
| `Support/WsTestClient.cs` | 集成测试用 ClientWebSocket 封装（连/发帧/带超时收帧/解码） |
| `SessionManagerTests.cs` / `RoomOutputSinkTests.cs` / `ServerLoopTests.cs` / `GatewayEndToEndTests.cs` | 见各任务 |

被修改：

| 文件 | 改动 |
|---|---|
| `Server/Server.Host/RoomHost.cs` | `TickAll(dt)` 改为返回本 tick 结束的 roomId 列表（向后兼容：旧调用忽略返回值即可） |

---

## Task 1: 修改 RoomHost.TickAll 返回本 tick 结束的房间（Server.Host）

**Files:**
- Modify: `Server/Server.Host/RoomHost.cs`
- Test: `Server/Server.Host.Tests/RoomHostTests.cs`（追加一个断言用例）

actor 需要知道哪些房间在本 tick 结束，以便给玩家发 RoomEnd 并解绑会话。

- [ ] **Step 1: 先写失败测试（追加到 `RoomHostTests.cs` 类内）**

```csharp
        [Fact]
        public void TickAll_ReturnsEndedRoomIds()
        {
            var host = NewHost();
            var cfg = new RoomConfig { GameId = "hello", Version = 1, Seed = 1, PlayerCount = 1 };
            host.CreateRoom("E", "hello", 1, cfg, Players, new Capture());

            var tick1 = host.TickAll(1f);
            var tick2 = host.TickAll(1f);
            var tick3 = host.TickAll(1f); // Hello 第 3 tick 结束
            Assert.Empty(tick1);          // 前两 tick 不应有结束房间
            Assert.Empty(tick2);
            Assert.Contains("E", tick3);  // 第 3 tick 才结束
        }
```

- [ ] **Step 2: 运行，确认红**

Run: `bash Server/build-test-games.sh && dotnet test Server/Server.sln --filter RoomHostTests`
Expected: 编译失败（`TickAll` 当前返回 void，`ended = host.TickAll(...)` 无法赋值）。

- [ ] **Step 3: 修改 `RoomHost.TickAll` 返回类型**

把 `RoomHost.cs` 中的 `TickAll` 方法整体替换为：

```csharp
        public IReadOnlyList<string> TickAll(float dt)
        {
            List<string> ended = null;
            foreach (var kv in _rooms)
            {
                var room = kv.Value.Room;
                if (!room.IsActive) { (ended ??= new List<string>()).Add(kv.Key); continue; }
                room.Tick(dt);
                if (!room.IsActive) (ended ??= new List<string>()).Add(kv.Key);
            }
            if (ended != null)
                foreach (var id in ended) ReleaseRoom(id);
            return ended ?? (IReadOnlyList<string>)System.Array.Empty<string>();
        }
```

其余方法不变。（旧测试 `host.TickAll(1f)` 忽略返回值，仍编译通过。）

- [ ] **Step 4: 运行，确认绿**

Run: `bash Server/build-test-games.sh && dotnet test Server/Server.sln --filter RoomHostTests`
Expected: PASS（含新用例）。

---

## Task 2: 搭建网关项目与测试工程

**Files:**
- Create: `Server/Gateway/Gateway.csproj`
- Create: `Server/Gateway.Tests/Gateway.Tests.csproj`
- Create: `Server/Gateway.Tests/Support/TestGames.cs`
- Modify: `Server/Server.sln`

- [ ] **Step 1: 生成工程并并入解决方案**

```bash
dotnet new classlib -n Gateway -o Server/Gateway -f net10.0
dotnet new xunit    -n Gateway.Tests -o Server/Gateway.Tests
rm -f Server/Gateway/Class1.cs Server/Gateway.Tests/UnitTest1.cs
dotnet sln Server/Server.sln add Server/Gateway/Gateway.csproj
dotnet sln Server/Server.sln add Server/Gateway.Tests/Gateway.Tests.csproj
mkdir -p Server/Gateway.Tests/Support
```

- [ ] **Step 2: 写 `Server/Gateway/Gateway.csproj`**

```xml
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>disable</Nullable>
    <ImplicitUsings>disable</ImplicitUsings>
    <AssemblyName>XWorld.Server.Gateway</AssemblyName>
    <RootNamespace>XWorld.Server.Gateway</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <ProjectReference Include="..\Server.Host\Server.Host.csproj" />
  </ItemGroup>

</Project>
```

- [ ] **Step 3: 配置 `Server/Gateway.Tests/Gateway.Tests.csproj`**

在 `</Project>` 前加入（模板已含 xUnit 包；补 `Nullable disable`、引用、TestGames 内容复用）。先把 `<PropertyGroup>` 里加一行 `<Nullable>disable</Nullable>`（若模板默认 enable），再加：

```xml
  <ItemGroup>
    <ProjectReference Include="..\Gateway\Gateway.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- 复用 2a 已构建的 Hello 夹具（由 build-test-games.sh 生成到 Server.Host.Tests/TestGames） -->
    <Content Include="..\Server.Host.Tests\TestGames\**\*">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <Link>TestGames\%(RecursiveDir)%(Filename)%(Extension)</Link>
    </Content>
  </ItemGroup>
```

- [ ] **Step 4: 写 `Server/Gateway.Tests/Support/TestGames.cs`**

```csharp
using System;
using System.IO;

namespace XWorld.Server.Gateway.Tests
{
    internal static class TestGames
    {
        // 前置条件：先运行 build-test-games.sh 生成 Server.Host.Tests/TestGames（本工程复用之）
        public static string Root => Path.Combine(AppContext.BaseDirectory, "TestGames");
    }
}
```

- [ ] **Step 5: 构建确认（夹具须先生成）**

Run: `bash Server/build-test-games.sh && dotnet build Server/Server.sln -v minimal`
Expected: `Build succeeded`，0 error。然后 `ls "Server/Gateway.Tests/bin/Debug/net10.0/TestGames/hello/1"` 列出 `Hello.Core.dll`、`Hello.Server.dll`、`game.json`。

---

## Task 3: 出站抽象 + 会话管理（单元 TDD）

**Files:**
- Create: `Server/Gateway/IClientConnection.cs`
- Create: `Server/Gateway/Session.cs`
- Create: `Server/Gateway/SessionManager.cs`
- Create: `Server/Gateway.Tests/Support/FakeConnection.cs`
- Test: `Server/Gateway.Tests/SessionManagerTests.cs`

- [ ] **Step 1: 写 `Support/FakeConnection.cs`**

```csharp
using System.Collections.Generic;

namespace XWorld.Server.Gateway.Tests
{
    internal sealed class FakeConnection : IClientConnection
    {
        public int PlayerId { get; }
        public List<byte[]> Sent { get; } = new List<byte[]>();
        public FakeConnection(int playerId) { PlayerId = playerId; }
        public void Send(byte[] frame) => Sent.Add(frame);
    }
}
```

- [ ] **Step 2: 写失败测试 `SessionManagerTests.cs`**

```csharp
using Xunit;
using XWorld.Server.Gateway;

namespace XWorld.Server.Gateway.Tests
{
    public class SessionManagerTests
    {
        [Fact]
        public void Connect_NewPid_CreatesConnectedSession()
        {
            var sm = new SessionManager();
            var c = new FakeConnection(1);
            sm.OnConnect(1, c);
            Assert.True(sm.IsConnected(1));
            Assert.Same(c, sm.GetConnection(1));
        }

        [Fact]
        public void Reconnect_SamePid_RebindsToNewConnection()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            var c2 = new FakeConnection(1);
            sm.OnConnect(1, c1);
            sm.OnDisconnect(1, c1, currentTick: 5);
            Assert.False(sm.IsConnected(1));
            Assert.Null(sm.GetConnection(1));

            sm.OnConnect(1, c2);              // 重连
            Assert.True(sm.IsConnected(1));
            Assert.Same(c2, sm.GetConnection(1)); // 路由到新连接
        }

        [Fact]
        public void StaleDisconnect_AfterReconnect_DoesNotClobber()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            var c2 = new FakeConnection(1);
            sm.OnConnect(1, c1);
            sm.OnConnect(1, c2);                 // 已重连到 c2
            sm.OnDisconnect(1, c1, currentTick: 9); // 旧连接 c1 的迟到断线不应清掉 c2
            Assert.True(sm.IsConnected(1));
            Assert.Same(c2, sm.GetConnection(1));
        }

        [Fact]
        public void RoomBinding_RoundTrips()
        {
            var sm = new SessionManager();
            sm.OnConnect(1, new FakeConnection(1));
            sm.Get(1).RoomId = "r1";
            Assert.Equal("r1", sm.Get(1).RoomId);
        }

        [Fact]
        public void SweepExpired_RemovesSessionsPastWindow()
        {
            var sm = new SessionManager();
            var conn = new FakeConnection(1);
            sm.OnConnect(1, conn);
            sm.OnDisconnect(1, conn, currentTick: 0);

            var none = sm.SweepExpired(currentTick: 3, windowTicks: 5);
            Assert.Empty(none);
            Assert.NotNull(sm.Get(1));

            var removed = sm.SweepExpired(currentTick: 6, windowTicks: 5); // 6-0 > 5
            Assert.Single(removed);
            Assert.Null(sm.Get(1));
        }
    }
}
```

- [ ] **Step 3: 运行，确认红**

Run: `dotnet test Server/Server.sln --filter SessionManagerTests`
Expected: 编译失败（相关类型不存在）。

- [ ] **Step 4: 写 `IClientConnection.cs`**

```csharp
namespace XWorld.Server.Gateway
{
    // actor 把出站帧交给它（非阻塞入队）；生产实现写 WebSocket 出站队列，测试用假实现记录
    public interface IClientConnection
    {
        int PlayerId { get; }
        // frame 在调用后不会被修改：实现可保留该引用（广播会把同一数组发给多个连接）。
        void Send(byte[] frame);
    }
}
```

- [ ] **Step 5: 写 `Session.cs`**

```csharp
namespace XWorld.Server.Gateway
{
    public sealed class Session
    {
        public int PlayerId;
        public IClientConnection Connection; // 当前连接；断线中仍保留会话但 Connected=false
        public bool Connected;
        public string RoomId;                // 所在房间，可空
        public long DisconnectedAtTick;      // 断线时的逻辑 tick，用于窗口过期
    }
}
```

- [ ] **Step 6: 写 `SessionManager.cs`**

```csharp
using System;
using System.Collections.Generic;

namespace XWorld.Server.Gateway
{
    // pid -> Session。只在 actor 线程被改，故无锁。
    public sealed class SessionManager
    {
        private readonly Dictionary<int, Session> _byPid = new Dictionary<int, Session>();

        public Session OnConnect(int pid, IClientConnection conn)
        {
            if (_byPid.TryGetValue(pid, out var s))
            {
                s.Connection = conn;   // 重连：重绑新连接，保留 RoomId
                s.Connected = true;
                return s;
            }
            s = new Session { PlayerId = pid, Connection = conn, Connected = true };
            _byPid[pid] = s;
            return s;
        }

        public void OnDisconnect(int pid, IClientConnection conn, long currentTick)
        {
            // 仅当断的是“当前连接”才标离线，避免旧连接的迟到断线清掉已重连的新连接
            if (_byPid.TryGetValue(pid, out var s) && ReferenceEquals(s.Connection, conn))
            {
                s.Connected = false;
                s.DisconnectedAtTick = currentTick;
            }
        }

        public IClientConnection GetConnection(int pid)
            => _byPid.TryGetValue(pid, out var s) && s.Connected ? s.Connection : null;

        public bool IsConnected(int pid) => _byPid.TryGetValue(pid, out var s) && s.Connected;

        public Session Get(int pid) => _byPid.TryGetValue(pid, out var s) ? s : null;

        /// <summary>移除断线且“严格越过”重连窗口的会话（currentTick - DisconnectedAtTick &gt; windowTicks）。返回被移除的会话；无则空数组。</summary>
        public IReadOnlyList<Session> SweepExpired(long currentTick, long windowTicks)
        {
            List<Session> removed = null;
            foreach (var kv in _byPid)
            {
                var s = kv.Value;
                if (!s.Connected && currentTick - s.DisconnectedAtTick > windowTicks)
                    (removed ??= new List<Session>()).Add(s);
            }
            if (removed != null)
                foreach (var s in removed) _byPid.Remove(s.PlayerId);
            return removed ?? (IReadOnlyList<Session>)Array.Empty<Session>();
        }
    }
}
```

- [ ] **Step 7: 运行，确认绿**

Run: `dotnet test Server/Server.sln --filter SessionManagerTests`
Expected: PASS。

---

## Task 4: 房间出站汇 RoomOutputSink（单元 TDD）

**Files:**
- Create: `Server/Gateway/RoomOutputSink.cs`
- Test: `Server/Gateway.Tests/RoomOutputSinkTests.cs`

- [ ] **Step 1: 写失败测试 `RoomOutputSinkTests.cs`**

```csharp
using System.Collections.Generic;
using Xunit;
using XWorld.Framework;
using XWorld.Framework.Protocol;
using XWorld.Server.Gateway;

namespace XWorld.Server.Gateway.Tests
{
    public class RoomOutputSinkTests
    {
        [Fact]
        public void Broadcast_WrapsInGameChannelFrame_ToConnectedPlayers()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            var c2 = new FakeConnection(2);
            sm.OnConnect(1, c1);
            sm.OnConnect(2, c2);

            var sink = new RoomOutputSink("r1", new List<int> { 1, 2 }, sm);
            sink.Broadcast(new NetMessage(7, new byte[] { 9, 9 }));

            Assert.Single(c1.Sent);
            Assert.Single(c2.Sent);
            var f = FrameCodec.Decode(c1.Sent[0]);
            Assert.Equal(Channel.Game, f.Channel);
            Assert.Equal((ushort)7, f.Opcode);
            Assert.Equal(new byte[] { 9, 9 }, f.Payload);
        }

        [Fact]
        public void Broadcast_SkipsDisconnectedPlayer()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            sm.OnConnect(1, c1);
            sm.OnConnect(2, new FakeConnection(2));
            sm.OnDisconnect(2, sm.GetConnection(2), 0); // 玩家2 离线

            var sink = new RoomOutputSink("r1", new List<int> { 1, 2 }, sm);
            sink.Broadcast(new NetMessage(1, new byte[0]));

            Assert.Single(c1.Sent);     // 仅在线玩家收到，不抛异常
        }

        [Fact]
        public void SendTo_OnlyTargetPlayer()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            var c2 = new FakeConnection(2);
            sm.OnConnect(1, c1);
            sm.OnConnect(2, c2);

            var sink = new RoomOutputSink("r1", new List<int> { 1, 2 }, sm);
            sink.SendTo(2, new NetMessage(5, new byte[] { 1 }));

            Assert.Empty(c1.Sent);
            Assert.Single(c2.Sent);
        }

        [Fact]
        public void Broadcast_AfterReconnect_GoesToNewConnection()
        {
            var sm = new SessionManager();
            var c1 = new FakeConnection(1);
            sm.OnConnect(1, c1);
            var sink = new RoomOutputSink("r1", new List<int> { 1 }, sm);

            sink.Broadcast(new NetMessage(1, new byte[] { 1 }));
            Assert.Single(c1.Sent);

            sm.OnDisconnect(1, c1, 0);           // 断线
            var c2 = new FakeConnection(1);
            sm.OnConnect(1, c2);                  // 重连到新连接

            sink.Broadcast(new NetMessage(1, new byte[] { 2 }));
            Assert.Single(c1.Sent);              // 旧连接不再收到
            Assert.Single(c2.Sent);              // 输出跟随重连到新连接
        }
    }
}
```

- [ ] **Step 2: 运行，确认红**

Run: `dotnet test Server/Server.sln --filter RoomOutputSinkTests`
Expected: 编译失败（`RoomOutputSink` 不存在）。

- [ ] **Step 3: 写 `RoomOutputSink.cs`**

```csharp
using System.Collections.Generic;
using XWorld.Framework;
using XWorld.Framework.Protocol;

namespace XWorld.Server.Gateway
{
    // 房间广播 → 解析各玩家当前连接（重连后自动指向新连接）→ 包成 Game 通道帧入对应出站队列
    public sealed class RoomOutputSink : IRoomOutput
    {
        private readonly string _roomId; // 保留作诊断/日志标识
        private readonly IReadOnlyList<int> _players;
        private readonly SessionManager _sessions;

        public RoomOutputSink(string roomId, IReadOnlyList<int> players, SessionManager sessions)
        {
            _roomId = roomId; _players = players; _sessions = sessions;
        }

        public void Broadcast(NetMessage message)
        {
            byte[] frame = FrameCodec.Encode(new Frame(Channel.Game, message.Opcode, message.Payload));
            foreach (var pid in _players)
                _sessions.GetConnection(pid)?.Send(frame);
        }

        public void SendTo(int playerId, NetMessage message)
        {
            var conn = _sessions.GetConnection(playerId);
            if (conn != null)
                conn.Send(FrameCodec.Encode(new Frame(Channel.Game, message.Opcode, message.Payload)));
        }
    }
}
```

- [ ] **Step 4: 运行，确认绿**

Run: `dotnet test Server/Server.sln --filter RoomOutputSinkTests`
Expected: PASS。

---

## Task 5: actor 核心 ServerLoop（单元 TDD，含路由/房间生命周期/心跳/重连）

**Files:**
- Create: `Server/Gateway/ServerCommand.cs`
- Create: `Server/Gateway/ServerLoop.cs`
- Test: `Server/Gateway.Tests/ServerLoopTests.cs`

> 用 `DrainAndTick(dt)` 直接驱动，配合 `FakeConnection` + 真 Hello 房间（从 TestGames 加载），无需任何 socket，确定性测试 actor 逻辑。

- [ ] **Step 1: 写失败测试 `ServerLoopTests.cs`**

```csharp
using System.Collections.Generic;
using Xunit;
using XWorld.Framework;
using XWorld.Framework.Protocol;
using XWorld.Server.Host;
using XWorld.Server.Gateway;

namespace XWorld.Server.Gateway.Tests
{
    public class ServerLoopTests
    {
        private static ServerLoop NewLoop(long reconnectWindow = 100)
            => new ServerLoop(TestGames.Root, new ConsoleLogger("[loop]"), reconnectWindow);

        private static byte[] JoinFrame(string gameId, int version)
            => FrameCodec.Encode(new Frame(Channel.Framework, (ushort)FrameworkOpcode.MatchRequest,
                new MatchRequestMsg { GameId = gameId, Version = version }.Encode()));

        // 把假连接收到的帧按 (channel, opcode) 分类
        private static List<Frame> Frames(FakeConnection c)
        {
            var list = new List<Frame>();
            foreach (var bytes in c.Sent) list.Add(FrameCodec.Decode(bytes));
            return list;
        }

        private static int LastGameCounter(FakeConnection c)
        {
            int counter = -1;
            foreach (var f in Frames(c))
                if (f.Channel == Channel.Game)
                {
                    var r = new PacketReader(f.Payload);
                    r.ReadVarInt();             // tick
                    counter = r.ReadVarInt();   // counter
                }
            return counter;
        }

        [Fact]
        public void Join_RepliesMatchFound_Snapshots_ThenRoomEnd()
        {
            var loop = NewLoop();
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });

            for (int i = 0; i < 3; i++) loop.DrainAndTick(1f); // Hello 第 3 tick 结束

            var frames = Frames(c);
            // 1 个 MatchFound（Framework）+ 3 个快照（Game）+ 1 个 RoomEnd（Framework）
            Assert.Contains(frames, f => f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.MatchFound);
            Assert.Equal(3, frames.FindAll(f => f.Channel == Channel.Game).Count);
            Assert.Contains(frames, f => f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.RoomEnd);
            Assert.Equal(3, LastGameCounter(c)); // v1 起始 0，3 次 +1
        }

        [Fact]
        public void GameInput_RoutedToRoom_AffectsCounter()
        {
            var loop = NewLoop();
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });

            // 入房后先送一条游戏输入（增量 5），再推进
            var w = new PacketWriter(); w.WriteVarInt(5);
            var inputFrame = new Frame(Channel.Game, 0, w.ToArray());
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = inputFrame });

            loop.DrainAndTick(1f); // 处理 connect+join+input 后 tick 一次：counter = 0 + 5 = 5
            Assert.Equal(5, LastGameCounter(c));
        }

        [Fact]
        public void Heartbeat_IsEchoed()
        {
            var loop = NewLoop();
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            var hb = new HeartbeatMsg { ClientTimeMs = 123456789L };
            loop.Submit(new FrameCommand { PlayerId = 1,
                Frame = new Frame(Channel.Framework, (ushort)FrameworkOpcode.Heartbeat, hb.Encode()) });

            loop.DrainAndTick(0f);

            var echo = Frames(c).Find(f => f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.Heartbeat);
            Assert.NotEqual(default, echo);
            Assert.Equal(123456789L, HeartbeatMsg.Decode(echo.Payload).ClientTimeMs);
        }

        [Fact]
        public void Reconnect_ReroutesRoomOutputToNewConnection()
        {
            var loop = NewLoop(reconnectWindow: 100);
            var c1 = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c1 });
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });
            loop.DrainAndTick(1f); // tick1：c1 收到 MatchFound + 快照1
            Assert.True(c1.Sent.Count >= 2);

            // 断线后重连到新连接
            loop.Submit(new DisconnectCommand { PlayerId = 1, Connection = c1 });
            var c2 = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c2 });
            loop.DrainAndTick(1f); // tick2：快照应发往 c2（房间仍在跑）

            Assert.True(c2.Sent.Count >= 1);
            Assert.Equal(2, LastGameCounter(c2)); // 重连后看到的最新计数 = 2
        }

        [Fact]
        public void ExpiredSession_IsSwept()
        {
            var loop = NewLoop(reconnectWindow: 2);
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            loop.DrainAndTick(1f); // _tick: 0→1
            loop.Submit(new DisconnectCommand { PlayerId = 1, Connection = c });
            loop.DrainAndTick(1f); // 排空时 _tick=1 → DisconnectedAtTick=1；随后 _tick→2
            loop.DrainAndTick(1f); // _tick→3：3-1=2，不 >2，保留
            loop.DrainAndTick(1f); // _tick→4：4-1=3 >2 → 过期清除
            Assert.False(loop.HasSession(1));
        }

        [Fact]
        public void DuplicateMatchRequest_WhileInRoom_IsRejectedWithError()
        {
            var loop = NewLoop();
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });
            loop.DrainAndTick(1f); // 入房 r1（Hello 第 3 tick 才结束）

            loop.Submit(new FrameCommand { PlayerId = 1, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });
            loop.DrainAndTick(1f); // 第二次 join：已在房间 → 回 Error

            Assert.Contains(Frames(c), f => f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.Error);
        }

        [Fact]
        public void GameFrame_WithNoRoom_IsIgnoredSafely()
        {
            var loop = NewLoop();
            var c = new FakeConnection(1);
            loop.Submit(new ConnectCommand { PlayerId = 1, Connection = c });
            var w = new PacketWriter(); w.WriteVarInt(3);
            loop.Submit(new FrameCommand { PlayerId = 1, Frame = new Frame(Channel.Game, 0, w.ToArray()) });

            var ex = Record.Exception(() => loop.DrainAndTick(1f));
            Assert.Null(ex);       // 无房间的游戏帧被安全忽略，不抛
            Assert.Empty(c.Sent);  // 无任何输出
        }

        [Fact]
        public void MatchRequest_WithNoSession_IsIgnoredSafely()
        {
            var loop = NewLoop();
            // 未发 ConnectCommand，直接来一个 join 帧
            loop.Submit(new FrameCommand { PlayerId = 99, Frame = FrameCodec.Decode(JoinFrame("hello", 1)) });
            var ex = Record.Exception(() => loop.DrainAndTick(1f));
            Assert.Null(ex);
            Assert.False(loop.HasSession(99));
        }
    }
}
```

- [ ] **Step 2: 运行，确认红**

Run: `bash Server/build-test-games.sh && dotnet test Server/Server.sln --filter ServerLoopTests`
Expected: 编译失败（`ServerLoop`/命令类型不存在）。

- [ ] **Step 3: 写 `ServerCommand.cs`**

```csharp
using XWorld.Framework.Protocol;

namespace XWorld.Server.Gateway
{
    public abstract class ServerCommand { public int PlayerId; }

    public sealed class ConnectCommand : ServerCommand { public IClientConnection Connection; }

    public sealed class DisconnectCommand : ServerCommand { public IClientConnection Connection; }

    public sealed class FrameCommand : ServerCommand { public Frame Frame; }
}
```

- [ ] **Step 4: 写 `ServerLoop.cs`**

```csharp
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using ChannelsNS = System.Threading.Channels;
using XWorld.Framework;
using XWorld.Framework.Protocol;
using XWorld.Server.Host;

namespace XWorld.Server.Gateway
{
    // 单线程 actor：独占 RoomHost 与 SessionManager；命令入队、周期性排空+推进。
    public sealed class ServerLoop
    {
        private readonly RoomHost _host;
        private readonly SessionManager _sessions = new SessionManager();
        private readonly ILogger _logger;
        private readonly long _reconnectWindowTicks;
        private readonly ChannelsNS.Channel<ServerCommand> _cmds =
            ChannelsNS.Channel.CreateUnbounded<ServerCommand>();
        private readonly Dictionary<string, List<int>> _roomPlayers = new Dictionary<string, List<int>>();
        private long _tick;
        private int _roomSeq;

        public ServerLoop(string gamesRoot, ILogger logger, long reconnectWindowTicks = 100)
        {
            _logger = logger;
            _reconnectWindowTicks = reconnectWindowTicks;
            _host = new RoomHost(new GameModuleRegistry(new GameModuleLoader(), gamesRoot), logger);
        }

        // 线程安全：网络线程调用，仅入队
        public void Submit(ServerCommand cmd) => _cmds.Writer.TryWrite(cmd);

        // 仅 actor 线程调用（_sessions 无锁）；测试在单线程下使用
        public bool HasSession(int pid) => _sessions.Get(pid) != null;

        // 测试直调；真实循环周期性调它。先排空命令，再推进一 tick，处理结束房间与过期会话。
        public void DrainAndTick(float dt)
        {
            while (_cmds.Reader.TryRead(out var cmd)) Process(cmd);
            _tick++;
            var ended = _host.TickAll(dt);
            for (int i = 0; i < ended.Count; i++) OnRoomEnded(ended[i]);
            var expired = _sessions.SweepExpired(_tick, _reconnectWindowTicks);
            for (int i = 0; i < expired.Count; i++)
                _logger.Info($"session {expired[i].PlayerId} 重连窗口过期，清除");
        }

        public async Task RunAsync(int tickIntervalMs, CancellationToken ct)
        {
            float dt = tickIntervalMs / 1000f;
            while (!ct.IsCancellationRequested)
            {
                DrainAndTick(dt);
                try { await Task.Delay(tickIntervalMs, ct).ConfigureAwait(false); }
                catch (OperationCanceledException) { break; }
            }
        }

        private void Process(ServerCommand cmd)
        {
            switch (cmd)
            {
                case ConnectCommand cc: _sessions.OnConnect(cc.PlayerId, cc.Connection); break;
                case DisconnectCommand dc: _sessions.OnDisconnect(dc.PlayerId, dc.Connection, _tick); break;
                case FrameCommand fc: Route(fc.PlayerId, fc.Frame); break;
            }
        }

        private void Route(int pid, Frame frame)
        {
            if (frame.Channel == Channel.Framework) HandleFramework(pid, frame);
            else
            {
                var s = _sessions.Get(pid);
                if (s?.RoomId != null)
                    _host.DeliverTo(s.RoomId, pid, new NetMessage(frame.Opcode, frame.Payload));
            }
        }

        private void HandleFramework(int pid, Frame frame)
        {
            switch ((FrameworkOpcode)frame.Opcode)
            {
                case FrameworkOpcode.Heartbeat:
                    SendFramework(pid, FrameworkOpcode.Heartbeat, frame.Payload); // 原样回显
                    break;
                case FrameworkOpcode.MatchRequest:
                    var req = MatchRequestMsg.Decode(frame.Payload);
                    CreateRoomFor(pid, req.GameId, req.Version);
                    break;
            }
        }

        private void CreateRoomFor(int pid, string gameId, int version)
        {
            var s = _sessions.Get(pid);
            if (s == null) return; // 未建立会话，忽略
            if (s.RoomId != null)
            {
                // 已在房间内（2b-1 暂无换房/离房流程）：拒绝，避免覆盖 RoomId 造成状态损坏
                SendFramework(pid, FrameworkOpcode.Error,
                    new ErrorMsg { Code = 2, Message = "already in room" }.Encode());
                return;
            }

            string roomId = $"r{++_roomSeq}";
            var players = new List<int> { pid };
            var sink = new RoomOutputSink(roomId, players, _sessions);
            var cfg = new RoomConfig { GameId = gameId, Version = version, Seed = (ulong)_roomSeq, PlayerCount = 1 };
            var infos = new[] { new PlayerInfo { PlayerId = pid, Name = $"P{pid}", IsAI = false } };

            Room room;
            try { room = _host.CreateRoom(roomId, gameId, version, cfg, infos, sink); }
            catch (Exception ex)
            {
                _logger.Error($"建房失败 {gameId}@{version}: {ex.Message}");
                SendFramework(pid, FrameworkOpcode.Error,
                    new ErrorMsg { Code = 1, Message = "create room failed" }.Encode());
                return;
            }

            s.RoomId = roomId;
            _roomPlayers[roomId] = players;

            var found = new MatchFoundMsg { RoomId = roomId, Version = version, SelfPlayerId = pid };
            found.Players.Add(new PlayerInfo { PlayerId = pid, Name = $"P{pid}", IsAI = false });
            SendFramework(pid, FrameworkOpcode.MatchFound, found.Encode());

            if (!room.IsActive) OnRoomEnded(roomId); // 极端：Start 即结束
        }

        private void OnRoomEnded(string roomId)
        {
            if (!_roomPlayers.TryGetValue(roomId, out var players)) return;
            _roomPlayers.Remove(roomId);
            var msg = new RoomEndMsg { WinnerPlayerId = 0, ResultBlob = Array.Empty<byte>() };
            byte[] payload = msg.Encode();
            for (int i = 0; i < players.Count; i++)
            {
                int pid = players[i];
                SendFramework(pid, FrameworkOpcode.RoomEnd, payload);
                var s = _sessions.Get(pid);
                if (s != null) s.RoomId = null;
            }
        }

        private void SendFramework(int pid, FrameworkOpcode op, byte[] payload)
        {
            _sessions.GetConnection(pid)?.Send(
                FrameCodec.Encode(new Frame(Channel.Framework, (ushort)op, payload)));
        }
    }
}
```

- [ ] **Step 5: 运行，确认绿**

Run: `bash Server/build-test-games.sh && dotnet test Server/Server.sln --filter ServerLoopTests`
Expected: PASS（5 个用例）。

---

## Task 6: WebSocket 连接包装 Connection

**Files:**
- Create: `Server/Gateway/Connection.cs`

> 收/发循环的 socket 行为由 Task 7 的真 Kestrel 集成测试覆盖（难以脱离 socket 单测）。

- [ ] **Step 1: 写 `Connection.cs`**

```csharp
using System;
using System.IO;
using System.Net.WebSockets;
using System.Threading;
using System.Threading.Tasks;
using ChannelsNS = System.Threading.Channels;
using XWorld.Framework.Protocol;

namespace XWorld.Server.Gateway
{
    // 一个 WebSocket 连接：收循环解码帧→Submit；发循环排空出站队列→SendAsync（每 socket 仅一个发循环，发送串行）
    public sealed class Connection : IClientConnection
    {
        public int PlayerId { get; }

        private readonly WebSocket _socket;
        private readonly ServerLoop _loop;
        private readonly ChannelsNS.Channel<byte[]> _outbound = ChannelsNS.Channel.CreateUnbounded<byte[]>();

        public Connection(int playerId, WebSocket socket, ServerLoop loop)
        {
            PlayerId = playerId; _socket = socket; _loop = loop;
        }

        public void Send(byte[] frame) => _outbound.Writer.TryWrite(frame);

        public async Task RunAsync(CancellationToken ct)
        {
            var sendTask = SendLoopAsync(ct);
            try { await ReceiveLoopAsync(ct).ConfigureAwait(false); }
            finally
            {
                _outbound.Writer.TryComplete();
                await sendTask.ConfigureAwait(false);
            }
        }

        private async Task ReceiveLoopAsync(CancellationToken ct)
        {
            var buf = new byte[8192];
            using var ms = new MemoryStream();
            try
            {
                while (_socket.State == WebSocketState.Open && !ct.IsCancellationRequested)
                {
                    ms.SetLength(0);
                    WebSocketReceiveResult res;
                    do
                    {
                        res = await _socket.ReceiveAsync(new ArraySegment<byte>(buf), ct).ConfigureAwait(false);
                        if (res.MessageType == WebSocketMessageType.Close) return;
                        ms.Write(buf, 0, res.Count);
                    } while (!res.EndOfMessage);

                    Frame frame;
                    try { frame = FrameCodec.Decode(ms.ToArray()); }
                    catch (FormatException) { continue; } // 畸形帧：丢弃，不拖垮连接

                    _loop.Submit(new FrameCommand { PlayerId = PlayerId, Frame = frame });
                }
            }
            catch (OperationCanceledException) { } // 主机关停/请求中止
            catch (WebSocketException) { }          // 对端突然断开（TCP 掉线）
        }

        private async Task SendLoopAsync(CancellationToken ct)
        {
            try
            {
                await foreach (var frame in _outbound.Reader.ReadAllAsync(ct).ConfigureAwait(false))
                {
                    if (_socket.State != WebSocketState.Open) break;
                    await _socket.SendAsync(new ArraySegment<byte>(frame),
                        WebSocketMessageType.Binary, true, ct).ConfigureAwait(false);
                }
            }
            catch (OperationCanceledException) { }
            catch (WebSocketException) { } // 对端已断，停止发送
        }
    }
}
```

---

## Task 7: Kestrel 宿主 GameServerHost + 端到端集成测试（真 WS）

**Files:**
- Create: `Server/Gateway/GameServerHost.cs`
- Create: `Server/Gateway.Tests/Support/WsTestClient.cs`
- Test: `Server/Gateway.Tests/GatewayEndToEndTests.cs`

- [ ] **Step 1: 写 `GameServerHost.cs`**

```csharp
using System;
using System.Linq;
using System.Net;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Hosting.Server;
using Microsoft.AspNetCore.Hosting.Server.Features;
using System.Net.WebSockets;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using XWorld.Server.Host;

namespace XWorld.Server.Gateway
{
    // 建 Kestrel + /ws 端点，把 socket 接入 ServerLoop。Start 返回实际监听地址（端口由系统分配）。
    public sealed class GameServerHost
    {
        private WebApplication _app;
        private ServerLoop _loop;
        private CancellationTokenSource _cts;
        private Task _loopTask;

        public string WsBaseUrl { get; private set; } // 例如 ws://127.0.0.1:54321

        public async Task StartAsync(string gamesRoot, int tickIntervalMs, long reconnectWindowTicks = 100)
        {
            _loop = new ServerLoop(gamesRoot, new ConsoleLogger("[loop]"), reconnectWindowTicks);
            _cts = new CancellationTokenSource();

            var builder = WebApplication.CreateBuilder();
            builder.Logging.ClearProviders();
            builder.WebHost.ConfigureKestrel(o => o.Listen(IPAddress.Loopback, 0)); // 临时端口

            var app = builder.Build();
            app.UseWebSockets();
            app.Use(async (ctx, next) =>
            {
                if (ctx.Request.Path == "/ws" && ctx.WebSockets.IsWebSocketRequest)
                {
                    if (!int.TryParse(ctx.Request.Query["pid"], out int pid))
                    {
                        ctx.Response.StatusCode = 400;
                        return;
                    }
                    using var ws = await ctx.WebSockets.AcceptWebSocketAsync();
                    var conn = new Connection(pid, ws, _loop);
                    _loop.Submit(new ConnectCommand { PlayerId = pid, Connection = conn });
                    try { await conn.RunAsync(ctx.RequestAborted); }
                    catch (OperationCanceledException) { } // 关停/中止：正常收束
                    finally
                    {
                        if (ws.State == WebSocketState.Open)
                        {
                            try { await ws.CloseAsync(WebSocketCloseStatus.NormalClosure, "server stopping", CancellationToken.None); }
                            catch { /* 关闭握手尽力而为 */ }
                        }
                        _loop.Submit(new DisconnectCommand { PlayerId = pid, Connection = conn });
                    }
                }
                else
                {
                    await next();
                }
            });

            await app.StartAsync();
            _app = app;

            var addresses = app.Services.GetRequiredService<IServer>()
                .Features.Get<IServerAddressesFeature>().Addresses;
            string http = addresses.FirstOrDefault() // http://127.0.0.1:port
                ?? throw new InvalidOperationException("Kestrel 已启动但未注册任何监听地址");
            WsBaseUrl = http.Replace("http://", "ws://");

            _loopTask = _loop.RunAsync(tickIntervalMs, _cts.Token);
        }

        public async Task StopAsync()
        {
            _cts.Cancel();
            try { await _loopTask; } catch { /* 忽略取消 */ }
            await _app.StopAsync();
            await _app.DisposeAsync();
        }
    }
}
```

- [ ] **Step 2: 写 `Support/WsTestClient.cs`**

```csharp
using System;
using System.IO;
using System.Net.WebSockets;
using System.Threading;
using System.Threading.Tasks;
using XWorld.Framework.Protocol;

namespace XWorld.Server.Gateway.Tests
{
    // 集成测试用 WS 客户端：连接、发帧、带超时收一帧并解码
    internal sealed class WsTestClient : IDisposable
    {
        private readonly ClientWebSocket _ws = new ClientWebSocket();

        public async Task ConnectAsync(string wsBaseUrl, int pid)
        {
            await _ws.ConnectAsync(new Uri($"{wsBaseUrl}/ws?pid={pid}"), CancellationToken.None);
        }

        public async Task SendFrameAsync(Frame frame)
        {
            byte[] bytes = FrameCodec.Encode(frame);
            await _ws.SendAsync(new ArraySegment<byte>(bytes), WebSocketMessageType.Binary, true, CancellationToken.None);
        }

        // 在 timeout 内收一条 WS 消息并解码为 Frame；超时抛 TimeoutException
        public async Task<Frame> ReceiveFrameAsync(int timeoutMs = 5000)
        {
            using var cts = new CancellationTokenSource(timeoutMs);
            var buf = new byte[8192];
            using var ms = new MemoryStream();
            WebSocketReceiveResult res;
            do
            {
                res = await _ws.ReceiveAsync(new ArraySegment<byte>(buf), cts.Token);
                if (res.MessageType == WebSocketMessageType.Close)
                    throw new InvalidOperationException("server closed");
                ms.Write(buf, 0, res.Count);
            } while (!res.EndOfMessage);
            return FrameCodec.Decode(ms.ToArray());
        }

        public async Task CloseAsync()
        {
            try { await _ws.CloseAsync(WebSocketCloseStatus.NormalClosure, "bye", CancellationToken.None); }
            catch { /* 忽略 */ }
        }

        public void Dispose() => _ws.Dispose();
    }
}
```

- [ ] **Step 3: 写集成测试 `GatewayEndToEndTests.cs`**

```csharp
using System.Collections.Generic;
using System.Threading.Tasks;
using Xunit;
using XWorld.Framework.Protocol;
using XWorld.Server.Gateway;

namespace XWorld.Server.Gateway.Tests
{
    public class GatewayEndToEndTests
    {
        private static Frame JoinHello()
            => new Frame(Channel.Framework, (ushort)FrameworkOpcode.MatchRequest,
                new MatchRequestMsg { GameId = "hello", Version = 1 }.Encode());

        [Fact]
        public async Task Connect_Join_ReceivesMatchFound_Snapshots_RoomEnd()
        {
            var host = new GameServerHost();
            await host.StartAsync(TestGames.Root, tickIntervalMs: 20);
            try
            {
                using var client = new WsTestClient();
                await client.ConnectAsync(host.WsBaseUrl, pid: 1);
                await client.SendFrameAsync(JoinHello());

                // 收帧直到 RoomEnd
                bool matchFound = false, roomEnd = false;
                int snapshots = 0;
                for (int i = 0; i < 20 && !roomEnd; i++)
                {
                    var f = await client.ReceiveFrameAsync(5000);
                    if (f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.MatchFound) matchFound = true;
                    else if (f.Channel == Channel.Game) snapshots++;
                    else if (f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.RoomEnd) roomEnd = true;
                }

                Assert.True(matchFound, "未收到 MatchFound");
                Assert.True(snapshots >= 3, $"快照数应≥3，实际 {snapshots}");
                Assert.True(roomEnd, "未收到 RoomEnd");
                await client.CloseAsync();
            }
            finally { await host.StopAsync(); }
        }

        [Fact]
        public async Task Heartbeat_IsEchoedBack()
        {
            var host = new GameServerHost();
            await host.StartAsync(TestGames.Root, tickIntervalMs: 20);
            try
            {
                using var client = new WsTestClient();
                await client.ConnectAsync(host.WsBaseUrl, pid: 7);
                await client.SendFrameAsync(new Frame(Channel.Framework, (ushort)FrameworkOpcode.Heartbeat,
                    new HeartbeatMsg { ClientTimeMs = 999L }.Encode()));

                Frame? echo = null; // Frame 是 readonly struct，用可空值类型
                for (int i = 0; i < 10; i++)
                {
                    var f = await client.ReceiveFrameAsync(5000);
                    if (f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.Heartbeat) { echo = f; break; }
                }
                Assert.True(echo.HasValue);
                Assert.Equal(999L, HeartbeatMsg.Decode(echo.Value.Payload).ClientTimeMs);
                await client.CloseAsync();
            }
            finally { await host.StopAsync(); }
        }

        [Fact]
        public async Task Reconnect_ContinuesReceivingFromSameRoom()
        {
            var host = new GameServerHost();
            // 大 tick 间隔给重连留足时间（Hello 3 tick = 3s）
            await host.StartAsync(TestGames.Root, tickIntervalMs: 1000, reconnectWindowTicks: 100);
            try
            {
                var client1 = new WsTestClient();
                await client1.ConnectAsync(host.WsBaseUrl, pid: 42);
                await client1.SendFrameAsync(JoinHello());

                // 收到 MatchFound + 第一个快照（首个 tick 在加入后约 ≤1s 触发）
                bool gotSnapshot = false;
                for (int i = 0; i < 5 && !gotSnapshot; i++)
                {
                    var f = await client1.ReceiveFrameAsync(5000);
                    if (f.Channel == Channel.Game) gotSnapshot = true;
                }
                Assert.True(gotSnapshot, "重连前应先收到一个快照");

                // 断开
                await client1.CloseAsync();
                client1.Dispose();

                // 用同 pid 重连
                using var client2 = new WsTestClient();
                await client2.ConnectAsync(host.WsBaseUrl, pid: 42);

                // 房间仍在跑，下一个快照应发到 client2
                bool gotAfterReconnect = false;
                for (int i = 0; i < 5 && !gotAfterReconnect; i++)
                {
                    var f = await client2.ReceiveFrameAsync(5000);
                    if (f.Channel == Channel.Game) gotAfterReconnect = true;
                    else if (f.Channel == Channel.Framework && f.Opcode == (ushort)FrameworkOpcode.RoomEnd) { gotAfterReconnect = true; }
                }
                Assert.True(gotAfterReconnect, "重连后应继续收到房间输出（快照或 RoomEnd）");
                await client2.CloseAsync();
            }
            finally { await host.StopAsync(); }
        }
    }
}
```

- [ ] **Step 4: 运行集成测试，确认绿**

Run: `bash Server/build-test-games.sh && dotnet test Server/Server.sln --filter GatewayEndToEndTests`
Expected: 3 个集成测试 PASS（真 Kestrel + ClientWebSocket，端到端连/入房/收快照/结束、心跳回显、断线重连续收）。

> 若 `Connect_Join_...` 偶发超时：确认 tickIntervalMs 较小（20ms），并发循环 `RunAsync` 在首个 `Task.Delay` 前已 `DrainAndTick` 一次。若重连测试偶发：增大 `tickIntervalMs`（如 1500）给客户端重连更多余量。真实端口/真实 WS 帧不应有功能性失败。

---

## Task 8: 收尾——全量验证

- [ ] **Step 1: 生成夹具并跑全量**

Run:
```bash
bash Server/build-test-games.sh
dotnet test Server/Server.sln
```
Expected: 全绿。= 子项目 1（46）+ 2a（27 + RoomHost 新增 1 = 28）+ 2b-1（SessionManager 5 + RoomOutputSink 3 + ServerLoop 5 + GatewayEndToEnd 3 = 16）。失败 0。

> 若遇 MSBuild 工作进程在沙箱中 `0xC0000005` 偶发崩溃（与产品无关），改用 `DOTNET_CLI_USE_MSBUILD_SERVER=0 dotnet test Server/Server.sln -m:1` 重试。

- [ ] **Step 2: 构建零警告确认**

Run: `dotnet build Server/Server.sln -v minimal`
Expected: `Build succeeded`，0 error / 0 warning。

---

## 完成判据（Definition of Done）

- [ ] `bash Server/build-test-games.sh && dotnet test Server/Server.sln` 全绿（含 16 个新测试）。
- [ ] `dotnet build Server/Server.sln` 0 error / 0 warning。
- [ ] 真 WS 端到端：客户端经真 Kestrel + ClientWebSocket 连接 → 发 MatchRequest → 收 MatchFound → 收 ≥3 个 Game 通道快照 → 收 RoomEnd。
- [ ] 路由正确：Framework 通道帧走框架处理（MatchRequest/Heartbeat），Game 通道帧路由到玩家所在房间。
- [ ] 心跳回显；断线重连窗口内续收同一房间输出（输出重路由到新连接）；过期会话被扫除。
- [ ] 并发模型：网络线程只 `Submit`（线程安全 Channel），RoomHost/Session 仅由 actor 单线程在 `DrainAndTick` 内访问，无锁。
- [ ] 共享层（Framework.Shared）零改动；2a 仅 `RoomHost.TickAll` 加返回值（向后兼容）。

## 不在本子项目范围（交给后续）

- **匹配 + AI 兜底**（按 (gameId,version) 分桶、凑齐 N 人、15s 超时→AI 兜底）+ 多人/2 人游戏——随 **RPS 重写（§9 第 5 步）**一起做（届时有真正的 2 人游戏与 AI 规则）。
- 鉴权（当前 `?pid=` 是明文身份占位）、WSS/TLS、限流、压测。
- 持久化升级（替换 `InMemoryStorage`）、监控告警、发布通知订阅。
- `IGameLogic` 的 `TInput`/`TEvent` 统一编解码约定与“业务输入走 Channel.Game vs GameInputMsg”的最终定夺——本计划已用 `Channel.Game` 直传业务帧（`NetMessage(frame.Opcode, frame.Payload)`），RPS 重写时确认沿用。
- `minFrameworkVersion`/`tickRateHz` 的加载期校验与按 manifest 驱动 tick（当前 tick 间隔由宿主参数给定）。