Inbox/系统基座文件/2.5 工程基线总结报告 - 数据结构定义与序列化规范.md

tags, aliases, date created, date modified

tags	aliases	date created	date modified
	2.5 工程基线总结报告 - 数据结构定义与序列化规范 2.5 数据结构定义与序列化规范 - 工程基线总结报告	星期一, 十一月 24日 2025, 11:32:07 晚上	星期一, 十一月 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）均已完成深度设计与基线确立。我们构建了一套从物理层到应用层、从内部内存到外部网络的完整数据治理体系。