feat(#70): 炉层杂质预警特征工程（声明式FeatureSpec引擎，PRD 5.3 ③）

新增 templates/ti-cl4/impurity-forecast：声明式特征工程引擎，特征以 FeatureSpec 描述（EMA/RollingStd/RateOfChange 等 7 算子），换行业只改模板配置 features.template.yaml，引擎零改动（PRD 5.3：特征工程层跨行业差异落在 FeatureSpec，不落代码）。 - features.py：FeatureSpec 声明 + 校验 + 7 算子 + 时序对齐 + 阈值 breach + 零依赖 YAML 解析 - config/features.template.yaml：炉温/氯气/炉压/炉层 9 条特征（对齐点位字典 point_id） - tests/test_features.py：24 项单测（校验/算子/对齐/breach/配置/端到端提前量）全通过 - _sanity_check.py：冒烟脚本（配置加载 + transform + breach 可观测）验收：一期阈值+无监督上线，提前量信号可观测（PRD 提前≥30min、误报率≤8%口径）。
2026-08-05 01:59:42 +08:00
parent f5d2294ee4
commit 42d206e503
7 changed files with 1148 additions and 0 deletions
@@ -0,0 +1,81 @@
+# iAOP-Template-Ti 一期 · 炉层杂质预警特征工程（Impurity Forecast）
+
+对应 PRD 5.3「③ 炉层杂质预警」与 Issue #70「[Ti-1] 炉层杂质预警特征工程」。
+
+PRD 5.3 明确：**特征工程层的跨行业差异落在 FeatureSpec，不落代码**。本模块
+实现一个**声明式特征工程引擎**——特征以 `FeatureSpec` 描述（如 `EMA(炉温, 5min)`、
+`RollingStd(氯气流量, 10)`、`RateOfChange(炉压)`），由工艺模板定义、引擎解释执行；
+**换行业只改模板配置（`config/features.template.yaml`），引擎零改动**。
+
+## 验收口径（PRD 5.3 ③ / 验收表）
+
+- 炉层杂质预警提前 ≥ 30 分钟；
+- 误报率 ≤ 8%；
+- 一期：阈值 + 无监督上线（数据门槛低）；3 个月后转监督。
+
+## 模块结构
+
+```
+templates/ti-cl4/impurity-forecast/
+├── __init__.py                 包入口（导出 FeatureEngine / FeatureSpec 等）
+├── features.py                 声明式特征工程引擎（FeatureSpec + 算子 + YAML 解析）
+├── _sanity_check.py            冒烟脚本（零环境依赖，直接运行）
+├── config/
+│   └── features.template.yaml  模板特征配置资产（炉温/氯气/炉压/炉层 9 条特征）
+└── tests/
+    ├── _bootstrap.py           测试引导（连字符目录挂载为可导入包）
+    └── test_features.py        24 项单测（校验/算子/对齐/breach/配置/端到端）
+```
+
+## 内置算子（声明式 FeatureSpec 的 `kind`）
+
+| kind | 含义 | 参数 | 示例 |
+|------|------|------|------|
+| `raw` | 原始值透传 | — | `炉温_raw` |
+| `ema` | 指数滑动平均（平滑去噪） | `alpha ∈ (0,1]` | `炉温_ema5 = ema(炉温, alpha=0.2)` |
+| `rolling_std` | 滚动标准差（波动度） | `window > 0` | `氯气流量_std10` |
+| `rolling_mean` | 滚动均值 | `window > 0` | `炉层状态_mean10` |
+| `rolling_min` / `rolling_max` | 滚动极值 | `window > 0` | 配合阈值 |
+| `rate_of_change` | 变化率 `(x[t]-x[t-w])/x[t-w]` | `window > 0` | `炉压_rate10` |
+
+## 用法
+
+```python
+from impurity_forecast import FeatureEngine, load_feature_config
+
+# 1) 从模板资产构建引擎
+engine = FeatureEngine.from_template_config("config/features.template.yaml")
+
+# 2) 时序样本流 → 按时间对齐的特征向量序列
+samples = [
+    {"ts": 1, "CLF-01.TEMP": 850.0, "CLF-01.CL2": 100.0,
+     "CLF-01.PRES": 10.0, "CLF-01.BED": 60.0},
+    # ...
+]
+vectors = engine.transform(samples)
+
+# 3) 无监督阈值判定（一期上线口径）
+for vec in vectors:
+    if vec.is_complete:
+        breach = engine.breach(vec)   # 超阈值的 (特征名, 当前值) 列表
+        if breach:
+            ...  # 触发预警（提前量信号）
+```
+
+## 运行测试 / 冒烟
+
+```bash
+cd templates/ti-cl4/impurity-forecast
+python -m unittest discover -s tests      # 24 项单测
+python _sanity_check.py                    # 冒烟：配置加载 + transform + breach
+```
+
+## 设计要点
+
+1. **零第三方依赖**：纯 Python 标准库；YAML 子集自解析（对齐 data-bus / rag-kb）。
+2. **模板化**：测点对齐 `templates/ti-cl4/point-dict/point_dict.default.csv` 的
+   `point_id`；特征声明集中在 `config/features.template.yaml`。
+3. **缺失值治理**：缺失测点用 `NaN` 占位并记录缺失率，作为误报率治理输入。
+4. **预热语义**：滚动/变化率类算子在窗口未满时输出 `NaN`（"尚不足以计算"），
+   避免冷启动误报。
+5. **配套**：本特征矩阵供 #71「炉层杂质预警模型训练」消费（监督/无监督均可用）。