# 决策模块重构设计方案

> 版本：v1.0 ｜ 日期：2026-09-09 ｜ 模块：yudao-module-bi 决策支持（decision）
> 对齐目标：数据看板与多维度报表、实时 KPI 监控与异常预警、历史数据驱动的负荷预测与决策研判

---

## 一、背景与目标

现有 `yudao-module-bi` 决策支持子模块已具备代码骨架（KPI / 预警 / 预测 / 看板四个域），但**配置数据全部为空**（`bi_kpi_definition`、`bi_dashboard`、`bi_chart_config`、`bi_alert_rule`、`bi_forecast_data` 均为 0 条），尚未与系统业务数据打通。

本次重构围绕三大业务目标：

| # | 目标 | 落地形态 |
|---|------|----------|
| 1 | 整合用电营销、生产运维、物资采购、库存、能耗等核心数据 | 配置式可视化看板（大屏）+ 多维度报表 |
| 2 | 实时监控供电量、设备运行、生产效率、质量、成本、安全等核心 KPI，异常自动预警 | KPI 指标库 + 快照聚合 + 预警规则中心 |
| 3 | 基于历史数据开展负荷预测、需求分析、趋势研判 | Java 统计预测引擎，支撑电网调度、运维计划、采购策略、客户经营决策 |

---

## 二、现状分析与数据摸底

### 2.1 现有决策模块骨架（代码已就绪）

| 域 | 表 | 服务 | 控制器 | 备注 |
|----|----|------|--------|------|
| KPI 指标定义 | `bi_kpi_definition` | BiKpiDefinitionService | DecisionKpiDefinitionController | SQL 配置式，`query_sql` 实时执行 |
| KPI 聚合展示 | — | BiDecisionKpiService | DecisionKpiController | overview/detail/category/refresh |
| 预警规则 | `bi_alert_rule` | BiAlertRuleService | DecisionAlertRuleController | 阈值 + 比较符 + 通知方式 |
| 预警记录 | `bi_alert_record` | BiAlertRecordService | DecisionAlertController | 分页/未处理数/确认/处理 |
| 负荷预测 | `bi_forecast_data` | BiForecastService | DecisionForecastController | 现为 SMA 简单移动平均占位，支持联动生成工单 |
| 仪表盘 | `bi_dashboard` | DashboardService | DashboardController | 按 `{code}/data` 返回图表数据 |
| 图表配置 | `bi_chart_config` | BiChartConfigService | BiChartConfigController | SQL + chartType + position + chartOptions |
| 数据源配置 | `bi_data_source_config` | BiDataSourceConfigService | BiDataSourceConfigController | 多数据源预留 |

### 2.2 预警定时任务（已存在）

`AlertEvaluationTask` 每 5 分钟（可配 `bi.alert.evaluation.interval`）扫描启用预警规则 → 执行 KPI SQL → 与阈值比较 → 生成预警记录，并对同一 KPI 未处理预警去重。

### 2.3 业务数据摸底（mom-xgdl 库 2026-09-09）

| 数据域 | 表 | 现状 | 说明 |
|--------|----|------|------|
| 设备 | `mes_dv_machinery` | 1 台（生产机，status=1，效率100） | status：0-停 / 1-运行 |
| 遥测 | `mes_dv_telemetry` | 296 条（4 台设备） | 工艺参数（温度/匝数等），含 `whether_anomaly` 异常标志、`telemetry_data_time`、`shift_name` |
| 生产 | `mes_pro_work_order / task / feedback` | 0 | 工单/任务/报工 |
| 质量 | `mes_qc_iqc/ipqc/oqc/ncr` | 0 | 来料/过程/出货/不合格品 |
| 库存 | `mes_wm_material_stock/transaction` | 1+1 | 库存余额 + 流水 |
| 安灯 | `mes_pro_andon_record` | 0 | 现场异常呼叫（安全监控入口） |
| 采购 | `erp_purchase_request/order` | 0 | 采购申请/订单 |
| 销售 | `erp_sale_order` | 0 | 销售订单 |
| 财务 | `erp_finance_receipt/payment` | 0 | 收款/付款 |
| 客户 | `crm_customer/contract/receivable` | 0 | 客户/合同/回款 |

> **结论**：当前处于开发/试运行初期，业务数据未铺开。KPI 指标、预警规则、看板图表一律按**真实表结构 + 真实字段**配置，数据积累后自动出值；设备运行与遥测异常指标当前即有真实数据支撑。

### 2.4 关键数据缺口

| 缺口 | 现状 | 本次策略 |
|------|------|----------|
| 能耗/供电量数据 | 无独立用电量记录表；`mes_dv_telemetry` 为工艺参数遥测，无功率/电量参数 | **从遥测参数聚合**：按 `param_name` 匹配 功率/电量/电流 类参数聚合；无匹配参数时 KPI 返回 0 占位并保留接口 |
| 安全数据 | 无事故/隐患台账，仅 `mes_pro_andon_record` 安灯记录 | 安全 KPI 基于安灯记录（数量/未处置数），隐患台账留待后续 |
| KPI 历史 | 无历史值存储，无法做趋势/同比环比/预测 | **新增 `bi_kpi_value_history` 快照表 + 定时聚合任务** |

---

## 三、总体架构设计

```
┌────────────────────────────────────────────────────────────────┐
│                        管理层（大屏/报表）                       │
│  bi_dashboard {code}/data  →  配置式大屏（采购销售/仓库/生产设备  │
│  /质量/能耗/营销 + 决策总览）                                    │
│  多维度报表：按 时间 / 车间 / 设备类型 / 物料分类 / 客户 / 供应商   │
│  交叉分析（新增 /bi/decision/report 汇总接口）                    │
├────────────────────────────────────────────────────────────────┤
│                       监控层（KPI + 预警）                       │
│  bi_kpi_definition（SQL 指标库）                                 │
│    ├── 实时层：BiDecisionKpiService 按需实时执行 SQL              │
│    ├── 快照层：（新增）KpiSnapshotTask 定时写入 bi_kpi_value_history│
│    └── 预警层：AlertEvaluationTask 评估 bi_alert_rule → bi_alert_record│
├────────────────────────────────────────────────────────────────┤
│                       决策层（预测/研判）                         │
│  BiForecastEngine（统计预测引擎：SMA/WMA/线性回归/同比环比/季节指数）│
│    ├── 基于 bi_kpi_value_history 的 KPI 趋势预测（负荷/产量/采购/回款）│
│    └── 联动：预测结果 → 生成生产工单（复用 generate-work-order）   │
└────────────────────────────────────────────────────────────────┘
```

### 3.1 分层职责

| 层 | 输入 | 处理 | 输出 |
|----|------|------|------|
| 数据接入 | 各业务表（mes/erp/crm/srm）+ 遥测 | 跨模块 SQL（单库 JdbcTemplate） | KPI 当前值 |
| 监控 | KPI 指标库 | 实时查询 + 定时快照 + 阈值评估 | overview / 快照历史 / 预警记录 |
| 决策 | 快照历史 | 统计预测引擎 | 预测序列 + 置信区间 + 工单联动 |
| 展示 | 看板/图表配置 | 配置驱动组装 | 大屏 / 报表 |

### 3.2 实时性设计

| 层级 | 机制 | 周期 |
|------|------|------|
| KPI 实时查询 | 前端按 `refreshInterval` 调 `overview/{kpiCode}` | 按需 |
| KPI 快照 | 新增 `KpiSnapshotTask` 聚合至 `bi_kpi_value_history` | 默认 1 小时（可配 `bi.kpi.snapshot.interval`） |
| 预警评估 | 现有 `AlertEvaluationTask` | 默认 5 分钟（可配 `bi.alert.evaluation.interval`） |
| 遥测异常 | 直接聚合 `mes_dv_telemetry.whether_anomaly` | 随快照 |

---

## 四、KPI 指标体系设计

统一编码规则：`{域简称}_{指标英文}`，共 7 类（category 扩展原注释枚举）。

### 4.1 域划分与指标清单

#### A. 供电电量 / 能耗域（category = `energy`）

| code | 名称 | 单位 | 数据来源 SQL 逻辑 |
|------|------|------|--------------------|
| energy_telemetry_devices | 遥测在采设备数 | 台 | `COUNT(DISTINCT tb_device_id)` from mes_dv_telemetry（近24h） |
| energy_telemetry_points | 在采测点总数 | 个 | `COUNT(*)` from mes_dv_telemetry（近24h） |
| energy_anomaly_rate | 遥测异常率 | % | `SUM(whether_anomaly)/COUNT(*)` 近24h |
| energy_power_load | 实时功率负荷 | kW | `SUM(timely_value)` where param_name like '%功率%'（无参数返回0占位） |
| energy_power_consumption | 周期用电量 | kWh | 聚合电度类参数差值（预留模型，本期占位） |

#### B. 设备运行域（category = `device_operation`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| device_total | 设备总数 | 台 | `COUNT(*)` from mes_dv_machinery |
| device_running | 运行设备数 | 台 | `COUNT(*) where status=1` |
| device_operation_rate | 开机率 | % | 运行 / 总数 |
| device_avg_efficiency | 平均生产效率 | 件/时 | `AVG(production_efficiency)` |
| device_need_repair | 待维修工单 | 个 | `COUNT(*) where status<终态` from mes_dv_repair |
| device_overdue_mainten | 到期未保养设备 | 台 | `last_mainten_time < 计划周期`（预留，返回0） |

#### C. 生产效率域（category = `production`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| prod_work_order_total | 工单总数 | 单 | `COUNT(*)` from mes_pro_work_order（近30天） |
| prod_work_order_finish | 完工工单数 | 单 | `status=已完工` |
| prod_plan_achieve_rate | 工单计划达成率 | % | 完工量之和 / 计划量之和 |
| prod_feedback_qualified | 报工合格率 | % | SUM(qualified)/SUM(feedback) from mes_pro_feedback |
| prod_daily_output | 日产量 | 件 | SUM(feedback_quantity) 当日 |
| prod_task_duration | 工单平均工期 | 天 | AVG(duration) from mes_pro_task |

#### D. 质量域（category = `quality`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| quality_iqc_pass_rate | 来料检验合格率 | % | SUM(qualified)/SUM(check) from mes_qc_iqc |
| quality_ipqc_pass_rate | 过程检验合格率 | % | from mes_qc_ipqc |
| quality_oqc_pass_rate | 出货检验合格率 | % | from mes_qc_oqc |
| quality_ncr_count | 不合格品报告数 | 单 | `COUNT(*)` from mes_qc_ncr |

#### E. 物资采购 / 成本域（category = `procurement`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| pur_request_amount | 采购申请金额（近30天） | 元 | `SUM(total_price)` from erp_purchase_request |
| pur_order_amount | 采购订单金额（近30天） | 元 | `SUM(total_price)` from erp_purchase_order |
| pur_order_pending_in | 待入库采购量 | 件 | `SUM(total_count-in_count)` from erp_purchase_order |
| stock_amount_value | 库存货值 | 元 | `SUM(stock.quantity*item.cost_price)` from mes_wm_material_stock join mdm_item |
| stock_low_alert | 库存低于安全库存物料数 | 个 | `quantity < item.safety_stock` |
| cost_payment_amount | 应付款（近30天） | 元 | `SUM(payment_price)` from erp_finance_payment |

#### F. 用电营销 / 客户经营域（category = `sales`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| sale_order_amount | 销售订单金额（近30天） | 元 | `SUM(total_price)` from erp_sale_order |
| crm_contract_amount | 合同签订金额 | 元 | `SUM(total_price)` from crm_contract（审核通过） |
| crm_receivable_amount | 实际回款金额 | 元 | `SUM(price)` from crm_receivable |
| crm_customer_count | 客户总数 | 个 | `COUNT(*)` from crm_customer |
| crm_receivable_overdue | 逾期未回款金额 | 元 | 佣金计划 `receivable_plan` 超 return_time 未回 |
| srm_avg_score | 供应商平均综合评分 | 分 | `AVG(composite_score)` from srm_supplier_evaluation |

#### G. 安全域（category = `safety`）

| code | 名称 | 单位 | SQL 逻辑 |
|------|------|------|----------|
| safety_andon_count | 安灯报警数（近30天） | 次 | `COUNT(*)` from mes_pro_andon_record |
| safety_andon_unhandled | 未处置安灯数 | 个 | `COUNT(*) where status=未处置` |

### 4.2 维度设计

| 维度 | 来源 | 用途 |
|------|------|------|
| 时间 | 日 / 周 / 月 / 年 | 全部指标趋势 |
| 车间 | `mes_dv_machinery.workshop_id`、`mes_pro_work_order` | 设备/生产 |
| 设备类型 | `mes_dv_machinery_type` | 设备/能耗 |
| 物料分类 | `mdm_item` 分类 | 采购/库存 |
| 客户 | `crm_customer` | 营销/回款 |
| 供应商 | `srm_supplier` / `erp_supplier` | 采购/成本 |

---

## 五、KPI 历史快照与聚合（本次新增）

### 5.1 新增表 `bi_kpi_value_history`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| kpi_id | bigint | 关联 bi_kpi_definition.id |
| kpi_code | varchar(64) | KPI 编码（冗余） |
| kpi_name | varchar(128) | KPI 名称（冗余） |
| category | varchar(32) | 分类 |
| kpi_value | decimal(18,4) | 快照值 |
| snapshot_time | datetime | 快照时间点（整点） |
| period_type | varchar(16) | 统计周期：hour/day/week/month |
| dimension_value | varchar(64) | 业务维度值（预留，默认 all） |
| remark | varchar(255) | 备注 |
| 审计字段 | — | creator/create_time/updater/update_time/deleted |

索引：`idx_kpi_time(kpi_code, snapshot_time)`，`idx_category_time(category, snapshot_time)`。

### 5.2 新增聚合任务 `KpiSnapshotTask`

- 定时（默认每小时 `0 0 * * * *`，可配 `bi.kpi.snapshot.cron`）扫描 `status=1` 的 KPI 定义
- 执行每条 `query_sql` 取当前值，写入 `bi_kpi_value_history`
- 同名 KPI 同一整点去重（覆盖式更新或跳过去重，取最新）
- 失败 SQL 记日志降级，不中断整体

### 5.3 新增查询接口（趋势研判）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/bi/decision/kpi/trend/{kpiCode}?beginTime=&endTime=&periodType=` | KPI 历史快照趋势（供报表/大屏折线） |
| GET | `/bi/decision/kpi/compare/{kpiCode}` | 同比环比（较上月/去年同期），基于快照 | 

---

## 六、预警规则体系

### 6.1 规则配置（本次落库示例）

| KPI | 规则 | 级别 | 阈值 | 比较符 |
|-----|------|------|------|--------|
| energy_anomaly_rate | 遥测异常率过高 | 警告 | 5 (%) | >= |
| device_operation_rate | 开机率过低 | 严重 | 60 (%) | < |
| device_avg_efficiency | 设备效率过低 | 警告 | 80 (件/时) | < |
| quality_oqc_pass_rate | 出货检验合格率过低 | 严重 | 95 (%) | < |
| stock_low_alert | 库存低于安全库存物料数超限 | 严重 | 10 (个) | > |
| safety_andon_unhandled | 未处置安灯持续累积 | 紧急 | 1 (个) | > |
| crm_receivable_overdue | 逾期回款金额过大 | 严重 | 500000 (元) | > |

> 阈值仅为初始建议值，上线后按实际水平调整。`notificationType` 统一配置为 `system`（站内信/待办集成，后续扩展 message/email）。

### 6.2 预警生命周期

```
规则启用 → 定时评估（5min）→ 命中阈值 → 生成 bi_alert_record(status=0)
→ 前端"预警中心"展示 + 未处理计数 → 确认(confirm) / 处理(handle) → 关闭
```

去重策略：同一 KPI 存在未处理预警时不再重复生成（现有逻辑）。

---

## 七、能耗/供电量聚合方案（从遥测参数聚合）

### 7.1 处理原则

- 以 `mes_dv_telemetry` 为唯一实时能耗来源，按 `param_name` 特征匹配能力参数：
  - 功率类：`param_name LIKE '%功率%'` → `energy_power_load`（实时功率，kW）
  - 电量类：`param_name LIKE '%电量%' OR '%用电%' OR '%电度%'` → 电量采集（预留）
  - 电流/电压类：`%电流%`、`%电压%` → 电能质量辅助指标
- 当前测点无能力参数时，相关 KPI 返回 0 / 无数据占位，**不伪造数据**，待测点补充后自动出值。

### 7.2 能耗聚合模型（本次落地）

| 指标 | 聚合口径 |
|------|----------|
| 实时功率负荷 | 当前批次 `timely_value` 求和，按设备 |
| 班次能耗估算 | 按 `shift_name` 分组 `AVG(timely_value)` × 运行时长（预留） |
| 日用电量 | 电度类参数 `max_value-min_value` 跨日回差（预留模型，表结构就绪） |

---

## 八、Java 统计预测引擎设计

### 8.1 模型库（本次落地）

| 模型 | 算法 | 适用场景 | 实现 |
|------|------|----------|------|
| SMA | 简单移动平均（窗口 12） | 平稳序列 | 现有逻辑保留 |
| WMA | 加权移动平均（近期权重递增） | 有轻微趋势 | 新增 |
| LR | 一元线性回归（最小二乘） | 线性趋势（产量/采购/回款） | 新增 |
| SEASONAL | 季节指数（按周期归一化） | 周期性负荷 | 新增 |
| YOY/QOQ | 同比/环比外推 | 营销类快速预估 | 新增 |

### 8.2 引擎结构

```
BiForecastEngine（新增，纯 Java 工具类）
  ├─ sma(List<BigDecimal>, window)
  ├─ wma(List<BigDecimal>, window)
  ├─ linearRegression(List<BigDecimal>) → slope/intercept/预测下N期
  ├─ seasonalIndex(List<BigDecimal>, period) → 季节因子 + 去季节预测
  └─ forecastByModel(code, modelType, data, periods) → 统一出口
```

### 8.3 接口扩展（BiForecastService + Controller）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/bi/decision/kpi/trend/{kpiCode}?beginTime=&endTime=&periodType=` | KPI 历史快照趋势取数（喂给引擎） |
| POST | `/bi/decision/forecast/generate` 扩展参数 `model=SMA\|WMA\|LR\|SEASONAL` + `periods=` | 按模型生成预测，落 `bi_forecast_data` |
| POST | `/bi/decision/forecast/generate-from-kpi?kpiCode=&model=&periods=` | 从 KPI 快照历史生成预测（负荷/产量/采购/回款） |
| POST | `/bi/decision/forecast/generate-work-order` | 预测联动创建生产工单（现有，延续） |

预测结果字段沿用 `bi_forecast_data`：forecast_value / lowerBound / upperBound / confidenceLevel(95%) / modelVersion（如 `v2.0-lr`）。

### 8.4 决策支撑场景映射

| 决策场景 | 预测对象 | 数据源 | 输出 |
|----------|----------|--------|------|
| 电网调度/产能排程 | 日产量、工单负荷 | prod_daily_output 快照 | 未来 7/30 天产量预测 |
| 运维计划 | 设备效率、异常率 | device_avg_efficiency、energy_anomaly_rate | 异常趋势预警 |
| 采购策略 | 采购金额、库存周转 | pur_order_amount、stock_low_alert | 下月采购量预测 |
| 客户经营 | 回款、合同 | crm_receivable_amount | 下月回款预测 |

---

## 九、看板与多维度报表方案

### 9.1 看板布局（bi_dashboard + bi_chart_config 落库）

| code | 名称 | 覆盖图表（chart_config） |
|------|------|--------------------------|
| decision_overview | 决策总览大屏 | 核心 KPI 卡片（number）+ 各域趋势折线 |
| purchase_sales | 采购销售大屏 | 采购金额趋势/销售订单趋势/来票额/回款（沿用既有 code） |
| warehouse | 仓库大屏 | 库存货值/低库存/出入库流水/库位分布 |
| production_equipment | 生产设备大屏 | 设备开机率/效率/工单达成率/产量趋势/遥测异常 |
| quality | 质量大屏 | 各检验合格率/NCR 数量 |
| energy | 能耗监控大屏（新增） | 实时功率负荷/在采测点/异常率/班次能耗 |
| sales_customer | 营销客户大屏（新增） | 合同签定/回款/逾期/客户数/供应商评分 |

### 9.2 多维度报表（新增 `/bi/decision/report`）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/bi/decision/report/cross` | 交叉表：时间 × 车间/客户/供应商/物料分类 × 指标值 |
| GET | `/bi/decision/report/topn?category=&dimension=&limit=` | TOP N 排行（客户回款 TOP、不良 TOP、缺料 TOP） |

响应统一为 `{ columns, rows }` 结构，前端渲染普通表格/透视图。

---

## 十、数据库变更清单

| 操作 | 对象 | 说明 |
|------|------|------|
| 新建表 | `bi_kpi_value_history` | KPI 历史快照 |
| 初始化数据 | `bi_kpi_definition` | 约 26 条 KPI（上表全部 code） |
| 初始化数据 | `bi_alert_rule` | 约 7 条预警规则 |
| 初始化数据 | `bi_dashboard` | 7 个看板 |
| 初始化数据 | `bi_chart_config` | 各看板图表（约 30 张） |
| 不改表 | `bi_forecast_data` | 现有结构够用，仅扩展 modelVersion 使用 |

> 业务表零改动：KPI 体系只读各业务表，不加任何冗余字段。符合《文件上传规则》《SQL 脚本规范》（无 tenant_id）等既有约束。

---

## 十一、实施步骤

| 步骤 | 内容 | 交付 |
|------|------|------|
| 1 | 新增 `bi_kpi_value_history` 表 + DO + Mapper | 表结构、代码 |
| 2 | 新增 `KpiSnapshotTask` 快照聚合任务 | 定时任务 |
| 3 | `BiDecisionKpiService` 增加 trend / compare 接口 | Controller + Service |
| 4 | BiForecastEngine 统计预测引擎 + BiForecastService 扩展 | 预测能力 |
| 5 | KPI 指标库 / 预警规则 / 看板图表 SQL 脚本落库 | 初始化脚本 |
| 6 | 编译检查（mvn compile）+ 数据库回读验证 | 验证报告 |

## 十二、风险与注意事项

- 业务表当前为空，KPI 出值依赖数据积累；本次保证"结构正确 + SQL 可执行"，数据到位自动出值。
- 遥测无功率/电量参数时，能耗 KPI 返回 0 占位，测点补充后自动生效，**不伪造数据**。
- KPI `query_sql` 为管理员可配置项，属系统边界内可信配置；运行时经 JdbcTemplate 参数化执行，无注入风险。
- 快照量估算：26 KPI × 每小时 = 约 624 行/天，年数据量 ~23 万行，规模可控。
- 预警阈值初值需上线后校准。