# 配置化驾驶舱内核模块（iAOP-Core / cockpit）

对齐 PRD 5.5「⑤ 配置化驾驶舱」：把驾驶舱抽象为模板化配置资产，按"布局/配置"渲染，
切换行业模板零改前端代码（PRD 5.5 验收口径）。

## 模块状态

| 能力 | Issue | 状态 |
| --- | --- | --- |
| 布局 JSON Schema 定义 + 校验/解析 | #50 | feature/issue-50（推进中） |
| 图表组件配置化渲染引擎（RenderPlan） | #51 | feature/issue-51（推进中） |
| **报警看板配置化（阈值/规则外置）** | **#52** | **本分支 feature/issue-52** |

#52「报警看板配置化」把告警面板（`alarm_panel`）的展示语义外置为模板配置资产，
让"换行业只换配置、前端代码零改动"也覆盖到告警面板。配置点：

- **严重度→颜色映射**（`severityColors`）：P0/P1/P2 三级各自的 `fg`/`bg`/可选 `icon`/`border`，
  覆盖主题默认告警色；驾驶舱红色告警（PRD 5.3 ③ 场景A）即由 `P0` 的 `fg` 决定。
- **告警规则 / 阈值源绑定**（`rulesSource` / `thresholdsSource`）：告警面板订阅哪份
  规则资产（`kind: asset` + `ref`）或内联规则（`kind: inline` + `data`）——把"看哪条规则"
  也变成配置项，避免把规则 id 写死在前端。
- **SOP 联动**（`showSop`）：PRD 场景A「LLM 生成原因+处置建议 → 值班长确认」是否在面板展开。
- **确认 / 静默行为**（`requireAck` / `ackTimeoutS` / `muteLower`）：关键告警是否强制人工确认、
  超时升级、是否静默低于某 severity 的提示。
- **分组 / 排序 / 最大条数**（`groupBy` / `sortBy` / `maxItems`）：大屏展示策略外置。

## 用法

```python
from cockpit import (
    validate_alarm_config, load_alarm_config, render_alarm_panel_props,
)

# 1) 配置资产（通常来自模板 YAML；这里用 dict 示意）
config = {
    "$schema": "iAOP-cockpit-alarm-panel-v1",
    "severityColors": [
        {"severity": "P0", "fg": "#ff3b30", "bg": "rgba(255,59,48,0.12)", "icon": "alert-octagon"},
        {"severity": "P1", "fg": "#f5a623", "bg": "rgba(245,166,35,0.12)"},
        {"severity": "P2", "fg": "#3aa0ff", "bg": "rgba(58,160,255,0.10)"},
    ],
    "rulesSource": {"kind": "asset", "ref": "ti-cl4/impurity-forecast/config/alert_rules.template.yaml"},
    "showSop": True, "requireAck": True, "ackTimeoutS": 300, "muteLower": "P2",
    "groupBy": "severity", "sortBy": "severity", "maxItems": 50,
}

# 2) 校验（聚合全部字段级错误，便于配置台「错误列表」展示）
result = validate_alarm_config(config)
assert result.ok, result.errors

# 3) 加载为内存模型
cfg = load_alarm_config(config)

# 4) 编译为 alarm_panel 组件的 props（#51 渲染层在 _build_props 里合并即可）
props = render_alarm_panel_props(cfg)
#   -> {'subscribe': 'alarm_stream', 'severityStyles': {...}, 'rulesSource': {...},
#       'showSop': True, 'requireAck': True, 'ackTimeoutS': 300, ...}
```

切换行业模板（如树脂）= 换一份配置资产（不同配色 / 规则源），`render_alarm_panel_props`
随配置变化产出不同 props，**前端代码零改动**。

## 设计要点

- **零运行时依赖**：只用标准库，配置资产是可 `json.dumps` 的纯 dict，便于配置台发布与审计。
- **声明式 + 强校验**：`validate_alarm_config` 收集全部字段级错误（沿用 #50
  `LayoutValidationResult` 风格）；`load_alarm_config` 校验失败抛 `AlarmConfigError`
  并携带错误清单。
- **与 #50/#51 解耦**：本模块不 import `layout` / `renderer`（它们在各自 feature 分支上推进），
  避免对未合并分支形成硬依赖；`render_alarm_panel_props` 仅产出 `alarm_panel` 组件的 props dict，
  由 #51 渲染层在 `_build_props` 里合并即可。#50/#51 合入 main 后，本模块的 `__init__`
  会合并它们的导出（`CockpitLayout` / `validate_layout` / `RenderPlan` 等）。

## 测试 / 验收

```bash
# 在 core/cockpit 目录下
python -m unittest discover -s tests -p "test_alarm_config.py" -v   # 28 用例
python scripts/verify_alarm_config.py                                # 验收脚本
```

参考资产：`templates/ti-cl4/dashboard/alarm_panel.ti.yaml`（氯化车间/海绵钛告警面板配置）。