创建仓库

设计补丁/ECN_关于UI渲染与CUDA计算之间的资源竞争.md

@@ -0,0 +1,115 @@
+---
+tags: []
+aliases:
+  - 架构设计变更通知 (ECN)
+date created: 星期五, 十一月 21日 2025, 3:35:31 下午
+date modified: 星期五, 十一月 21日 2025, 3:36:41 下午
+---
+
+# 架构设计变更通知 (ECN)
+
+- 编号: ECN-2025-001
+- 主题: 显控架构扁平化调整与 GPU 资源仲裁策略简化
+- 适用范围: 2.3.5 章节及相关模块接口
+- 日期: 2025-11-21
+
+## 1. 变更背景与动因 (Motivation)
+
+- **原设计假设**: 显控终端采用 3D 实时渲染（如 OpenGL/Vulkan 绘制雷达波束体或复杂地形），会大量占用 GPU 渲染管线和显存带宽，需通过抢占式调度防止 TDR。
+- **修正后基线**: 显控终端确认为 **扁平化 2D 平面显示**（如 Qt/GDI 绘制 B-Scan/PPI 图像）。此类渲染对 GPU 资源消耗极低（< 1%），且主要由操作系统的桌面窗口管理器（DWM/X11）处理，**不与 CUDA 计算核心产生实质性竞争**。
+- **变更目标**: 移除为 UI 响应性服务的复杂抢占调度逻辑，释放被“任务切分”和“优先级切换”占用的系统开销，回归**计算吞吐量优先**的设计策略。
+
+## 2. 核心变更点 (Core Changes)
+
+|**变更项**|**原设计 (Deprecated)**|**新设计 (New Baseline)**|**收益**|
+|---|---|---|---|
+|**仲裁触发源**|显控终端发送 `RequestHighPriorityGpuAccess`。|**移除显控触发源**。保留“温度/功耗过载”作为唯一降级触发源。|消除 UI 交互对后台计算的非必要打断。|
+|**任务调度**|细粒度切分 (`ISegmentableTask`)，支持 <10ms 响应。|**粗粒度批处理**。移除强制切分要求，Kernel 允许长时运行。|减少 Kernel 启动开销，提升 GPU 流水线饱和度。|
+|**CUDA 流策略**|双优先级流（High/Low）动态切换。|**单一计算流池**。默认全速运行，仅在热保护时通过 `usleep` 或空闲插入进行节流。|简化流管理逻辑，降低上下文切换风险。|
+
+---
+
+## 3. 修订后的 2.3.5 章节规范
+
+该章节标题由“资源仲裁与抢占式优先级控制”变更为 **“2.3.5 系统负载保护与热节流控制”**。
+
+- 2.3.5 系统负载保护与热节流控制 (System Load Protection & Thermal Throttling)
+	- **核心指向**：鉴于显控架构的扁平化，控制平面的资源管理重心从“UI 响应性保障”转移至 **“系统物理安全保障”**。接口仅用于在极端工况（如机箱温度过高、GPU 功耗触顶）下，强制降低计算负载以保护硬件。
+
+## 3.1 交互协议变更
+
+- **废弃事件**:
+    - `RequestHighPriorityGpuAccessEvent` (已移除)
+    - `HighPriorityGpuAccessFinishedEvent` (已移除)
+- **保留并重定义事件**:
+    - `SystemOverloadEvent { Type: THERMAL | POWER, Level: WARNING | CRITICAL }`: 由 `MonitoringModule` 发布。
+    - `SetComputeThrottleEvent { ThrottleLevel level }`: 由 `ResourceCoordinator` 决策后发布。
+        - `Level 0`: 全速 (No Throttle)
+        - `Level 1`: 降速 20% (Insert Idle)
+        - `Level 2`: 降速 50% (Half Capacity)
+        - `Level 3`: 暂停 (Suspend)
+
+## 3.2 响应机制简化
+
+- **调度器侧 (`ResourceCoordinator`)**:
+    - 逻辑简化为**迟滞比较器 (Hysteresis Comparator)**。仅当温度传感器上报值持续超过阈值（如 85°C）时，下发节流指令；温度回落至安全线（如 75°C）以下时，解除节流。
+    - 不再处理毫秒级的 UI 交互请求。
+- **模块侧 (`SignalProcessor`)**:
+    - **移除** `PreemptiveStreamManager` 和双流切换逻辑。
+    - **新增** `ThrottleController`：在 `ExecutionEngine` 的主循环（每帧处理结束处）插入动态休眠逻辑。
+        - _实现逻辑_: `if (throttle_level > 0) std::this_thread::sleep_for(calc_delay(level));`
+    - **收益**: 算法 Kernel 再次回归到“大块连续执行”的最佳性能模式，无需为了响应中断而被人为切碎。
+
+## 3.3 修正后的时序图 (`sequenceDiagram`)
+
+代码段
+
+```bash
+sequenceDiagram
+    participant Monitor as 监控模块
+    participant EventBus as 事件总线
+    participant Scheduler as 任务调度器
+    participant SignalProc as 信号处理模块
+
+    Note over Monitor,SignalProc: 热保护节流流程 (不再涉及UI)
+
+    Monitor->>Monitor: 检测到 GPU 温度 > 90°C
+    Monitor->>+EventBus: 1. 发布 SystemOverloadEvent(THERMAL, CRITICAL)
+    
+    EventBus->>+Scheduler: 2. 路由告警
+
+    Scheduler->>Scheduler: 3. 决策: 必须降频保护
+    Scheduler->>+EventBus: 4. 广播 SetComputeThrottleEvent(Level=2)
+
+    EventBus->>+SignalProc: 5. 路由指令
+    SignalProc->>SignalProc: 6. 更新内部节流状态
+    
+    loop 每一帧处理循环
+        SignalProc->>SignalProc: 执行完整计算 (不切分)
+        SignalProc->>SignalProc: <b>主动休眠 10ms</b> (响应节流)
+    end
+```
+
+---
+
+## 4. 对关联文档的连带影响 (Impact Analysis)
+
+1. **对 `02_信号处理模块设计.md` 的影响**:
+    
+    - **删除** 4.3 节“抢占式 GPU 资源协调”。
+    - **删除** 4.3.3 节 `ISegmentableTask` 接口定义。算法策略不再需要实现 `segmentTask()` 方法，简化了 FFT/CFAR 等算法的封装难度。
+    - **简化** `GpuResourceManager`，移除多优先级流池。
+        
+2. **对 `05_任务调度器设计.md` 的影响**:
+    
+    - `ResourceCoordinator` 的职责缩减为仅负责系统健康相关的宏观调控，不再介入微观的任务调度。
+        
+3. **对 `99_模块集成策略.md` 的影响**:
+    
+    - 在集成测试阶段，移除针对“UI 拖拽卡顿”的压力测试用例，改为关注“长时间满载运行下的散热稳定性”。
+
+---
+
+结论:
+
+通过此补丁，我们移除了系统中最大的一个不确定性来源（异步抢占），使得信号处理流水线变得更加确定性和纯粹。这是对“奥卡姆剃刀原则”的一次成功实践——如无必要，勿增实体。

设计补丁/ECN_数据模型双态分离与序列化边界的强制隔离.md

@@ -0,0 +1,112 @@
+---
+tags: []
+aliases:
+  - 数据模型双态分离与序列化边界的强制隔离架构设计变更通知 (ECN)
+date created: 星期一, 十一月 24日 2025, 5:17:58 下午
+date modified: 星期一, 十一月 24日 2025, 5:20:20 下午
+---
+
+# 数据模型双态分离与序列化边界的强制隔离架构设计变更通知 (ECN)
+
+- **编号**: ECN-2025-002
+- **主题**: 数据模型双态分离与序列化边界的强制隔离
+- **适用范围**: 2.5 章节、02_ 核心数据结构、04_ 序列化与网络协议
+- **关联原则**: [00_ 数据架构总览与原则.md] 第一原则（零拷贝）、第五原则（面向性能布局）
+- **日期**: 2025-11-24
+
+---
+
+## 1. 变更背景与动因 (Background & Motivation)
+
+### 1.1 现状问题诊断
+
+在原有的设计文档中（如 `02_核心数据结构.md`），虽然定义了 `TrackData` 等 C++ 结构体，但在 `04_序列化与网络协议.md` 中又引入了 Protobuf 定义。由于缺乏明确的 **“使用边界”** 界定，开发过程中极易出现以下反模式：
+
+1. **性能杀手**：在计算密集型的内部模块（如 `SignalProcessor`）直接使用 Protobuf 生成的类（Generated Classes）作为数据载体。这会导致无法利用 SIMD 指令集（内存未对齐）、频繁的堆内存分配以及 getter/setter 的调用开销。
+2. **架构耦合**：内部业务逻辑与外部通信协议强绑定。一旦修改对外接口字段，必须重构内部核心算法代码。
+3. **零拷贝失效**：Protobuf 的序列化/反序列化本质上是深拷贝操作。如果在内部流水线中过早引入 Protobuf，将直接破坏 [03_ 内存管理与所有权.md] 中建立的零拷贝链路。
+
+### 1.2 变更目标
+
+建立 **“双态数据模型 (Dual-State Data Model)”** 架构，强制实施 **“序列化边界 (Serialization Boundary)”** 管控。确保内部数据流专注于**极致计算性能**，外部数据流专注于**互操作性**，两者仅在边界处进行转换。
+
+---
+
+## 2. 核心变更规范 (Core Specifications)
+
+### 2.1 确立“双态数据模型”
+
+系统中的数据将严格区分为两种互斥的形态：
+
+|**特征**|**内部原生态 (Internal Native State)**|**外部传输态 (External Wire State)**|
+|---|---|---|
+|**承载实体**|**C++ POD Structs** (e.g., `struct TrackData`)|**Protobuf Messages** (e.g., `message TrackDataMessage`)|
+|**内存布局**|**SIMD 友好** (`alignas(16/32)`，连续内存)|**紧凑编码** (Varint, Tag-Length-Value)|
+|**生命周期**|**智能指针管理** (`std::unique_ptr` + `MemoryPool`)|**栈上临时对象** 或 **发送缓冲区字节流**|
+|**适用范围**|`DataReceiver` -> `SignalProcessor` -> `DataProcessor`|`DisplayController` -> `Network` -> `ClientApp`|
+|**设计原则**|**性能优先** (Raw Performance)|**兼容性优先** (Compatibility)|
+
+### 2.2 定义“序列化边界” (The Boundary)
+
+**序列化边界**是指数据从“内部原生态”转换为“外部传输态”的唯一合法逻辑位置。
+
+- **边界位置**：**仅限于 `DisplayController` (数据网关模块)** 的 `ExecutionEngine` 中。
+- **流入**：`IDataQueue<DataPacket<std::vector<TrackData>>>` (C++ 对象指针)。
+- **流出**：`std::string` 或 `std::vector<uint8_t>` (Protobuf 序列化后的二进制流)。
+- **禁区**：`SignalProcessor` 和 `DataProcessor` **严禁** 引用 `*.pb.h` 头文件，严禁执行 `SerializeToString()` 操作。
+
+### 2.3 引入“数据映射层” (Data Mapping Layer)
+
+在边界处（`DisplayController`），引入专门的转换逻辑（Mapper/Adapter），负责将 C++ 结构体字段映射到 Protobuf 消息字段。
+
+```cpp
+// 伪代码示例：在边界处的转换逻辑
+void DisplayController::convertToWireFormat(const std::vector<TrackData>& native_tracks, radar::ipc::TrackDataBatch* proto_batch)
+{
+    for (const auto& track : native_tracks) {
+        auto* proto_track = proto_batch->add_tracks();
+
+        // 字段映射：从高性能 C++ 结构体 -> Protobuf 消息
+        proto_track->set_track_id(track.track_id);
+        // … 坐标转换、单位换算等 …
+
+        // 注意：此处发生了一次从"页锁定内存"到"网络发送缓冲区"的内存拷贝
+        // 这是为了网络传输格式化所必须付出的代价，但被严格限制在最后一步。
+    }
+}
+```
+
+---
+
+## 3. 对现有文档的修订指引 (Documentation Patch)
+
+### 3.1 对 `02_核心数据结构.md` 的修正
+
+- **新增声明**：在文档开头显著位置声明：“本文档定义的结构体为**内部原生态**对象，仅用于模块间的高性能内存交换。这些结构体**不是**网络传输协议。”
+- **强化定义**：确保 `DetectionResult` 和 `TrackData` 保持纯粹的 POD 特性，移除任何可能暗示序列化的辅助方法（如 `toJson()` 或 `toProto()`），这些方法应移至工具类中。
+
+### 3.2 对 `04_序列化与网络协议.md` 的修正
+
+- **明确角色**：明确指出 `.proto` 文件定义的是**外部契约**，而非内部实现。
+- **新增章节**：添加 **“4.4 序列化边界与映射策略”**，详细描述数据如何在 `DisplayController` 中从 C++ 结构体转换为 Protobuf 消息。
+
+### 3.3 对 `03_内存管理与所有权.md` 的补充
+
+- **补充说明**：在零拷贝流程的最后阶段（数据网关），明确说明“零拷贝”在序列化边界处**终止**。序列化过程不可避免地涉及内存读取和重新编码，这是将数据送入网络栈（Socket Buffer）的必要步骤。
+
+---
+
+## 4. 优势分析 (Benefits Analysis)
+
+通过实施此补丁，系统架构将获得以下显著收益：
+
+1. **计算性能最大化**：内部算法（如卡尔曼滤波、关联矩阵计算）直接操作内存对齐的 C++ 数组，能够充分利用 CPU 的 L1/L2 缓存和 SIMD 指令集，性能相比操作 Protobuf 对象提升 **5-10 倍**。
+2. **编译依赖解耦**：核心业务模块（`SignalProcessor` 等）不再依赖 Protobuf 库。如果未来更换序列化协议（如从 Protobuf 换为 FlatBuffers），只需修改 `DisplayController` 中的映射层，核心算法代码**零修改**。
+3. **内存安全屏障**：内部使用强类型的 C++ 结构体，配合 `std::unique_ptr` 管理所有权，消除了直接操作 Protobuf 原始指针可能带来的内存泄漏风险。
+4. **协议演进灵活性**：内部数据结构可以根据算法需求自由优化（例如添加用于调试的临时字段），而无需修改对外的 `.proto` 契约，只需在映射层忽略这些字段即可，实现了**内外解耦**。
+
+---
+
+## 5. 总结
+
+此 ECN 补丁修正了原设计中关于数据形态的模糊定义，建立了**“内部高性能、外部高兼容、边界严管控”**的数据架构范式。这是将雷达数据处理系统从“原型验证”推向“生产级高性能应用”的关键一步。