---
tags: []
aliases:
  - 2.5 工程基线总结报告 - 数据结构定义与序列化规范
  - 2.5 数据结构定义与序列化规范 - 工程基线总结报告
date created: 星期一, 十一月 24日 2025, 11:32:07 晚上
date modified: 星期一, 十一月 24日 2025, 11:32:24 晚上
---

# 2.5 工程基线总结报告 - 数据结构定义与序列化规范

**适用范围**: 全系统（数据面 + 控制面）

## 1. 核心架构基线 (Core Architecture Baselines)

| 决策领域 | 核心基线 (Baseline Established) | 关键技术特征 (Key Specs) | 设计意图/依据 |
| :--- | :--- | :--- | :--- |
| **2.5.1 内部对象** | **高性能 POD (High-Perf POD)** | **Strict POD**, `alignas(32)`, **定长数组** (非 `std::vector`)。 | 适配 CPU 缓存行与 SIMD (AVX/NEON) 指令，最大化计算吞吐。 |
| **2.5.2 内部事件** | **类型安全信令 (Type-Safe Signaling)** | 强制继承 `BaseEvent`，**强制携带 TraceID**，轻量级负载。 | 确保控制指令在进程内分发时的低延迟与全链路可追溯性。 |
| **2.5.3 外部契约** | **Protobuf v3** | 语义化版本控制，**原子批次 (Atomic Batch)**，向后兼容设计。 | 提供跨语言/跨平台的稳定性，支持分布式多站标识 (`StationID`)。 |
| **2.5.4 数据容器** | **仅移动语义 (Move-Only)** | `DataPacket<T>` 模板，`unique_ptr` 所有权管理，**禁止拷贝**。 | 利用 C++ 类型系统物理杜绝深拷贝，保障零拷贝架构的安全性。 |
| **2.5.5 转换边界** | **显式映射 (Explicit Mapping)** | **静态转换器 (Converter)**，节流感知清洗，单向隔离。 | 隔离内部计算模型的变更对外部契约的影响，防止序列化开销污染计算核心。 |

---

## 2. 关键技术规范详解

### 2.5.1 内部高性能业务对象 (Internal DTOs)

- **点迹 (`DetectionResult`)**:
    - **对齐**: `alignas(16)` (适配 128-bit 寄存器)。
    - **布局**: AoS (Array of Structures)，显式 Padding 填充至 48 字节。
- **航迹 (`TrackData`)**:
    - **对齐**: `alignas(32)` (适配 256-bit 寄存器)。
    - **容器**: 使用 **定长数组 (`float state[8]`)** 替代 `std::vector`，消除指针跳转与缓存未命中。
- **集合**: 使用带对齐分配器的 `AlignedVector<T>`。

### 2.5.2 内部控制事件 (Internal Events)

- **根契约**: `BaseEvent` 包含 `uint64_t trace_id` 和 `uint64_t timestamp_us`。
- **分类规范**:
    - **生命周期类**: 携带 `ErrorCode` 和 `Snapshot` (用于故障现场还原)。
    - **资源类**: 携带 `ThrottleLevel` (用于热保护)。
    - **配置类**: 使用 `std::shared_ptr<ConfigPatch>` (用于 RCU 无锁更新)。
    - **遥测类**: 使用 `FlatMap` 或预分配容器 (用于高频无锁上报)。

### 2.5.3 外部数据交换契约 (External Contract)

- **Schema 定义**:
    - **根对象**: `TrackDataBatch` (对应一个 CPI)。
    - **分布式支持**: 必须包含 `station_id` 和 `timestamp_us` (UTC)。
- **演进法则**:
    - **严禁修改 Tag**。
    - 废弃字段必须使用 `reserved` 锁定。
    - 接收端必须处理字段缺失（默认值）情况。

### 2.5.4 零拷贝数据容器 (Data Container)

- **结构**: `DataPacket<PayloadType>`。
    - **Header**: 包含 `TraceID`, `SequenceID`, `SourceModule`。
    - **Payload**:
        - **Raw Data**: `unique_ptr` + `MemoryPoolDeleter` (自动归还页锁定内存)。
        - **Struct Data**: `std::vector` (移动语义传递)。
- **安全**: 拷贝构造函数 `= delete`，强制使用 `std::move`。

### 2.5.5 序列化边界与映射 (Boundary & Mapping)

- **合法边界**:
    - **数据面**: `DisplayController` (C++ -> Protobuf)。
    - **控制面**: `ApiCommandService` (Internal State -> JSON/Proto)。
- **转换逻辑**:
    - **单位统一**: 内部 SI 单位 (米/秒) -> 外部 SI 单位。
    - **节流清洗**: 根据 `throttle_level` 动态丢弃低优先级字段（如点迹、协方差矩阵）。
    - **脱敏**: 剔除内部使用的指针地址 (`void*`) 和临时 ID。

---

## 3. 风险与应对 (Risk Mitigation)

| 潜在风险 | 现象 | 应对/缓解措施 |
| :--- | :--- | :--- |
| **ABI 兼容性** | 内部结构体变更导致内存错乱。 | 内部对象严禁跨进程传输。仅通过重新编译解决内部依赖，外部依赖完全隔离于 Protobuf 边界。 |
| **缓存行伪共享** | 多线程写入 `DataPacket` Header 导致性能下降。 | Header 设计紧凑（<64B），且数据包在流转时通常由单线程独占访问（所有权转移），天然避免竞争。 |
| **序列化开销** | Protobuf 编码占用过多 CPU。 | 在 `DisplayController` 独立 IO 线程中执行；利用 L2 级热节流主动减少编码对象数量。 |

---

**结论**：
至此，**第二章：数据接口与通信协议** 的所有子章节（2.1 - 2.5）均已完成深度设计与基线确立。我们构建了一套从物理层到应用层、从内部内存到外部网络的完整数据治理体系。