Inbox/系统基座文件/2/2.5/2.5 数据结构定义与序列化规范.md

tags, aliases, date created, date modified

tags	aliases	date created	date modified
	2.5 数据结构定义与序列化规范 (Data Structure Definition & Serialization Specification)	星期一, 十一月 24日 2025, 5:21:10 下午	星期一, 十一月 24日 2025, 5:21:21 下午

2.5 数据结构定义与序列化规范 (Data Structure Definition & Serialization Specification)

• 覆盖范围：定义系统内外部数据交互的静态契约。该规范严格区分 “内部原生对象（In-Memory Native Objects）” 与 “外部传输契约（On-Wire Contracts）”，并界定两者之间的转换边界。内部关注极致的计算性能（SIMD 对齐、零拷贝），外部关注跨语言/跨平台的互操作性（Protobuf）。
  • 2.5.1 内部高性能业务对象模型 (Internal High-Performance Business Object Model)
    • 核心指向：定义在 DataReceiver -> SignalProcessor -> DataProcessor 流水线中流转的 C++ 原生结构体（DTO）。涵盖 DetectionResult（点迹）和 TrackData（航迹）的内存布局设计，强制使用 POD (Plain Old Data) 类型，并应用 alignas(16/32) 以适配 SIMD (AVX/NEON) 向量化指令优化，严禁在核心计算路径上使用虚函数或复杂对象。
  • 2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)
    • 核心指向：定义在 EventBus 上流转的控制信令结构。所有事件必须继承自 BaseEvent，并强制包含 全链路追踪 ID (TraceID) 和 高精度时间戳。事件负载（Payload）必须保持轻量（通常仅包含状态码、配置键值对或对象 ID），严禁携带大块业务数据（如 I/Q 波形），以保障控制平面的低延迟响应。
  • 2.5.3 外部数据交换契约 (External Data Exchange Contract)
    • 核心指向：定义系统向外部（显控终端、API 网关）输出数据的接口定义语言 (IDL)。强制选用 Google Protobuf (v3) 作为唯一标准。涵盖 .proto 文件的版本管理规范（语义化版本控制），以及字段的 向前/向后兼容性 设计原则（如使用 optional 字段，保留 reserved 标识符），确保前后端可独立演进。
  • 2.5.4 零拷贝数据容器规范 (Zero-Copy Data Container Specification)
    • 核心指向：定义承载内部业务对象的通用包装器 DataPacket<T>。涵盖其 Header 的标准化元数据（序列号、源模块、TraceID），以及 Payload 的所有权管理机制——必须使用 std::unique_ptr 配合 自定义删除器 (Custom Deleter)，以实现内存块在生命周期结束时的自动归还（回收到 MemoryPool），彻底消除内存泄漏风险。
  • 2.5.5 序列化边界与映射策略 (Serialization Boundary & Mapping Strategy)
    • 核心指向：定义“内部对象”转换为“外部格式”的唯一合法位置。明确规定 仅在 DisplayController（数据网关） 和 ApiCommandService（API 响应） 处进行序列化操作。涵盖从 C++ Struct 到 Protobuf Message 的字段映射逻辑（Mapping Logic），以及在边界处进行 数据清洗与脱敏 的安全规范。

---

核心变更点解析：

1. 分离定义：明确将 2.5.1 (内部高性能 C++) 与 2.5.3 (外部 Protobuf) 分开。旧设计可能在内部也混用了序列化对象，这是性能杀手，新设计予以纠正。
2. 容器规范：新增 2.5.4，将 DataPacket<T> 和智能指针管理提升为核心规范，这是“零拷贝”落地的关键载体。
3. 边界管控：新增 2.5.5，显式定义“序列化边界”。这是架构师视角的管控点，防止开发人员在内部模块（如信号处理）随意进行序列化导致性能劣化。