决策BI大屏 - 前端联调方案

涉及页面

采购销售售后大屏
仓库大屏
生产设备大屏
质量大屏
人资办公大屏
图表配置管理页
数据源配置管理页

API

1. 获取仪表盘数据

方法	路径	说明
POST	`/bi/dashboard/{dashboardCode}/data`	获取指定仪表盘的所有图表数据

路径参数：

参数	类型	必填	说明
dashboardCode	String	是	仪表盘编码：purchase_sales / warehouse / production_equipment / quality / hr_oa

请求参数（JSON Body，可选）：

参数	类型	必填	说明
startDate	String	否	查询开始日期
endDate	String	否	查询结束日期
其他	Any	否	根据图表 SQL 中的占位符传递参数

响应格式：

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "本月采购金额趋势",
      "chartType": "line",
      "refreshInterval": 60,
      "position": {"x": 0, "y": 0, "w": 12, "h": 6},
      "chartOptions": {"title": {"text": "采购金额趋势"}},
      "data": [
        {"date": "2026-01", "amount": 150000},
        {"date": "2026-02", "amount": 200000}
      ]
    }
  ]
}

图表类型（chartType）：

值	说明	ECharts 系列类型
bar	柱状图	bar
line	折线图	line
pie	饼图	pie
scatter	散点图	scatter
gauge	仪表盘	gauge
table	表格	自定义渲染
number	数字卡片	自定义渲染

2. 图表配置 CRUD

方法	路径	说明
POST	`/bi/chart-config/create`	创建图表配置
PUT	`/bi/chart-config/update`	更新图表配置
DELETE	`/bi/chart-config/delete?id={id}`	删除图表配置
GET	`/bi/chart-config/get?id={id}`	获取图表配置详情
GET	`/bi/chart-config/page?dashboardId={}&pageNo={}&pageSize={}`	分页查询

3. 数据源配置 CRUD

方法	路径	说明
POST	`/bi/data-source-config/create`	创建数据源配置
PUT	`/bi/data-source-config/update`	更新数据源配置
DELETE	`/bi/data-source-config/delete?id={id}`	删除数据源配置
GET	`/bi/data-source-config/get?id={id}`	获取数据源配置详情
GET	`/bi/data-source-config/page?pageNo={}&pageSize={}`	分页查询

仪表盘页面布局

每个仪表盘页面（如 /bi/purchase-sales）结构为单页，页面加载后调用 POST /bi/dashboard/{code}/data 获取所有图表数据，根据每个图表的 position 字段（{x, y, w, h}）使用 CSS Grid 或 flex 布局渲染。

position 字段说明：
- x: 列起始位置（0-based）
- y: 行起始位置（0-based）
- w: 占用列数（总宽度12列）
- h: 占用行高

自动刷新

如果图表的 refreshInterval > 0，前端应使用 setInterval 定时重新请求该仪表盘数据。刷新过程中不显示 loading 遮罩，静默更新。

图表渲染

ECharts 6.1 已安装在前端项目中。渲染流程：

根据 chartType 确定 ECharts 系列类型（bar→bar, line→line, pie→pie, scatter→scatter, gauge→gauge）
将 chartOptions（JSON）作为 base ECharts option
将 data 作为 series.data 或 dataset.source 填入
如果 chartType 为 table 或 number，使用自定义组件渲染而非 ECharts

字段展示规则

字段	展示位置	说明
name	图表标题	显示在图表上方

业务规则说明

场景	规则
仪表盘禁用	dashboard status=0 时，接口返回错误，前端显示提示
图表禁用	chartConfig status=0 的图表不会出现在响应中
SQL 执行失败	chartData 中 data 为空数组，error 字段包含错误信息，前端在该图表位置显示错误提示
无参数请求	params 为 null 时，SQL 中的占位符不会被替换，直接执行原始 SQL

注意事项

仪表盘页面对应的前端路由为 /bi/{code}（如 /bi/purchase-sales），组件统一使用 bi/dashboard/index
仪表盘的 code 通过路由地址获取，不同仪表盘用同一个页面组件
图表配置中的 query_sql 由后端执行，前端不直接操作 SQL
chart_options 字段是完整或部分 ECharts option 对象，前端应深度 merge 到默认配置上
数据源配置（bi_data_source_config）是后端概念，前端只需选择数据源 ID，不需要知道连接细节