# UDP多播接收功能说明

## 概述

本功能实现了UDP多播接收逻辑，对应C++代码`TLogServer.cpp`中的接收广播机制。服务通过UDP多播接收COP（Common Object Protocol）协议数据，解析后交由`TranLogService`处理。

## 功能对应关系

### C++代码对应关系

| C++代码 | Java实现 | 说明 |
|---------|---------|------|
| `m_RecvCtrl.Start(m_iRecvPort, m_IP.c_str())` | `MulticastReceiverService.start()` | 启动UDP多播接收 |
| `m_RecvCtrl.AddGroup(m_GroupIPArray[GIPIndex].c_str(), m_IP.c_str())` | `MulticastReceiverService.start()` 中的 `socket.joinGroup()` | 加入多播组 |
| `m_RecvCtrl.RegisterCallback(CallbackFunc, this)` | `MulticastReceiverService.receiveLoop()` | 注册回调函数 |
| `CTranLogServer::CallbackFunc(COP_ITEM& item)` | `MulticastReceiverService.processReceivedData()` | 回调处理函数 |
| `CTranLogServer::Process(item)` | `TranLogService.process(item)` | 处理数据 |

## 配置说明

在 `application.yml` 中配置UDP多播接收参数：

```yaml
multicast:
  receiver:
    # 是否启用UDP多播接收
    enabled: true
    # 接收端口（对应C++的RecvPort）
    recv-port: 5000
    # 本地网络接口IP地址（对应C++的IPAddress）
    ip-address: 0.0.0.0
    # 多播组IP地址列表（对应C++的GroupIP0, GroupIP1, ...）
    group-ips:
      - 225.6.7.8
      # 可以配置多个多播组
      # - 225.6.7.9
    # 接收缓冲区大小（字节）
    buffer-size: 65536
    # 接收超时时间（毫秒）
    timeout: 1000
```

### 环境变量配置

也可以通过环境变量配置：

- `MULTICAST_RECEIVER_ENABLED`: 是否启用（默认：true）
- `MULTICAST_RECEIVER_PORT`: 接收端口（默认：5000）
- `MULTICAST_RECEIVER_IP`: 本地IP地址（默认：0.0.0.0）
- `MULTICAST_GROUP_IP_0`: 第一个多播组IP
- `MULTICAST_BUFFER_SIZE`: 缓冲区大小（默认：65536）
- `MULTICAST_TIMEOUT`: 超时时间（默认：1000）

## 核心组件

### 1. MulticastConfig

配置类，读取UDP多播接收相关配置。

**位置**: `com.afe.dc.tranlog.config.MulticastConfig`

### 2. MulticastReceiverService

UDP多播接收服务，负责：
- 创建并绑定UDP多播Socket
- 加入配置的多播组
- 接收UDP数据包
- 调用COP解析器解析数据
- 将解析后的数据传递给TranLogService处理

**位置**: `com.afe.dc.tranlog.service.MulticastReceiverService`

**生命周期**:
- `@PostConstruct`: 应用启动时自动启动接收服务
- `@PreDestroy`: 应用关闭时自动停止接收服务

### 3. COPParser

COP协议解析器，负责将UDP接收到的字节数据解析为`COPItem`对象。

**位置**: `com.afe.dc.tranlog.service.COPParser`

**功能**:
- 解析COP消息头（消息类型、ItemNo等）
- 解析FID字段数据
- 支持多种数据类型（CHAR、SHORT、INT、LONG、FLOAT、DOUBLE、STRING等）

**注意**: COP协议的具体格式可能需要根据实际协议规范进行调整。

## 数据流程

```
外部数据源（Data Provider）
    │
    │ (UDP 多播发送 COP 协议数据)
    ▼
MulticastReceiverService (接收端)
    │
    │ (接收UDP数据包)
    ▼
COPParser.parse() (解析COP协议)
    │
    │ (转换为COPItem对象)
    ▼
TranLogService.process() (处理数据)
    │
    ▼
TranDatabaseService (更新数据库)
```

## 启动和停止

### 自动启动

服务会在Spring Boot应用启动时自动启动（通过`@PostConstruct`注解）。

### 手动控制

可以通过配置`multicast.receiver.enabled=false`来禁用UDP多播接收功能。

### 停止

服务会在Spring Boot应用关闭时自动停止（通过`@PreDestroy`注解），包括：
- 离开所有多播组
- 关闭Socket
- 停止接收线程

## 日志

服务会输出以下关键日志：

- 启动成功：`[MulticastReceiverService] Started UDP multicast receiver on port: {port}, groups: {groups}`
- 加入多播组：`[MulticastReceiverService] Joined multicast group: {ip} on interface: {interface}`
- 接收数据：`[MulticastReceiverService] Processing COP item: itemNo={itemNo}, msgType={msgType}`
- 解析失败：`[COPParser] Failed to parse COP data`
- 处理失败：`[MulticastReceiverService] Failed to process COP item`

## 注意事项

1. **COP协议格式**: 当前实现的COP解析器是基于通用协议的假设。如果实际的COP协议格式不同，需要调整`COPParser`的解析逻辑。

2. **网络权限**: 在某些操作系统上，加入多播组可能需要特殊权限。

3. **防火墙**: 确保防火墙允许UDP数据包通过配置的端口。

4. **网络接口**: 如果配置了特定的IP地址，确保该IP地址对应的网络接口存在且可用。

5. **性能**: 接收缓冲区大小和超时时间可以根据实际网络环境调整。

## 故障排查

### 无法接收数据

1. 检查配置是否正确（端口、多播组IP）
2. 检查网络接口是否正确
3. 检查防火墙设置
4. 查看日志中的错误信息

### 解析失败

1. 检查COP协议格式是否与实现一致
2. 查看日志中的详细错误信息
3. 可能需要调整`COPParser`的解析逻辑

### 处理失败

1. 检查`TranLogService`的日志
2. 检查数据库连接
3. 检查数据格式是否正确

## 扩展

如果需要支持更多的COP协议特性，可以：

1. 扩展`COPParser`以支持更多的数据类型
2. 添加更多的FID字段解析逻辑
3. 添加数据验证和错误处理
4. 添加性能监控和统计