# 决策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 中的占位符传递参数 |

**响应格式：**

```json
{
  "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 已安装在前端项目中。渲染流程：

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

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| name | 图表标题 | 显示在图表上方 |
| chartType | - | 决定渲染方式 |
| refreshInterval | 图表角落 | 如 > 0，显示"每 N 秒刷新"标签 |
| position | - | 决定图表在页面中的位置和大小 |
| data | 图表内容 | 图表的数据来源 |
| error | 图表内容 | 如果 SQL 执行失败，显示错误信息 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 仪表盘禁用 | 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，不需要知道连接细节