# comm-framework

多模块示例工程：演示 **区服（游戏逻辑 + HTTP）**、**跨服（独立 TCP 进程）** 以及二者之间的 **长连接、注册、心跳** 与 **CmdRpc 业务帧** 的编解码与路由。

## 模块一览

| 模块 | 说明 | 文档 |
|------|------|------|
| **ProtoBufModule** | `.proto` 定义与 Java 生成（`CmdRpcEnvelope`、各业务消息、枚举） | [ProtoBufModule/README.md](ProtoBufModule/README.md) |
| **BaseModule** | 公共 Netty 帧、命令分发、`ProtoRegistry`、`CrossRpcInvoker` 抽象等 | [BaseModule/README.md](BaseModule/README.md) |
| **CrossModule** | 可独立启动的跨服进程：监听 TCP，处理 `CROSS_TCP` 来源命令 | [CrossModule/README.md](CrossModule/README.md) |
| **ServerModule** | 区服：客户端游戏 TCP、连跨服的 `CrossTcpClient`、HTTP Demo | [ServerModule/README.md](ServerModule/README.md) |

## 总体架构（进程与端口）

```mermaid
flowchart LR
  subgraph Client["游戏客户端 / 本机探针"]
    C[TCP 客户端]
  end
  subgraph Server["ServerModule 进程"]
    CT[Client TCP :9091]
    HTTP[HTTP :8080]
    CC[CrossTcpClient 长连接]
  end
  subgraph Cross["CrossModule 进程"]
    XT[Cross TCP :9200]
  end
  C -->|长度前缀 + CmdRpcEnvelope| CT
  BROWSER[浏览器] -->|HTTP 探活/Demo| HTTP
  CC -->|长度前缀 + CmdRpcEnvelope| XT
```

- **默认端口**（见各模块 `application.yml`）：区服客户端 TCP 由 `game.client-tcp.port` 指定（示例 **9091**）；跨服 TCP **9200**；区服 HTTP **8080**。
- **区服 → 跨服** 使用 **单条 TCP 长连接**：启动后 **Service_4 注册**，定时 **Service_4 心跳**；业务请求通过 **`link_seq`** 在同一连接上多路复用。

## 统一帧格式（TCP）

任意一条 TCP 消息在链路上的形态均为：

```text
+------------------+------------------------+
| 4 字节大端 length | length 字节的 body      |
+------------------+------------------------+
        body = CmdRpcEnvelope.parseFrom(bytes)
```

实现见 `BaseModule` 中 `LengthPrefixedProtobuf`、`CmdRpcTcpFrameHandler`。

## 命令来源（CommandSource）

| 来源 | 含义 | 典型入口 |
|------|------|----------|
| `Client_TCP` | 玩家/工具连区服的客户端 TCP | `ServerModule` `ClientTcpServer` |
| `CROSS_TCP` | 区服作为客户端连到跨服的那条链路上的入站 | `CrossModule` 接受 `CrossTcpClient` 连接 |

同一 `service_id + method_id` 在两种来源下可对应 **不同** `GameCommand` 实现；`ProtoRegistry` 按 **来源 + service + method** 分别注册 `ProtoInfo`（CTS/STC 类型）。

## 三条客户端业务路径（概念）

1. **路径 1**：区服本地处理（不经跨服）。
2. **路径 2**：客户端 `CrossProxy*` → 区服转换为 `CrossForward*` → **跨服** → 回到区服组装 `CrossProxyStc`（含 `server_note`）。
3. **路径 3**：客户端 payload 已是跨服 CTS 形态，区服仅改信封转发跨服，响应再换回原 service/method。

详见 [ServerModule/README.md](ServerModule/README.md)。

## 构建与运行

```bash
# 在仓库根目录
mvn clean compile

# 先起跨服，再起区服（路径 2/3 依赖跨服）
# CrossModuleApplication
# ServerModuleApplication
```

Proto 变更后需对 **ProtoBufModule** 执行 `mvn generate-sources`（或 `ProtoBufModule/genpb.bat`）。

## 日志

各区服/跨服进程通过各自 `logback-spring.xml` 将 **INFO/WARN** 与 **ERROR** 分文件写入 `app.logging.dir`（默认 `logs/ServerModule`、`logs/CrossModule`）。
