决策模块重构设计方案

版本：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 万行，规模可控。
预警阈值初值需上线后校准。