# 部件故障频率数据库设计说明

版本：v1.0（2026-11-05）  
目标库：`energy_prod`  
关联服务：`Analysis_Multi`、`energy-manage-platform`

## 1. 设计目标

在不改动现有台账主表结构的前提下，为“主轴承、齿轮箱、发电机”振动分析提供故障频率参数和测点映射：

- 按品牌/型号解析轴承几何参数；
- 按机型关联具体部件的品牌、型号、安装位置和齿轮齿数；
- 输出 BPFO/BPFI/BSF/FTF、GMF；
- 参数不足时明确返回缺失项，不生成猜测值；
- 为振动报警和故障诊断预留故障类型、特征频率、证据字段。

## 2. 数据关系

```text
wind_engine_group (engine_code -> mill_type_code)
        │
        ▼
wind_engine_mill (mill_type_code)
        ├── unit_bearings (主轴承前后轴承)
        ├── unit_gearbox (gearbox_code)
        │     ├── unit_gearbox_structure (行星级/齿圈齿数/轴承)
        │     └── unit_gearbox_bearings (平行级轴承)
        └── unit_dynamo (发电机驱动/非驱动端轴承)

unit_dict_brand_model (品牌+型号 -> 轴承几何参数)
        │
        ▼
component_fault_spec (故障参数库，优先查询)

measurement_point_component (测点 -> 部件/位置/级数)
        │
        ▼
FaultFrequencyService -> 振动分析 / 诊断 / 报警
```

## 3. 新增表

### 3.1 `component_fault_spec`

按“部件类型 + 品牌 + 型号 + 位置 + 级数”保存故障频率所需最小参数。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | BIGINT | 主键 |
| `component_type` | VARCHAR(32) | bearing/main_bearing/generator/gearbox_bearing/gearbox_gear |
| `brand` | VARCHAR(128) | 品牌 |
| `model` | VARCHAR(128) | 型号 |
| `position` | VARCHAR(32) | front/rear/drive_end/non_drive_end/planet/high_speed 等 |
| `stage` | INT | 齿轮箱级数，0 表示不区分 |
| `n_rolls` | DECIMAL | 滚动体数量 |
| `roller_diameter` | DECIMAL | 滚动体直径 mm |
| `pitch_diameter` | DECIMAL | 节圆直径 mm |
| `contact_angle` | DECIMAL | 接触角 度 |
| `gear_teeth` | INT | 齿轮齿数 |
| `stage_count` | INT | 齿轮箱级数 |
| `pole_pairs` | INT | 发电机极对数 |
| `source` | VARCHAR(128) | 参数来源 |
| `confidence` | DECIMAL(5,2) | 置信度 |
| `valid_state` | VARCHAR(16) | valid/missing/review |

唯一键：

```text
(component_type, brand, model, position, stage)
```

### 3.2 `measurement_point_component`

| 字段 | 说明 |
|---|---|
| `point_name` | 波形 `mesure_point_name` |
| `component_type` | 部件类型 |
| `position` | 安装位置 |
| `stage` | 级数 |
| `note` | 说明 |

唯一键：`point_name`。没有映射时，服务退化为按测点名称关键字识别，并在结果中保留告警。

## 4. 报警表扩展

`vibration_alarm_event` 增加：

| 字段 | 用途 |
|---|---|
| `fault_type` | BPFO/BPFI/BSF/FTF/GMF |
| `characteristic_freq` | 特征频率 Hz |
| `fault_order` | 阶次 |
| `spec_source` | 参数来源 |
| `diagnosis_detail` | 峰值/谐波/边带证据 |

这些字段允许为空，兼容现有整体 RMS 报警。

## 5. 频率计算

```text
fr   = shaft_rpm / 60
BPFI = n/2 × (1 + d/D × cosα) × fr
BPFO = n/2 × (1 - d/D × cosα) × fr
BSF  = D/(2d) × [1 - (d/D × cosα)²] × fr
FTF  = 1/2 × (1 - d/D × cosα) × fr
GMF  = 齿数 × fr
```

主轴承/齿轮箱低速测点使用 `wind_engine_mill.rotational_speed_ratio` 折算；缺少传动比时使用输入转速并在 `warnings` 标注。

## 6. 兼容性与迁移

- 只新增表/字段，不修改既有字段类型；
- 迁移脚本：`docs/database/20261105_fault_frequency.sql`；
- 已有 `unit_dict_brand_model` 中 10 条几何参数会回填到 `component_fault_spec`；
- 已有 3 个机型部件配置可立即使用；
- 未覆盖型号返回 `supported=false`，不影响现有 RMS 报警。

## 7. 回滚

```sql
DROP TABLE IF EXISTS component_fault_spec;
DROP TABLE IF EXISTS measurement_point_component;
ALTER TABLE vibration_alarm_event
  DROP COLUMN fault_type,
  DROP COLUMN characteristic_freq,
  DROP COLUMN fault_order,
  DROP COLUMN spec_source,
  DROP COLUMN diagnosis_detail;
```

回滚前先确认没有业务页面依赖新增字段。

## 8. 诊断结果追溯表

新增 `vibration_diagnosis_result`，保存每次诊断的输入上下文、参数来源、特征频率和未支持原因：

```text
engine_code、wind_code、point_name、diagnosis_type、max_status
component_type、brand、model、frequencies_json、unsupported_json、meta_json、create_time
```

目的：

- 诊断结果可追溯；
- 采样率不足等“未定义”结果可审计；
- 后续可做诊断历史、复核和模型效果评估。

迁移脚本：`docs/database/20261105_diagnosis_result.sql`。

## 9. 已知限制


1. 当前仅 10 条轴承几何参数，79 个机型中仅 3 个有部件记录；
2. 齿轮箱级间转速暂按低速轴近似，精确计算需各级齿数/传动比；
3. 低采样频率（<12800 Hz）波形不能用于轴承高频故障诊断；
4. 发电机极对数、冷却方式尚未纳入自动解析；
5. 传感器量纲/标定不一致时，整体 RMS 绝对阈值需另行标定。