Inbox/系统基座文件/2/2.5/2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition).md

---
tags: []
aliases:
  - 2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)
date created: 星期一, 十一月 24日 2025, 10:39:09 晚上
date modified: 星期一, 十一月 24日 2025, 10:56:20 晚上
---

# 2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)

**基线核心宗旨**：**“Type-Safe & Traceable (类型安全与可追溯)”**。
内部控制事件不跨越进程边界（不涉及 Protobuf 序列化），它们是纯粹的 C++ 运行时对象。设计重心在于利用 C++ 类型系统防止误用，并强制携带全链路追踪上下文。

-----

## 1\. 核心设计契约 (Design Contracts)

1. **强制继承 (Mandatory Inheritance)**：

      - 所有在 `EventBus` 上流转的事件 **必须** 继承自 `BaseEvent`。
      - **理由**：确保所有事件天然携带 `TraceID` 和 `Timestamp`，实现无死角的审计与追踪。

2. **轻量级负载 (Lightweight Payload)**：

      - **禁止**：在事件对象中直接嵌入大块内存（如 `vector<float>` 原始波形数据）。
      - **允许**：状态码、配置参数、资源句柄（智能指针）、元数据摘要。
      - **理由**：控制平面应保持低延迟。大块数据应通过数据面（DataQueue）流转，控制面仅传递“指向数据的指针”或“操作指令”。

3. **值语义与移动优化 (Value Semantics & Move Semantics)**：

      - 事件对象默认按**值传递**（Copy/Move）。
      - 必须支持移动构造（Move Constructor），以便高效地在 `EventBus` 的异步队列中转移。

-----

## 2\. 根模式定义 (Root Schema)

这是所有控制信令的“父类契约”。

```cpp
/**
 * @brief 所有内部控制事件的基类
 * @note 即使是空事件，大小也至少为 16 字节 (TraceID + Timestamp)
 */
struct BaseEvent {
    // --- 上下文核心 (Context Core) ---
    
    // 全链路追踪 ID (从 TraceContext 自动捕获或继承)
    uint64_t trace_id;
    
    // 事件生成时的精确时间 (UTC Microseconds)
    // 用于计算控制指令在队列中的排队延迟 (Queueing Latency)
    uint64_t timestamp_us;

    // --- 构造基线 ---
    BaseEvent() {
        // 自动注入上下文，确保业务代码无需手动填写
        trace_id = TraceContext::getCurrentId(); 
        timestamp_us = Clock::nowInUs();
    }
    
    virtual ~BaseEvent() = default; // 允许作为基类指针传递（如果需要统一日志处理）
};
```

-----

## 3\. 核心事件分类定义 (Concrete Schemas)

基于 **2.3 章节** 确立的各个控制子系统，我们定义以下四类核心事件。

### 3.1 生命周期与编排类 (Lifecycle & Orchestration)

服务于 **2.3.3** 和 **2.3.4**。这类事件对**可靠性**要求最高。

```cpp
// 指令：启动模块
struct StartModuleEvent : public BaseEvent {
    std::string target_module; // 目标模块名
    // 可选：携带启动参数或配置覆盖
    // std::map<string, string> overrides; 
};

// 回执：模块运行中
struct ModuleRunningEvent : public BaseEvent {
    std::string module_name;
};

// 告警：模块故障 (Rich Context from 2.3.4)
struct ModuleFailedEvent : public BaseEvent {
    std::string module_name;
    ErrorCode error_code;      // 标准化错误码
    bool is_hardware_fault;    // 是否硬件故障 (决定是否熔断)
    std::string debug_info;    // 现场快照 (堆栈、显存状态等)
};
```

### 3.2 资源保护与仲裁类 (Resource & Safety)

服务于 **2.3.5**。这类事件对**响应速度**要求最高。

```cpp
// 告警：系统过载 (由监控模块发出)
struct SystemOverloadEvent : public BaseEvent {
    enum class Type { THERMAL, POWER, MEMORY };
    enum class Level { WARNING, CRITICAL };
    
    Type type;
    Level level;
    float current_value; // e.g., 95.5 (Celsius)
};

// 指令：执行节流 (由调度器发出)
struct SetComputeThrottleEvent : public BaseEvent {
    enum class Level { NO_THROTTLE, LIGHT, HEAVY, SUSPEND };
    Level level;
    // 接收方收到后，需立即调整 sleep 策略或丢包策略
};
```

### 3.3 配置热更新类 (Configuration Transaction)

服务于 **2.3.6**。这类事件需要承载**复杂负载**（配置数据）。

```cpp
// 事务：配置变更补丁
// 采用 RCU 模式，负载通过 shared_ptr 传递，避免深拷贝
struct ValidateConfigEvent : public BaseEvent {
    uint64_t config_version;
    // 使用智能指针传递复杂的配置树，确保事件本身轻量
    std::shared_ptr<const ConfigPatch> patch; 
};

// 提交：确认变更
struct CommitConfigEvent : public BaseEvent {
    uint64_t config_version; // 必须匹配 Validate 中的版本
};
```

### 3.4 性能遥测类 (Telemetry)

服务于 **2.3.7**。这类事件**吞吐量最大**，必须极致精简。

```cpp
// 遥测：指标快照
struct MetricsUpdateEvent : public BaseEvent {
    // 使用扁平化 Map 传输快照
    // Key 命名规范: "metric_name{tag=val,…}"
    std::unordered_map<std::string, double> metrics;
    
    // 优化建议：
    // 如果 std::unordered_map 造成频繁 malloc，
    // 可考虑使用预分配的 vector<MetricPair> 或类似 SmallVector 的优化容器
};
```

-----

## 4\. 模式设计自检 (Design Checklist)

| 检查项 | 符合标准 | 设计意图 |
| :--- | :--- | :--- |
| **继承关系** | ✅ Yes | 所有事件均继承自 `BaseEvent`，保证 TraceID 存在。 |
| **内存所有权** | ✅ Yes | 复杂对象（如 ConfigPatch）使用 `shared_ptr` 传递，避免总线拷贝大对象。 |
| **类型安全** | ✅ Yes | 避免使用 `void*` 或 `EventId` 整数流，利用 C++ 类型系统进行分发。 |
| **序列化无关** | ✅ Yes | 结构体中包含 `std::string` 等非 POD 类型，明确不直接用于网络传输（需经由 2.5.3 转换）。 |

-----

**总结**：
**2.5.2** 确立了控制平面的“通用语言”。这套定义确保了控制指令在进程内传输时：

1. **可追踪**（自带 TraceID）。
2. **低延迟**（避免大内存拷贝）。
3. **强类型**（编译期检查错误）。

这为 2.3 节定义的所有控制逻辑提供了坚实的数据结构支撑。