# LIMS 数据分析与展示 - 前端联调文档

## 1. 模块说明

本次在 `lims` 模块新增了“数据分析与展示”能力，覆盖：

- 数据趋势分析（按天/按小时）
- 数据比较分析（按数据类型/设备）
- 数据质量分布统计
- 概览指标看板（总量、异常、合格率、预警等）

接口统一前缀：`/lims/dataAnalysis`

---

## 2. 鉴权与通用约定

1. 鉴权方式：沿用系统现有 Token（`Authorization` 请求头）。
2. 返回格式：`AjaxResult`

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

3. 时间参数格式：`yyyy-MM-dd HH:mm:ss`
4. 默认时间范围：若 `startTime/endTime` 都不传，则默认最近 7 天。

---

## 3. 查询参数（通用）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startTime | string | 否 | 开始时间，格式：`yyyy-MM-dd HH:mm:ss` |
| endTime | string | 否 | 结束时间，格式：`yyyy-MM-dd HH:mm:ss` |
| dataType | string | 否 | 数据类型：`temperature/humidity/pressure/flow/concentration` |
| deviceCode | string | 否 | 设备编号 |
| granularity | string | 否 | 趋势粒度：`day/hour`，默认 `day` |
| dimension | string | 否 | 比较维度：`dataType/deviceName/deviceCode`，默认 `dataType` |
| topN | number | 否 | 比较分析返回条数，默认 `10`，最大 `50` |

---

## 4. 接口清单

| 接口 | 方法 | 说明 |
|---|---|---|
| `/lims/dataAnalysis/dashboard` | GET | 一次返回看板全部数据（推荐） |
| `/lims/dataAnalysis/overview` | GET | 仅返回概览指标 |
| `/lims/dataAnalysis/trend` | GET | 仅返回趋势数据 |
| `/lims/dataAnalysis/comparison` | GET | 仅返回比较分析数据 |
| `/lims/dataAnalysis/qualityDistribution` | GET | 仅返回质量分布数据 |

---

## 5. 详细返回结构

### 5.1 `GET /lims/dataAnalysis/dashboard`

`data` 结构：

```json
{
  "startTime": "2026-05-16 00:00:00",
  "endTime": "2026-05-22 23:59:59",
  "granularity": "day",
  "dimension": "dataType",
  "overview": {
    "totalCollections": 1200,
    "todayCollections": 210,
    "abnormalCollections": 38,
    "qualifiedRate": 94.17,
    "inProgressExperiments": 6,
    "warningMonitors": 3,
    "inStockSamples": 168
  },
  "trend": [
    {
      "time": "2026-05-16",
      "pointCount": 145,
      "avgValue": 23.65,
      "maxValue": 29.40,
      "minValue": 20.10
    }
  ],
  "comparison": [
    {
      "dimensionValue": "temperature",
      "pointCount": 560,
      "avgValue": 24.31,
      "maxValue": 33.20,
      "minValue": 18.90
    }
  ],
  "qualityDistribution": [
    {
      "category": "qualified",
      "pointCount": 1130,
      "ratio": 94.17
    },
    {
      "category": "abnormal",
      "pointCount": 38,
      "ratio": 3.17
    },
    {
      "category": "pending",
      "pointCount": 32,
      "ratio": 2.67
    }
  ]
}
```

字段解释：

- `overview.totalCollections`：时间范围内采集总条数  
- `overview.todayCollections`：最近 24 小时采集条数  
- `overview.qualifiedRate`：合格率（百分比）  
- `trend`：折线图数据源  
- `comparison`：柱状图/横向条形图数据源  
- `qualityDistribution`：饼图数据源

---

## 6. 前端调用建议

1. 页面初始化优先调用 `dashboard`，减少请求次数。
2. 用户切换筛选条件（时间、设备、数据类型）后，重新请求 `dashboard`。
3. 若页面分区加载，可分别调 `overview/trend/comparison/qualityDistribution`。
4. `trend` 已补齐时间轴空档位（无数据返回 0），可直接绘制连续折线。

---

## 7. 调用示例

```bash
curl -G 'http://localhost:8080/lims/dataAnalysis/dashboard' \
  --data-urlencode 'startTime=2026-05-16 00:00:00' \
  --data-urlencode 'endTime=2026-05-22 23:59:59' \
  --data-urlencode 'granularity=day' \
  --data-urlencode 'dimension=dataType' \
  --data-urlencode 'topN=10' \
  -H 'Authorization: Bearer <token>'
```