docs: add fault frequency database design

docs/database/fault-frequency-design.md

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