代码初始化

ProtoBufModule/README.md

@@ -0,0 +1,84 @@
+# 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`（强类型命令）。