# ProtoBufModule

本模块承载 **RPC 与业务消息的二进制契约**：所有 TCP 链路上传输的业务体都通过此处定义的 `protobuf` 生成 Java 类（包名 `com.huangzj.cmd.gen`）。

## 职责

- 维护 `src/main/protobuf` 下的 `.proto` 源文件。
- Maven `protobuf-maven-plugin` 在 `generate-sources` 阶段生成 Java 源码到 `target/generated-sources/protobuf/java`。
- **其它模块**（BaseModule、ServerModule、CrossModule）仅依赖本模块打出的 jar，不重复拷贝 `.proto`。

## 目录结构（源文件）

```text
src/main/protobuf/
└── serverProto/
    ├── cmd_rpc.proto    # CmdRpcEnvelope、各 CTS/STC、Method 枚举
    └── pb_service.proto # PbService（Service_1 ~ Service_4）
```

> 历史上独立的 `CrossProto` 已移除；跨服与区服共用 **`demo.cmd`** 包下的消息，通过 **service/method + CommandSource** 在 Java 侧区分语义。

## 网络层核心消息：`CmdRpcEnvelope`

```protobuf
message CmdRpcEnvelope {
  uint32 service_id = 1;
  uint32 method_id = 2;
  bytes payload = 3;      // 具体 CTS 的序列化字节
  int32 cross_ret = 4;    // 预留/透传
  uint32 link_seq = 5;    // 区服↔跨服长连接多路复用序号（客户端 TCP 可为 0）
}
```

### `link_seq` 的作用（与网络实现配合）

```mermaid
sequenceDiagram
  participant Z as 区服 CrossTcpClient
  participant X as 跨服 TCP
  Note over Z,X: 单条 TCP 上可能同时存在多帧在途
  Z->>X: 请求 A (link_seq=101)
  Z->>X: 请求 B (link_seq=102)
  X-->>Z: 响应 B (link_seq=102)
  X-->>Z: 响应 A (link_seq=101)
```

- 区服在 **`CrossTcpClient`** 内为每次 `roundTrip` / 注册 / 心跳分配 **非 0** 的 `link_seq`。
- 跨服命令通过 **`AbstractTypedPbCommand`** 回包时 **原样带回** 请求信封中的 `link_seq`，以便客户端把响应与 `CompletableFuture` 对应。

## 服务与方法枚举

| PbService | 用途 |
|-----------|------|
| Service_1 | 路径 1 示例（Echo） |
| Service_2 | 跨服业务 Method2（`CrossForward*`） |
| Service_3 | 路径 3 区服对客户端暴露的中转接口 |
| Service_4 | **链路控制**：Register、Heartbeat（仅区服→跨服长连接上使用） |

`Service4_Method`：`Register`、`Heartbeat`，载荷分别为 `CrossLinkRegisterCts/Stc`、`CrossLinkHeartbeatCts/Stc`。

## 业务消息（与路径对应）

- **路径 1**：`CmdEchoCts` / `CmdEchoStc`。
- **路径 2（客户端侧）**：`CrossProxyCts` / `CrossProxyStc`（区服内会转为 `CrossForward*` 再发往跨服）。
- **路径 3**：客户端 payload 使用 **`CrossForwardCts`** 形态（与跨服 Service_2/Method2 一致），信封为 Service_3/Method3。
- **跨服 Service_2/Method2**：`CrossForwardCts` / `CrossForwardStc`。

## 生成代码

```bash
cd ProtoBufModule
mvn -q generate-sources
# 或使用 genpb.bat（Windows，会探测 Maven）
```

生成物加入 `ProtoBufModule` jar，依赖方编译时自动可见。

## 扩展约定

新增 RPC 时建议：

1. 在 `pb_service.proto` 增加 `PbService` 枚举值（若新服务号）。
2. 在 `cmd_rpc.proto` 增加 `ServiceX_Method` 与 CTS/STC `message`。
3. 执行 `generate-sources` 后，在 **BaseModule** 侧通过 `@Cmd` + `AbstractTypedPbCommand` 或 `GameCommand` 实现逻辑，并由 **`ProtoRegistryAutoConfigurer`** 自动注册 `ProtoInfo`（强类型命令）。