代码初始化

README.md

@@ -0,0 +1,82 @@
+# 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`）。