# 全量与实时运行及告警落库

本文档记录压力/振动算法在 `models/` 重构后的运行方式：设备号输入、全量/实时模式、
`compressor_alarm` 存储映射与定时服务。对应代码：`models/scan_all.py`、
`models/realtime_service.py`、`models/common/devices.py`、`models/common/alarm_store.py`。

## 1. 设备号输入

- 统一使用 `--device 7# 8# 9#`（默认 `7# 8# 9#`），也兼容 `7`、`7号机`。
- 设备通过 `compressor_data_import.directory_path` 解析到 PKS 导入批次：

```sql
SELECT pls.*
FROM pks_long_sample pls
INNER JOIN compressor_data_import di ON di.id = pls.import_batch_id
WHERE di.data_type = 'PKS' AND di.directory_path = '7#';
```

- `7#/8#/9#` 分别对应 7/8/9 号机；`4#/5#/6#` 暂不纳入本算法。
- 算法内部**仍按 `批次` 划分周期**（与历史一致），因此本地全量结果与现有
  `润滑油压力小时阶段段.csv`、`振动异常段.csv` 逐字节一致。

## 2. 全量运行

```bash
# 本地：自动查询起止时间，先清理旧中间/结果再生成
python models/scan_all.py --device 7# 8# 9# --store local

# 数据库：本地结果照常生成，并额外写入 compressor_alarm
python models/scan_all.py --device 7# 8# 9# --store db

# 开启模型预测参考（3 小时滑动预测，写入概率均值/最大/最小）
python models/scan_all.py --device 7# 8# 9# --store db --with-model

# 显式时间或复用小时中间表
python models/scan_all.py --start "2025-01-01 00:00:00" --end "2026-09-01 00:00:00"
python models/scan_all.py --hourly-csv models/datas/hourly/pks_hourly_full.csv
```

- **自动时间范围**：`start = floor(最小 sample_time)`，`end = floor(最大 sample_time) + 1h`
  （保证最后一个完整整点小时纳入），按设备取范围。
- **清理策略**：运行前删除旧的小时中间表与扫描结果（`models/datas/hourly/`、
  `models/results/{common,pressure,vibration}` 中的扫描产物），不删除模型测试结果与
  `models/datas/reference/`。
- `--store db` 会按 `(device_code, alarm_type ∈ {润滑油压力故障, 振动故障})`
  **先删除所选设备的旧告警，再插入新段**。

## 3. 数据库存储映射（表 `compressor_alarm`）

| 结果 | device_code | device_part | device_point | alarm_type | alarm_level |
|---|---|---|---|---|---|
| 压力段 | `7#` | `润滑油压力` | `YSJ_5` | `润滑油压力故障` | 压力阶段 |
| 振动段 | `7#` | `联轴器端振动` / `链轮端振动` | `YSJ_10` / `YSJ_11` | `振动故障` | 振动阶段 |

- **每个压力段落 1 行**；**每个振动段也落 1 行**，`device_part/device_point` 由该段
  `最强异常侧` 决定（链轮端 → `YSJ_11`，联轴器端 → `YSJ_10`），与
  `振动异常段.csv` 一行一段对应。
- 其他字段：
  - `alarm_des` = `阶段触发依据`（已迁移为 `VARCHAR(4000)`）；
  - `alarm_time_start` / `alarm_time_end` = `开始小时` / `结束小时`；
  - `alarm_info_json` = 对应 CSV 行的 JSON（`阶段/基线/评分/触发依据/最强异常侧` 等全部字段）；
  - `status = 1`；`scan_start_time` / `scan_end_time` = 本次扫描范围。
- 结构迁移：`models/migrations/alter_compressor_alarm_alarm_des_4000.sql`
  （`ALTER TABLE compressor_alarm MODIFY alarm_des VARCHAR(4000)`）。

## 3.1 模型预测参考（`--with-model`，默认关闭）

- 定位：模型只提供**预测参考数值**，不做异常判定，不影响故障段的产生与等级。
- 方式：对每个故障段内**每个有效运行小时**取“结尾 3 个有效运行小时”窗口滑动预测一次
  （段不足 3 小时时窗口向前补有效小时）；整段无法组成窗口则记“数据不足”。
- 汇总：`模型异常概率均值`、`模型异常概率最大值`、`模型异常概率最小值`。
- 输出：
  - `alarm_info_json` 增加上述 3 个概率字段及 `模型预测参考`
    （`模型预测参考：3小时窗口异常概率 均值x/最大y/最小z（n次）`）；
  - `alarm_des` 只保留 `阶段触发依据`，不再追加模型预测参考；
  - 本地 `润滑油压力小时阶段段.csv` / `振动异常段.csv` 同步增加这 3 列 + `模型预测参考` 列。
- 训练链路（`build_datasets` / `split` / `train`）完全不受影响；预测复用同一窗口与特征函数。
- 开启时若 `models/datas/artifacts/*` 缺失会直接报错，需先运行对应 `run_pipeline.py`。
- 默认关闭，不带该参数时结果与 golden 逐字节一致；带该参数时校验按基础列子集比对。

## 4. 实时运行与合并规则

```bash
python models/realtime_service.py --once                    # 单次
python models/realtime_service.py --loop --interval 300     # 每 5 分钟（命令行定时）
python models/realtime_service.py --once --with-model       # 同时写入模型预测参考
```

- 每次 tick：`end = min(floor(本机当前时间), floor(最新数据) + 1h)`，
  `start = end - lookback`（默认 45 天），按设备跑与全量相同的算法得到段。
- **合并写入**：对每段按 `(device_code, alarm_type, alarm_level)` 找时间重叠、或间隔
  ≤6 小时的既有行：
  - `alarm_time_start = min`、`alarm_time_end = max`，刷新 `alarm_des` / `alarm_info_json`
    / `scan_*`；
  - 合并键**不含部件/点位**，因此“最强异常侧”在 tick 之间切换也不会把连续段拆开；
    合并时 `device_part/device_point` 更新为最新 `最强异常侧`；
  - 同一时刻若新段桥接了两条既有行，会合并为一条（删除多余行）；
  - 不同等级（轻微/异常/严重异常）保留为不同行，与阶段 CSV 的行语义一致。
- 因此“14 点和 15 点属于同一故障段”的场景会持续更新同一行，不会拆开。

## 5. 定时服务

| 平台 | 安装 | 卸载 |
|---|---|---|
| macOS | `bash models/service/mac/install.sh` | `bash models/service/mac/uninstall.sh` |
| Linux | `sudo bash models/service/linux/install.sh` | `sudo bash models/service/linux/uninstall.sh` |
| Windows | `models\service\windows\install_service.bat` | `models\service\windows\uninstall_service.bat` |

均为每 5 分钟执行 `python models/realtime_service.py --once`；详见
`models/service/README.md`（含 cron 备选与日志位置）。

## 6. 冒烟测试与校验

```bash
# 顺序模拟多个时刻运行，结束后默认回滚数据库
python models/realtime_service.py --simulate "2026-02-03 20:00:00,2026-02-04 00:00:00"

# 校验本地结果与 golden 一致、DB 行数与 CSV 对应
python models/common/verify.py --with-db
```

`--with-db` 会校验 `compressor_alarm` 行数与参考 CSV 对应：压力 72 行、振动 25 行，共 97 行。