eis/docs/superpowers/specs/2026-05-13-rng-parameterized-models-design.md

# RNG 参数化随机数生成 — 设计规格

## 概述

将 RNG 从硬编码的信号→数据源映射重构为配置驱动的参数化模型架构，使随机数/仿真数据的生成完全由外部配置控制，无需修改 C++ 代码即可定义新的信号行为。

## 核心设计决策

- **模型模板与信号绑定分离**：模型模板定义在 `rng_models.json`，每个信号通过 DB2 表 `T_LOV_FDAAITEM` 的 `tables[1]` 字段引用模型名
- **每个信号独立实例化**：即使 100 个信号用同一个模型模板，各自创建独立实例，状态不共享
- **基值参数取自 defaultValue**：`TeleItem.defaultValue` 天然作为 `c`(constant)、`b`(linear)、`offset`(sine)、`base`(spike/drift)、`mean`(normal) 的默认值
- **纯 JSON 参数透传**：模型构造函数直接解析 JSON params key-value，工厂不关心具体参数内容

## 模型模式

### 模拟量模式

| mode | 函数 | 从 defaultValue 取的基值 | 模板 params |
|------|------|------------------------|------------|
| `constant` | y = c | c | — |
| `linear` | y = k·t + b | b | k |
| `sine` | y = A·sin(ω·t + φ) + offset | offset | A, ω, φ |
| `normal` | y = μ + σ·N(0,1) | μ | σ |
| `uniform` | y = random(−Δ, +Δ) + center | center | Δ |
| `spike` | y = base + spike(t) | base | amplitude, probability |
| `drift` | y = base + rate·t | base | drift_rate |
| `csv` | y = csv(t, col) | — | file, column |
| `composite` | y = base(t) + noise(t) | — | base_model, noise_model |

t 为时间索引，从进程启动起每周期（~20ms）递增。

### 布尔量模式

| mode | 行为 | 模板 params |
|------|------|------------|
| `bool_random` | 随机 0/1，可配置为 1 的概率 | prob_true (default 0.5) |
| `bool_toggle` | 固定周期 0/1 翻转 | period_ms |
| `bool_csv` | CSV 数据回放（int 列） | file, column |
| `valve_pair` | 跟随另一个信号，加延迟/闪断/抖动/超时 | on_delay_ms, off_delay_ms, delay_jitter_ms, flash_prob, delay_over_prob, delay_over_ms |

### spike 毛刺行为

- 每个周期以 `probability` 概率触发毛刺
- 触发时 y = base ± amplitude（符号随机）
- 毛刺持续 1 个周期后恢复

### drift 漂移行为

- y = base + drift_rate × t
- 漂移累加无上限，模拟传感器退化趋势

### valve_pair 时序模型

不模拟动作信号本身，而是通过模型名引用另一个信号（如 `bool_toggle`）的当前值，模拟传感器对动作的响应延迟。

参数说明：

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `on_delay_ms` | 阀开到位延迟（ms），信号 0→1 后传感器多久变 1 | 必填 |
| `off_delay_ms` | 阀关到位延迟（ms），信号 1→0 后传感器多久变 0 | 必填 |
| `delay_jitter_ms` | 延迟抖动范围，实际延迟 = delay ± random(0, jitter) | 0 |
| `flash_prob` | 高电平期间每周期出现闪断的概率 | 0 |
| `delay_over_prob` | 每次阀动作时触发超时的概率（on/off 独立判断） | 0 |
| `delay_over_ms` | 超时时的延迟值，替代正常延迟 | 0 |

正常时序（无超时，有抖动）：

```
动作信号 A:
    ────────────┐                  ┌────────────────
                │                  │
                ├── on_delay ──→   ├── off_delay ──→
传感器 B:       │  ±jitter        │  ±jitter
    ────────────┘                  └────────────────
                └─ 阀芯移动 ──→    └─ 阀芯复位 ──→
```

超时场景（delay_over_prob 触发时）：

```
动作信号 A:
    ────────────┐
                │
                ├──────── on_delay_over (4000ms) ────────→   正常 off_delay
传感器 B:       │                                          ┌────── ...
    ────────────┘                                          │
                                                           └── 超时! 远超正常范围
```

- 每次 A 跳变时（0→1 或 1→0），以 `delay_over_prob` 概率独立判断是否超时
- 超时时延迟 = `delay_over_ms`，未超时时延迟 = `delay_ms` ± random(0, `delay_jitter_ms`)
- 闪断：高电平期间以 `flash_prob` 概率单周期归零后自动恢复
- `delay_over_prob = 0` = 永不超时；`delay_jitter_ms = 0` = 无抖动
- on 和 off 方向各自由各自概率独立触发超时

配对方式：B 的 `tables[1]` = `valve_px_std:toggle_2s`，其中 `toggle_2s` 是 A 的模型名。运行时通过模型名查找动作信号的 IModel 实例。

一对多自然支持：同一个动作信号可被多个 valve_pair 传感器跟随，各自维护独立的延迟/闪断状态。

## JSON 配置格式

文件路径：`/users/dsc/code/TestProject/RNG/json/rng_models.json`（Linux 运行环境固定路径）

```json
{
  "models": {
    "normal_tiny":    { "mode": "normal",     "params": { "sigma": 0.01 } },
    "normal_med":     { "mode": "normal",     "params": { "sigma": 0.5 } },
    "linear_slow":    { "mode": "linear",     "params": { "k": 0.001 } },
    "linear_fast":    { "mode": "linear",     "params": { "k": 0.05 } },
    "sine_ecc1":      { "mode": "sine",       "params": { "A": 5.0, "omega": 0.314, "phi": 0 } },
    "sine_ecc2":      { "mode": "sine",       "params": { "A": 3.0, "omega": 0.628, "phi": 1.57 } },
    "spike_sharp":    { "mode": "spike",      "params": { "amplitude": 50,  "probability": 0.05 } },
    "spike_mild":     { "mode": "spike",      "params": { "amplitude": 10,  "probability": 0.15 } },
    "drift_slow":     { "mode": "drift",      "params": { "drift_rate": 0.0001 } },
    "drift_fast":     { "mode": "drift",      "params": { "drift_rate": 0.005 } },
    "toggle_2s":      { "mode": "bool_toggle", "params": { "period_ms": 2000 } },
    "toggle_5s":      { "mode": "bool_toggle", "params": { "period_ms": 5000 } },
    "toggle_10s":     { "mode": "bool_toggle", "params": { "period_ms": 10000 } },
    "valve_px_std":   { "mode": "valve_pair", "params": { "on_delay_ms": 200, "off_delay_ms": 150, "delay_jitter_ms": 20, "flash_prob": 0.02, "delay_over_prob": 0.0001, "delay_over_ms": 4000 } },
    "valve_px_fast":  { "mode": "valve_pair", "params": { "on_delay_ms": 80,  "off_delay_ms": 60,  "delay_jitter_ms": 10, "flash_prob": 0.01, "delay_over_prob": 0,       "delay_over_ms": 0 } }
  }
}
```

## DB2 信号绑定

每个信号在 `T_LOV_FDAAITEM` 表中通过 `tables[1]` 字段指定模型引用。

### tables[1] 语法

| 格式 | 含义 | 示例 |
|------|------|------|
| `model_name` | JSON 中定义的模型 | `normal_tiny` |
| `csv:file_name:col` | CSV 文件回放（内联简写） | `csv:C308速度毛刺仿真.csv:1` |
| `base_model+noise_model` | 组合模型 | `linear_slow+normal_tiny` |
| `pair_model:action_model` | 布尔配对模型（仅 valve_pair） | `valve_px_std:toggle_2s` |
| 空 / `default` | 默认模型 `normal_tiny` | — |

### 示例数据行

| item | defaultValue | tables[1] | 说明 |
|------|-------------|-----------|------|
| BR1_1_V_act | 100.0 | `normal_tiny` | 均值100的正态噪声 |
| BR1_2_V_act | 120.0 | `normal_tiny` | 同上模板，独立实例 |
| BR2_2_I_act | 0.0 | `csv:spbdata:1` | CSV第1列回放 |
| TCM-4-82-BD-1-101 | 80.0 | `sine_ecc1` | 幅值5周期0.314的正弦 |
| TCM-72-150-BD-5-117 | 75.0 | `sine_ecc1` | 同上模板，独立实例 |
| RW_o_Drv_SpdErr | 0.0 | `linear_slow+spike_mild` | 线性爬升叠加毛刺 |
| 3G-DSA-B01-01B | 0 | `toggle_2s` | 2秒周期翻转（动作阀） |
| 3G-PX-B01-01 | 0 | `valve_px_std:toggle_2s` | 跟随动作阀的到位传感器 |

## 软件架构

### 文件结构

```
TestProject/RNG/
├── model/
│   ├── IModel.h              # 统一接口
│   ├── ModelRegistry.h/cc    # 工厂 + tables[1] 解析
│   ├── NormalModel.h
│   ├── LinearModel.h
│   ├── SineModel.h
│   ├── UniformModel.h
│   ├── SpikeModel.h
│   ├── DriftModel.h
│   ├── CsvReplayModel.h
│   ├── BoolRandomModel.h
│   ├── BoolToggleModel.h
│   ├── BoolCsvModel.h
│   ├── ValvePairModel.h
│   └── CompositeModel.h
├── json/                     # nlohmann_json (已有)
├── Generator.h/cc            # 重构：去掉硬编码，走 ModelRegistry
├── RNG_icei.h/cc             # 不变
├── RNG.h/cc                  # 启动时加载 rng_models.json
├── RandT.h                   # 保留，底层数学工具
├── read_csv.hpp              # 保留，CsvReplayModel 内部使用
└── CMakeLists.txt            # 新增 model/ 源文件
```

### 关键接口

```cpp
// IModel.h — 所有模型的基类
class IModel {
public:
  virtual ~IModel() = default;
  virtual float  evaluate(size_t t_index);        // 模拟量，默认返回0
  virtual bool   evaluateBool(size_t t_index);    // 布尔量，默认返回false
  virtual void   linkPeers(ModelRegistry& reg);   // 配对信号关联，默认空
  virtual void   reset();                         // 重置内部状态
};

// ModelRegistry — 单例
class ModelRegistry {
public:
  using Ctor = std::function<std::unique_ptr<IModel>(const json& params, float defaultVal)>;

  void loadModels(const std::string& jsonPath);           // 加载 rng_models.json
  IModel* getOrCreate(const std::string& tables1Spec,     // 解析并创建实例
                      float defaultValue);

  // 按模型名查找所有使用该模型的信号实例（valve_pair 查询动作信号用）
  std::vector<IModel*> findByModelName(const std::string& modelName);

  void registerMode(const std::string& mode, Ctor ctor);  // 注册新模型类型
};
```

### 数据流（每周期 TimeNotify）

```
TimeNotify(eventNo)
  → BinaryTele.ReBuild(eventNo)
  → for i in 0..BinaryTele.size():
      item = BinaryTele[i]
      spec = item.tables[1]
      model = ModelRegistry::getOrCreate(spec, atof(item.defaultValue))
      if item.type[0] == 'b':
        item = model->evaluateBool(timeIndex)
      else:
        item = model->evaluate(timeIndex)      (float)
  → BinaryTele.GetTeleData() → m_mapfix[eventNo]->push(buff)
```

### 启动流程

```
RNG::start()
  → con_mag_->dbLogin()
  → ModelRegistry::instance().loadModels("/users/dsc/code/TestProject/RNG/json/rng_models.json")
  → RNG_server = new RNGICEI()
  → PACE 服务注册
```

## 扩展流程

新增一个模型模式（如指数衰减 `exponential`）只需要：

1. 新建 `model/ExponentialModel.h`，实现 `IModel::evaluate(t)`
2. 在 `ModelRegistry` 构造函数中注册一行：`reg("exponential", ExponentialModel::create)`
3. 在 `rng_models.json` 中添加模板：`"exp_decay": { "mode": "exponential", "params": { "lambda": 0.01 } }`

JSON params 以通用 map 形式透传给模型构造函数，工厂不需要理解新参数。

## 存量兼容

- `RandT.h` 保留，底层随机数工具被各 Model 内部使用
- `read_csv.hpp` 保留，`CsvReplayModel` 内部使用
- `Generator.cc` 中所有硬编码的 if-else 信号映射删除
- `BinaryTele` + `CMemFix<PLC_DATA>` 共享内存写入逻辑保持不变
- ICE 接口 `RNGICEI` 不变
- DB2 中已有的 `tables[1]` 为空的行走默认模型 `normal_tiny`，保持向后兼容

## 约束

- `tables[1]` 字段长度 40 字符（`name_type` = `char[40]`），模型名 + 引用语法需控制在此范围内
- 时间索引 `t_index` 从进程启动起单调递增，每周期（~20ms）加 1，不持久化