# libcom_router — 通信路由中枢 API 参考

## 模块概述

**位置**: `src/system/libcom_router/`

**定位**: RTU 通信路由中枢。负责:
- 转发通道管理 (TCP/串口 → FTU 串口透传)
- FTU 串口接收分路 (按帧内容区分维护PC/self_ptl)
- 跨模块回调注册 (与 self_ptl 解耦)

**依赖**: `libcomm`, `libicp67`(帧头检测), `liblog`, `libdatacenter`

**不依赖**: self_ptl, libiec (通过 `app_wiring()` 运行时解耦)

## 架构

```
                    libcom_router
               ┌──────────┼──────────┐
               │                     │
         转发通道(TCP)          FTU 串口
               │                     │
    Step1: 直接透传 ────→  ┌── Step2: 分路 ──┐
                           │                  │
                    ICP67 dev=0  IEC 0x68  ICP67 dev=1
                        │          │          │
                    回传转发源  回传转发源   self_ptl
                   (维护软件)  (维护软件)  (RTU自身)
```

**注意**: RTU 自身的 IEC-104 不走 com_router，由 libiec 直管 libcomm。

## 文件清单

| 文件 | 行数 | 说明 |
|---|---|---|
| `inc/com_router.h` | 98 | 通道配置、转发规则、回调注册 API |
| `src/com_router.cpp` | 385 | 通道管理、配置加载、状态回调、主循环 |
| `src/com_router_dispatch.cpp` | 191 | 转发透传 + FTU 串口分路 |

## 对外 API

### 配置加载

```c
int com_router_config_load(const char *json_path);
```

从 JSON 加载通道配置和转发规则。未调用时使用硬编码默认配置。

### 回调注册 (模块解耦)

```c
typedef void (*com_router_dispatch_cb)(uint32_t interface, const unsigned char *data, int len);

int com_router_register_dispatch(const char *bind_app, com_router_dispatch_cb cb);
```

协议模块通过此 API 接收 FTU 串口的 ICP67 dev=1 帧。

**调用者**: `app_sys.cpp` → `app_wiring()`

**示例**:
```c
com_router_register_dispatch("self_ptl", self_ptl_router_wrapper);
```

### 查询 API

```c
uint32_t com_router_interface_get(const char *key);   // key → interface
int      com_router_fd_get(const char *key);           // key → socket_fd
int      com_router_id_get_by_bind(const char *bind_app); // bind_app → ch_id
```

### 应用线程入口

```c
int   app_com_router_init1(void *arg);   // 创建通道 + 注册回调
int   app_com_router_init2(void *arg);   // 连接通道
void *app_com_router(void *arg);         // 主循环
```

## 路由规则 (v2 — bind_app 协议绑定)

```
com_router_recv_cb(id, fd, data, len)
│
├─ Step 1: forward_rule → FTU串口透传
│
├─ Step 2: bind_app 非空 → dispatch 投递给注册协议
│
└─ Step 3: bind_app 为空 → FTU串口帧内容分路
    ├─ ICP67 dev=0 → 回传维护
    ├─ IEC  → 回传维护
    └─ ICP67 dev≠0 → MQ → self_ptl
```

**示例**: `tcp_master(:2404)` 配置 `bind_app="iec"` → 整帧直投 libiec

### bind_app 注册 API

```c
typedef void (*com_router_dispatch_cb)(uint32_t interface, const unsigned char *data, int len);

int com_router_register_dispatch(const char *bind_app, com_router_dispatch_cb cb);
```

## 配置结构

### 通道配置

```c
typedef struct {
    char     key[32];           // "serial_ftu"
    char     bind_app[16];      // "" (FTU串口不需要绑定)
    int      type;              // COMM_TYPE_UART / COMM_TYPE_TCP_SERVER
    union_comm_para para;       // 通道参数
    int      id;                // comm_create 返回值
    int      socket_fd;         // 当前 fd, -1=未连接
    uint32_t interface;         // (id<<16)|fd
} com_channel_t;
```

### 转发规则

```c
typedef struct {
    char  listen_ip[32];        // "0.0.0.0"
    int   listen_port;          // 2405
    char  target_type[16];      // "uart"
    char  target_dev[64];       // "/dev/ttyS1"
    int   sock_fd;              // accept 后的 client fd
    int   target_ch_id;         // 目标通道 id
} com_forward_rule_t;
```

## 默认配置 (硬编码兜底)

| 通道 | key | 类型 | bind_app | 说明 |
|---|---|---|---|---|
| 串口 | `serial_ftu` | UART 115200 | `""` | FTU连接, bind_app 空→帧内容分路 |
| TCP | `tcp_master` | TCP :2404 | `"iec"` | IEC-104主站, bind_app 绑定后直投 libiec |

| 转发规则 | 监听 | 目标 | 说明 |
|---|---|---|---|
| 维护透传 | 0.0.0.0:2405 | FTU 串口 | 维护软件直连 FTU |

## 多 FTU 扩展

```
新增 FTU 只需:
1. 配置加一个串口通道 + 一个转发规则
2. com_router 自动按帧的 dev_addr 分路
3. self_ptl 通过 interface 区分不同 FTU
```

## 完成状态

### ✅ 已完成

- [x] 通道创建/连接/状态回调
- [x] 转发通道 → FTU 串口透传
- [x] FTU 串口接收三路分路 (ICP67 dev=0 / IEC / ICP67 dev=1)
- [x] 跨模块回调注册 (app_wiring 解耦)
- [x] bind_app 协议绑定路由 + register_dispatch API
- [x] JSON 解析 channels/forward_rules/bind_app
- [x] TCP accept + 客户端 fd 管理
- [x] X-Macro + EV_STOP
- [x] 通道健康检测

### ⬜ 未完成

- [ ] 串口热插拔/自动重连
- [ ] 单元测试 (test_com_router.c)
- [ ] 通道流量统计上报 (EV_TIMER3)