UnityAI/modules/frameworks/网络系统.md

# 网络系统

## 分类

- 核心框架

## 目的

提供 WebSocket 连接、protobuf 消息收发、消息 ID / route 映射和错误响应处理。

---

## 核心路径

- protobuf 源：`GoogleProtobufNetwork/`
- 生成输出：`Assets/Game/GameHFScripte/CopyToHF/Network/`
- WebSocket：`Assets/Game/GameHFScripte/GameFunction/WebSocket/`

---

## 核心类

| 类 | 职责 |
|---|---|
| `HFSeverManager` | 网络管理器单例 |
| `WSSession` | WebSocket 会话 |
| `HFM_Socket_WS` | WebSocket 底层连接 |
| `HFWebSocket_Manager_AutoMsgMap` | 自动生成消息映射 |
| `HFNetWorkMsgIdMap` | 网络消息 ID 映射 |
| `MessagePage` | 数据包编解码 |

---

## C2S 发送链路

```text
IMessage.Dispatch()
  -> HFSeverManager.Instance.SendMsg(message)
  -> HFSeverManager.OnAuto_OnGetProtocNo(message)
  -> HFSeverManager.OnAuto_OnGetRoute(Network_MsgId)
  -> m_Session.SendMessage(protoNo, route, PacketType.Data, Request, message)
```

`IMessage.Dispatch()` 定义在 `Assets/Game/GameHFScripte/GameFunction/WebSocket/Extends/HFServer_Extend.cs`。

---

## WebSocket 连接流程

```text
登录管理器.ConnectServer
  -> HFSeverManager.Connect(MainConnect, WebSocket, ip, port, token)
  -> WSSession.Connect
  -> HFM_Socket_WS.Connect
  -> Handshake -> HandshakeAck -> 连接成功回调
```

---

## S2C 收包和派发

```text
WSSession.ReceiveMessages(PacketType.Data)
  -> MessagePage.Decode(packet.Body)
  -> Response.MessageId / Push.Route -> Network_MsgId
  -> HFSeverManager.OnAuto_OnMergeFrom(msgid, body)
  -> protobuf Parser.ParseFrom
  -> 反射创建 HFEvent_STC_{MessageTypeName}
  -> 写入 Request / ErrorCode
  -> AbsHFEventArg<enHFSTCEvent>.Dispatch()
  -> HFEventManager.Instance.STCEvent.Dispatch(arg)
```

---

## 自动生成映射

- `HFWebSocket_Manager_AutoMsgMap.cs`：提供 `OnAuto_OnGetProtocNo`、`OnAuto_OnGetRoute`、`OnAuto_OnMergeFrom`、`msrDicRouteToMsg`、S2C/C2S 类型字典。
- `HFNetWorkMsgIdMap.cs`：为 protobuf partial class 标记 `[HFNetworkMsg(...)]`。

---

## 使用规则

- 新增协议先改 `.proto`、`msg.proto`、`route.txt`。
- 不手动修改生成输出。
- 不硬编码 route 或数字 msgId。
- UI 监听 S2C 必须在 `OnClose` 移除。
- 错误响应会触发 `HFEvent_ErrorCode`。

---

## 协议变更清单

1. 修改 `.proto` 和 `msg.proto`。
2. 登记 msgId / route（如 `route.txt` 或对应生成配置）。
3. 通过生成器重新生成 C# 代码到 `Assets/Game/GameHFScripte/CopyToHF/Network/`。
4. 检查 `HFNetWorkMsgIdMap.cs` / `HFWebSocket_Manager_AutoMsgMap.cs` 是否同步。
5. 更新业务入口和监听。
6. 编译 `GameHF` 并运行连接/收发测试。

## 验证

- 构建 `GameHF.csproj`。
- 在支持服务器的运行环境中登录、收发 C2S/S2C 消息。
- 确认 `HFEvent_STC_*` 正确派发并在 `OnClose` 时移除监听。
- 验证错误码事件 `HFEvent_ErrorCode` 触发路径。

## 当前状态

- 待验证

---

## 相关模块

- [事件系统](事件系统/README.md)
- [数据/配置框架](数据配置框架.md)

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
| [modules/frameworks/事件系统/README.md](事件系统/README.md) | S2C 消息派发为 STC 事件 |
| [modules/frameworks/数据配置框架.md](数据配置框架.md) | 配置表与网络消息可能联动 |
| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |