tele-recv/README.md

# tele-recv 串口电报接收器

[![Build Status](http://d2.int.it2000.com.cn/api/badges/airport/tele-recv/status.svg)](http://d2.int.it2000.com.cn/airport/tele-recv)

机场串口电报数据缓存与分发程序。从串口读取电报（ZCZC...NNNN 格式），持久化到 SQLite，并通过 TCP 和/或 Apache Pulsar 分发。

## 架构

```
串口 (ttyS0) → serial.Port → telegram.Parser → storage.Store (SQLite)
                                                   ↓
                                              transport.Sender
                                                   ↓
                                          ┌──────────┴──────────┐
                                          ↓                     ↓
                                       TCP Client         Apache Pulsar
```

核心原则：**先持久化，再分发**。无论配置何种传输模式，电报始终先写入 SQLite，确保数据不丢失。

## 项目结构

```
tele-recv/
├── app/          # 应用生命周期管理 (context.Context + 信号处理)
├── cmd/          # CLI 入口 (cobra: root, start, test)
├── config/       # 配置结构体与 viper 加载
├── serial/       # 串口读接口与实现 (Reader 接口)
├── telegram/     # 电报解析器 (ZCZC...NNNN 提取)
├── storage/      # SQLite 持久化 (Repository 接口)
├── transport/    # 传输层 (Sender 接口: TCP, Pulsar, MultiSender)
├── main.go       # 程序入口
├── Taskfile.yml  # 构建/测试任务定义
└── telegram.yaml # 配置文件
```

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 语言 | Go 1.21+ | 需 Go 1.21 或更高版本 |
| CLI | cobra + viper | 命令解析与配置管理 |
| 串口 | github.com/argandas/serial | 串口通信 |
| 存储 | github.com/mattn/go-sqlite3 | SQLite 驱动 (需要 CGO) |
| 消息 | github.com/apache/pulsar-client-go | Apache Pulsar 集成 |
| 日志 | go.uber.org/zap | 结构化日志 |
| 轮转 | github.com/lestrrat-go/file-rotatelogs | 日志文件轮转 |

## 快速开始

### 前置条件

- Go 1.21+
- 如需交叉编译：`x86_64-linux-gnu-gcc` (Linux) 或 `x86_64-w64-mingw32-gcc` (Windows)

### 安装 Task (推荐)

```bash
go install github.com/go-task/task/v3/cmd/task@latest
```

### 常用命令

```bash
task deps          # 安装依赖
task build         # 构建当前平台二进制
task build-all     # 构建 Linux + Windows 二进制
task run           # 构建并启动 tele-recv start
task run-test      # 构建并启动 tele-recv test
task test          # 运行所有测试
task test-race     # 运行竞态检测测试
task test-cover    # 运行测试并生成覆盖率报告
task lint          # go vet 静态检查
task emu           # 创建虚拟串口对 (ttyS0 ↔ ttyS1)
task clean         # 清理构建产物
task dist          # 构建全平台并打包 tar.gz
```

### 手动构建

```bash
go mod tidy
go build -o tele-recv .
```

### 交叉编译

```bash
# Linux (需要 CGO 和 x86_64-linux-gnu-gcc)
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC=x86_64-linux-gnu-gcc go build -o tele-recv-linux .

# Windows (需要 CGO 和 x86_64-w64-mingw32-gcc)
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc go build -o tele-recv-win64.exe .
```

### 模拟串口

```bash
task emu
# 创建 /tmp/ttyS0 ↔ /tmp/ttyS1 虚拟串口对
```

## 配置

编辑 `telegram.yaml`：

```yaml
serial:
  device: /tmp/ttyS1        # 串口设备
  baudrate: 9600            # 波特率
  lograw: true              # 控制台输出原始数据

telegram:
  tcp: false                # 启用 TCP 分发
  pulsar: true              # 启用 Pulsar 分发

sqlite:
  file: telegram.db         # 数据库文件
  init: false               # 启动时重建数据库

socket:
  address: 127.0.0.1:6000   # TCP 监听地址

pulsar:
  url: pulsar://localhost:6650
  topic: telegram-raw
  name: serial-reader

log:
  dir: ./logs               # 日志目录
  maxage: 60                # 日志保留天数
  rotatehour: 1             # 日志轮转间隔(小时)
```

### 配置选项

| 选项 | 含义 | 默认值 |
|------|------|--------|
| `serial.device` | 串口设备名 | — |
| `serial.baudrate` | 波特率 | — |
| `serial.lograw` | 控制台输出原始数据 | `false` |
| `telegram.tcp` | 启用 TCP 分发 | `false` |
| `telegram.pulsar` | 启用 Pulsar 分发 | `false` |
| `sqlite.file` | SQLite 数据库文件 | — |
| `sqlite.init` | 启动时重建数据库 | `false` |
| `socket.address` | TCP 监听地址 | — |
| `pulsar.url` | Pulsar 代理地址 | — |
| `pulsar.topic` | Pulsar 主题 | — |
| `pulsar.name` | Pulsar 生产者名称 | — |
| `log.dir` | 日志目录 | `./logs` |
| `log.maxage` | 日志保留天数 | `60` |
| `log.rotatehour` | 日志轮转间隔(小时) | `1` |

> 注意：TCP 和 Pulsar 可以同时启用。电报会先写入 SQLite，再通过所有启用的传输通道分发。

## 运行

### 测试环境

检查串口和数据库是否可用：

```bash
./tele-recv test
```

### 启动服务

```bash
./tele-recv start
```

服务启动后将：
1. 打开串口设备
2. 从串口读取数据，解析 ZCZC...NNNN 电报
3. 写入 SQLite 持久化
4. 通过 TCP 和/或 Pulsar 分发

## 测试

```bash
# 运行所有测试
task test

# 带竞态检测
task test-race

# 覆盖率报告
task test-cover

# 手动运行
go test -race -v ./...
```

当前测试覆盖 6 个包，30+ 测试用例，`go test -race` 零竞态。

## 下载

发布版本：[release](https://gitea.int.it2000.com.cn/airport/tele-recv/releases)

## 许可证

详见 [LICENSE](LICENSE)