# 大屏可视化系统 API 文档 (v1.0.0)

## 1. 接口概述

### 1.1 功能范围
- 产业数据概览展示
- 实时监控数据推送
- 历史数据查询分析
- 地图区域数据展示

### 1.2 基础路径
`/api/v1/dashboard`

### 1.3 权限控制
- 公开接口（无需认证）：数据查询和展示
- 管理接口（需要认证）：数据配置和管理

### 1.4 全局错误码
| 状态码 | 说明               |
|--------|--------------------|
| 400    | 请求参数无效       |
| 401    | 未授权             |
| 403    | 权限不足           |
| 404    | 资源不存在         |
| 500    | 服务器内部错误     |

## 2. 接口明细

### 2.1 获取实时数据
```
GET /realtime
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| 无参数      |        |      |                    |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "timestamp": "2023-08-19T10:30:00Z",
    "total_cattle": 128456,
    "total_farms": 1245,
    "annual_output_value": 2860000000,
    "total_transaction": 1520000000
  }
}
```

### 2.2 WebSocket实时数据推送
```
WebSocket /ws
```

**推送数据格式**:
```json
{
  "type": "realtime_update",
  "data": {
    "timestamp": "2023-08-19T10:30:00Z",
    "total_cattle": 128456,
    "total_farms": 1245,
    "annual_output_value": 2860000000,
    "total_transaction": 1520000000
  }
}
```

### 2.3 获取历史数据
```
GET /history
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| start_date  | string | 否   | 开始日期(YYYY-MM-DD)|
| end_date    | string | 否   | 结束日期(YYYY-MM-DD)|
| type        | string | 是   | 数据类型           |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "date": "2023-01",
        "value": 8200
      },
      {
        "date": "2023-02",
        "value": 9100
      }
    ],
    "total": 12,
    "start_date": "2023-01-01",
    "end_date": "2023-12-31"
  }
}
```

### 2.4 获取区域地图数据
```
GET /map/regions
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| 无参数      |        |      |                    |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "regions": [
      {
        "id": "xlg",
        "name": "锡林浩特市",
        "coordinates": [116.093, 43.946],
        "cattle_count": 25600,
        "farm_count": 120,
        "output_value": 650000000
      },
      {
        "id": "dwq",
        "name": "东乌旗",
        "coordinates": [116.980, 45.514],
        "cattle_count": 18500,
        "farm_count": 95,
        "output_value": 480000000
      }
    ],
    "total": 12
  }
}
```

### 2.5 获取指定区域详细数据
```
GET /map/region/{regionId}
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| regionId    | string | 是   | 区域ID             |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "region": {
      "id": "xlg",
      "name": "锡林浩特市",
      "coordinates": [116.093, 43.946],
      "cattle_count": 25600,
      "farm_count": 120,
      "output_value": 650000000,
      "trend": "up"
    },
    "farms": [
      {
        "id": "FARM001",
        "name": "锡林浩特市第一牧场",
        "coordinates": [116.120, 43.950],
        "cattle_count": 2450,
        "output_value": 62000000
      }
    ]
  }
}
```

## 3. 版本历史

### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

### 2.6 获取大屏配置
```
GET /config
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| 无参数      |        |      |                    |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "layout": "grid",
    "theme": "dark",
    "refresh_interval": 30,
    "charts": [
      {
        "id": "cattle_count",
        "type": "line",
        "title": "牛只数量趋势",
        "position": "top-left"
      },
      {
        "id": "transaction_volume",
        "type": "bar",
        "title": "交易量统计",
        "position": "top-right"
      }
    ]
  }
}
```

### 2.7 更新大屏配置
```
PUT /config
```

**请求参数**:
| 参数名          | 类型   | 必填 | 说明               |
|-----------------|--------|------|--------------------|
| layout          | string | 是   | 布局方式           |
| theme           | string | 是   | 主题               |
| refresh_interval| number | 是   | 刷新间隔(秒)       |
| charts          | array  | 是   | 图表配置           |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "message": "配置更新成功"
  }
}
```

## 5. 数据格式

### 5.1 产业概览数据
```json
{
  "total_cattle": 128456,
  "total_farms": 1245,
  "annual_output_value": 2860000000,
  "total_transaction": 1520000000,
  "growth_rate": 5.2
}
```

### 5.2 养殖监控数据
```json
{
  "farm_id": "FARM001",
  "temperature": 22.5,
  "humidity": 65,
  "cattle_count": 245,
  "feed_consumption": 1200
}
```

### 5.3 金融服务数据
```json
{
  "loan_amount": 8600000,
  "insurance_policies": 12450,
  "claim_amount": 245000,
  "approval_rate": 92.5
}
```

### 5.4 交易统计数据
```json
{
  "daily_transactions": 125,
  "average_price": 18500,
  "regional_distribution": [
    {
      "region": "东乌旗",
      "count": 1200
    }
  ]
}
```

## 6. 错误处理

### 6.1 错误响应格式
```json
{
  "error": {
    "code": "DASHBOARD_001",
    "message": "获取数据失败",
    "details": "数据库连接异常"
  }
}
```

### 6.2 常见错误码
- `DASHBOARD_001`: 数据获取失败
- `DASHBOARD_002`: 参数错误
- `DASHBOARD_003`: 权限不足
- `DASHBOARD_004`: 系统内部错误

## 7. 权限说明

大屏可视化系统接口需要以下权限：
- `dashboard:view`: 查看大屏数据权限
- `dashboard:config`: 配置大屏权限

## 8. 注意事项

1. 大屏可视化系统主要面向内部管理使用，需要相应权限才能访问
2. 实时数据推送通过WebSocket实现，需要保持长连接
3. 历史数据支持分页查询，避免一次性加载大量数据
4. 所有接口均采用HTTPS加密传输