# 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「炉层杂质预警模型训练」消费（监督/无监督均可用）。