# 决策模块重构 - 前端联调方案

> 版本：v1.0 ｜ 日期：2026-09-09 ｜ 后端模块：yudao-module-bi（决策支持）
> 详细设计见 [decision_module_redesign.md](./decision_module_redesign.md)

## 涉及页面

- 决策总览大屏（`/bi/decision-overview`）
- 采购销售大屏（`/bi/purchase-sales`）
- 仓库大屏（`/bi/warehouse`）
- 生产设备大屏（`/bi/production-equipment`）
- 质量大屏（`/bi/quality`）
- 能耗监控大屏（`/bi/energy`，新增）
- 营销客户大屏（`/bi/sales-customer`，新增）
- 决策 BI 大屏 / 图表配置管理页 / 数据源配置管理页（既有）

## API 变更说明

本次为新增接口，不改动既有接口签名。

### 1. KPI 历史快照趋势（趋势研判）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/bi/decision/kpi/trend/{kpiCode}` | 指定 KPI 的历史快照序列（折线图数据源） |

**请求参数（Query）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| kpiCode | String | 是 | KPI 编码（见下方 KPI 清单） |
| beginTime | String | 否 | 开始时间 `yyyy-MM-dd HH:mm:ss`，默认近 30 天 |
| endTime | String | 否 | 结束时间，默认当前 |
| periodType | String | 否 | 统计周期 hour/day/week/month，默认 hour |

**响应字段：**

```json
{
  "code": 0,
  "data": {
    "kpiCode": "device_operation_rate",
    "kpiName": "开机率",
    "category": "device_operation",
    "unit": "%",
    "periodType": "hour",
    "points": [
      {"time": "2026-09-09T02:00:00", "value": 100.0000},
      {"time": "2026-09-09T03:00:00", "value": 100.0000}
    ]
  }
}
```

> 快照由定时任务每小时聚合写入，KPI 定义后需等待下一整点聚合出数；无快照时 `points` 为空数组。

### 2. KPI 环比研判

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/bi/decision/kpi/compare/{kpiCode}` | 当前快照值较上一周期的变化率及近 24 期统计 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| currentValue / currentTime | Decimal / String | 最近一期快照值与时间 |
| previousValue / previousTime | Decimal / String | 上一期快照值 |
| changeRate | Decimal | 环比变化率（%），上期不存在或为 0 时为 null |
| avgValue / maxValue / minValue | Decimal | 近 24 期均值/最大/最小 |
| periodCount | int | 实际快照条数 |

### 3. 预测生成（扩展模型参数）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/bi/decision/forecast/generate` | 生成预测，新增 `model` 参数 |

**新增 Query 参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| forecastCode | String | 是 | 预测编码（沿用） |
| model | String | 否 | 模型：SMA/WMA/LR/SEASONAL/YOY，缺省 SMA |
| window | int | 否 | 移动平均窗口，默认 12 |
| period | int | 否 | 季节周期，默认 7 |

### 4. 基于 KPI 历史生成预测

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/bi/decision/forecast/generate-from-kpi` | 用 KPI 快照历史按模型滚动预测未来 N 期 |

**请求参数（Query）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| kpiCode | String | 是 | 用哪个 KPI 的历史快照预测 |
| model | String | 否 | SMA/WMA/LR/SEASONAL/YOY，缺省 SMA |
| window | int | 否 | 默认 12 |
| period | int | 否 | 默认 7 |
| periods | int | 否 | 预测期数，默认 30，上限 90 |
| intervalMinutes | int | 否 | 预测点间隔分钟，默认 360 |

**响应：** 生成的预测记录数（int）

**注意：** 历史快照不足时返回 `BI_FORECAST_NO_HISTORY` 错误码（code 非 0），前端需提示"暂无历史数据，无法预测"。

### 5. 既有接口（无变更）

- `POST /bi/dashboard/{dashboardCode}/data` — 大屏数据（沿用既有 `bi_dashboard_frontend.md` 联调约定）
- `GET /bi/decision/forecast/list`、`POST /bi/decision/forecast/history`、`POST /bi/decision/forecast/generate-work-order`、`GET /bi/decision/alert/page` 等

## KPI 编码清单（前端展示用）

| 域 | KPI 编码 | 名称 | 单位 |
|----|----------|------|------|
| energy | energy_telemetry_devices | 遥测在采设备数 | 台 |
| energy | energy_telemetry_points | 在采测点总数 | 个 |
| energy | energy_anomaly_rate | 遥测异常率 | % |
| energy | energy_power_load | 实时功率负荷 | kW |
| energy | energy_power_consumption | 周期用电量 | kWh |
| device_operation | device_total / device_running | 设备总数 / 运行设备数 | 台 |
| device_operation | device_operation_rate | 开机率 | % |
| device_operation | device_avg_efficiency | 平均生产效率 | 件/时 |
| device_operation | device_need_repair | 待维修工单数 | 单 |
| production | prod_work_order_total / prod_work_order_finish | 工单总数 / 累计产量 | 单 / 件 |
| production | prod_plan_achieve_rate / prod_feedback_qualified | 计划达成率 / 报工合格率 | % |
| production | prod_daily_output | 今日产量 | 件 |
| quality | quality_iqc_pass_rate / quality_ipqc_pass_rate / quality_oqc_pass_rate | 来料/过程/出货合格率 | % |
| quality | quality_ncr_count | 不合格品报告数 | 单 |
| procurement | pur_request_amount / pur_order_amount / pur_order_pending_in | 采购申请/订单金额、待入库量 | 元 / 件 |
| procurement | stock_amount_value / stock_low_alert | 库存货值 / 低库存物料数 | 元 / 个 |
| procurement | cost_payment_amount | 应付款近30天 | 元 |
| sales | sale_order_amount / crm_contract_amount / crm_receivable_amount | 销售订单/合同/回款金额 | 元 |
| sales | crm_customer_count / srm_avg_score | 客户数 / 供应商评分 | 个 / 分 |
| safety | safety_andon_count / safety_andon_unhandled | 安灯报警数 / 未处置数 | 次 / 个 |

## 新增大屏 code 与数据带入说明

| dashboardCode | 名称 | 数据带入 / 刷新 |
|---------------|------|------------------|
| decision_overview | 决策总览 | number/gauge 卡片 5 分钟刷新，趋势折线 10 分钟刷新 |
| energy | 能耗监控 | 实时卡片 5 分钟刷新；无功率/电量测点时"功率负荷"显示 0 |
| sales_customer | 营销客户 | 指标卡片 10 分钟刷新 |

> 大屏统一走 `POST /bi/dashboard/{code}/data`，`position` 用 12 列栅格（`{x,y,w,h}`），图表类型 number/gauge/line/bar 渲染约定与既有 `bi_dashboard_frontend.md` 一致。

## 业务规则说明

| 场景 | 规则 |
|------|------|
| KPI 首次配置 | 快照从下一个整点开始聚合，趋势接口暂空 |
| 业务表无数据 | KPI 返回 0 或空，不视为异常；设备/遥测当前即有真实数据 |
| 能耗无功率测点 | 功率负荷/用电量返回 0，属正常占位；补充功率类测点后自动出值 |
| 预测无历史 | 返回 `BI_FORECAST_NO_HISTORY`，前端提示无历史数据 |
| 预警去重 | 同一 KPI 已有未处理预警时不重复生成，人工处理后恢复 |

## 注意事项

- 指标卡/仪表盘面板建议对"分类"做 tab 分组（能耗/设备/生产/质量/采购/营销/安全），共用同一套卡片组件。
- 预警中心页面（既有）已支持未处理计数与确认/处理操作，可直接复用本次 KPI 体系产出的 `bi_alert_record`。
- 权限点沿用既有：`bi:decision:kpi:query/update`、`bi:decision:alert:query/confirm/handle`，新接口不新增权限，无需改菜单。