210 lines
6.9 KiB
Markdown
210 lines
6.9 KiB
Markdown
---
|
||
tags: []
|
||
date created: 星期一, 十一月 24日 2025, 11:09:27 晚上
|
||
date modified: 星期一, 十一月 24日 2025, 11:09:40 晚上
|
||
---
|
||
|
||
# 2.5.3 外部数据交换契约 (External Data Exchange Contract)
|
||
|
||
**基线核心宗旨**：**“Contract First, Backwards Compatible (契约优先，向后兼容)”**。
|
||
外部接口定义语言 (IDL) 一旦发布，即视为法律条文，严禁随意修改。任何变更必须遵循严格的版本控制和兼容性法则，以确保服务器升级不会导致显控终端崩溃。
|
||
|
||
-----
|
||
|
||
## 1\. 核心设计契约 (Design Contracts)
|
||
|
||
1. **唯一标准 (Single Standard)**：
|
||
|
||
- 强制使用 **Google Protocol Buffers v3 (proto3)**。
|
||
- **理由**：proto3 移除了 `required` 字段，天然支持向后兼容（缺失字段使用默认值），极其适合迭代快速的分布式系统。
|
||
|
||
2. **包版本化 (Package Versioning)**：
|
||
|
||
- 所有 `.proto` 文件必须定义在带版本的包命名空间下，例如 `package radar.external.v1;`。
|
||
- **理由**：当发生破坏性变更（Breaking Change）时，可以通过引入 `v2` 包来实现并存，而不是破坏现有 `v1` 客户端。
|
||
|
||
3. **显式类型 (Explicit Typing)**：
|
||
|
||
- 时间戳必须显式注明单位（后缀 `_us` / `_ms`）。
|
||
- 枚举值（Enum）的第一个字段必须是 `UNKNOWN` 或 `UNSPECIFIED`（值为 0），作为默认零值安全网。
|
||
|
||
-----
|
||
|
||
## 2\. 协议文件组织 (File Organization)
|
||
|
||
为了规范管理，`.proto` 文件应按以下目录结构组织，并作为独立的构建目标（Target）：
|
||
|
||
```text
|
||
project_root/
|
||
└── protos/
|
||
└── radar/
|
||
└── external/
|
||
└── v1/
|
||
├── common.proto # 共享基础类型 (Point, Vector3)
|
||
├── track_data.proto # 核心业务数据 (Track, Plot, Batch)
|
||
└── system_status.proto # 系统健康状态
|
||
```
|
||
|
||
-----
|
||
|
||
## 3\. 核心模式定义基线 (Schema Baseline)
|
||
|
||
基于 **2.4.2** 确立的逻辑结构，将其固化为工程级的 Protobuf 定义。
|
||
|
||
### 3.1 基础类型定义 (`common.proto`)
|
||
|
||
```protobuf
|
||
syntax = "proto3";
|
||
package radar.external.v1;
|
||
|
||
// WGS84 地理坐标 (用于多站融合)
|
||
message GeoPoint {
|
||
double latitude = 1; // 纬度 (度)
|
||
double longitude = 2; // 经度 (度)
|
||
double altitude = 3; // 海拔 (米)
|
||
}
|
||
|
||
// 笛卡尔状态向量 (用于高精度跟踪)
|
||
message StateVector {
|
||
// ECEF 或 站心坐标系，具体由配置约定
|
||
double pos_x = 1;
|
||
double pos_y = 2;
|
||
double pos_z = 3;
|
||
double vel_x = 4;
|
||
double vel_y = 5;
|
||
double vel_z = 6;
|
||
}
|
||
```
|
||
|
||
### 3.2 核心业务数据 (`track_data.proto`)
|
||
|
||
```protobuf
|
||
syntax = "proto3";
|
||
package radar.external.v1;
|
||
|
||
import "radar/external/v1/common.proto";
|
||
import "radar/external/v1/system_status.proto";
|
||
|
||
// 2.4.2 确立的原子批次
|
||
message TrackDataBatch {
|
||
// --- Header ---
|
||
uint32 station_id = 1; // 站台ID
|
||
uint64 batch_sequence_id = 2; // 批次序号
|
||
uint32 checksum = 3; // CRC32c 校验和
|
||
uint64 timestamp_us = 4; // UTC 时间戳 (微秒)
|
||
uint64 trace_id = 5; // 全链路追踪ID
|
||
uint32 throttle_level = 6; // 当前热节流等级 (0-3)
|
||
|
||
// --- Payload ---
|
||
repeated TrackMessage tracks = 7; // 确认航迹
|
||
repeated PlotMessage plots = 8; // 原始点迹 (可被剪裁)
|
||
|
||
// 系统状态快照 (可选，通常低频发送或仅在变更时发送)
|
||
SystemStatusMessage system_status = 9;
|
||
}
|
||
|
||
message TrackMessage {
|
||
uint64 track_id = 1;
|
||
|
||
enum Status {
|
||
STATUS_UNSPECIFIED = 0;
|
||
STATUS_TENTATIVE = 1;
|
||
STATUS_CONFIRMED = 2;
|
||
STATUS_COAST = 3;
|
||
STATUS_LOST = 4;
|
||
}
|
||
Status status = 2;
|
||
|
||
StateVector state = 3; // 运动状态
|
||
repeated float covariance = 4; // 协方差矩阵 (对角线或下三角)
|
||
|
||
// 扩展属性
|
||
float probability = 5; // 存在概率
|
||
int32 classification = 6; // 目标分类 ID
|
||
}
|
||
|
||
message PlotMessage {
|
||
uint32 batch_id = 1; // 关联的 CPI ID
|
||
uint32 range_idx = 2;
|
||
uint32 doppler_idx = 3;
|
||
float snr = 4;
|
||
float azimuth_rad = 5;
|
||
float range_m = 6;
|
||
}
|
||
```
|
||
|
||
### 3.3 系统状态定义 (`system_status.proto`)
|
||
|
||
这是显控端感知服务器“健康度”的依据。
|
||
|
||
```protobuf
|
||
syntax = "proto3";
|
||
package radar.external.v1;
|
||
|
||
message SystemStatusMessage {
|
||
enum HealthState {
|
||
HEALTH_UNKNOWN = 0;
|
||
HEALTH_OK = 1;
|
||
HEALTH_DEGRADED = 2; // 降级 (如热节流中)
|
||
HEALTH_CRITICAL = 3; // 严重故障 (部分模块离线)
|
||
}
|
||
HealthState overall_health = 1;
|
||
|
||
// 关键资源指标
|
||
float gpu_temp_celsius = 2;
|
||
float gpu_util_percent = 3;
|
||
float mem_usage_percent = 4;
|
||
|
||
// 模块级状态 (简报)
|
||
map<string, string> module_states = 5; // e.g. {"SignalProcessor": "RUNNING"}
|
||
}
|
||
```
|
||
|
||
-----
|
||
|
||
## 4\. 演进与兼容性法则 (Evolution Laws)
|
||
|
||
在项目全生命周期中，**严禁**违反以下法则：
|
||
|
||
1. **禁止修改 Tag (Never Change Tags)**：
|
||
|
||
- 一旦字段 `uint32 station_id = 1;` 发布，Tag `1` 永远属于 `station_id`。即使该字段被废弃，Tag `1` 也不能分配给新字段。
|
||
|
||
2. **保留机制 (Reserved Strategy)**：
|
||
|
||
- 当删除字段时，必须使用 `reserved` 关键字锁定 Tag 和 Name，防止未来误用。
|
||
- *示例*：
|
||
|
||
```protobuf
|
||
message TrackMessage {
|
||
// uint32 old_field = 5; // Deleted
|
||
reserved 5;
|
||
reserved "old_field";
|
||
}
|
||
```
|
||
|
||
3. **默认值假设 (Default Value Assumption)**：
|
||
|
||
- 接收端（显控）**不能**依赖字段的存在性（`has_field`），必须处理字段缺失（即值为 0/false/empty）的情况。
|
||
- *设计推论*：如果 `0` 具有特殊业务含义（如 `range = 0` 表示雷达正中心），则必须小心。通常建议业务值的有效范围避开 `0`，或者使用 `oneof` 包装以获得存在性检查能力（但这会增加开销，非必要不推荐）。
|
||
|
||
-----
|
||
|
||
## 5\. 构建集成规范 (Build Integration)
|
||
|
||
- **代码生成**：使用 CMake 的 `protobuf_generate_cpp` 命令，在构建时自动生成 `.pb.h` 和 `.pb.cc`。
|
||
- **不可修改**：生成的 C++ 代码严禁人工修改，且不应提交到 Git 仓库（应作为构建产物）。
|
||
- **库依赖**：对外发布 SDK 时，应提供编译好的 `.proto` 文件或预编译的静态库，而不是让第三方依赖具体的 Protobuf 版本（尽量减少 DLL Hell）。
|
||
|
||
-----
|
||
|
||
## 总结
|
||
|
||
**2.5.3 章节基线** 已确立为：
|
||
|
||
1. **Standard**: Protobuf v3, Semantic Versioning (`v1`).
|
||
2. **Schema**: `TrackDataBatch` (Atomic), `GeoPoint` (WGS84).
|
||
3. **Compatibility**: Strict `reserved` policy, Explicit Zero Values.
|
||
|
||
这套契约不仅定义了数据格式，更定义了**团队协作的边界**——后端开发人员在修改 `.proto` 文件时，必须像修改法律条文一样谨慎。
|