CA/docs/API.md

# 武汉市疾病监测预警系统 API 文档

## 概述

本 API 提供武汉市 100m 网格级别的疾病监测、风险预测和历史数据查询功能。

**Base URL**: `http://localhost:8000/api`

**认证**: 当前无需认证

---

## 端点列表

### 1. 历史数据聚合

#### `GET /api/history/aggregated`

按区县和日期聚合的历史病例和气象数据。

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `start_date` | string | 是 | 开始日期 (YYYY-MM-DD) |
| `end_date` | string | 是 | 结束日期 (YYYY-MM-DD) |
| `aggregation` | string | 否 | 聚合级别：`daily` (默认), `weekly`, `monthly` |
| `district` | string | 否 | 区县名称筛选 |

**响应示例**:
```json
{
  "aggregations": [
    {
      "district": "武昌区",
      "date": "2022-12-01",
      "total_cases": 15,
      "outpatient_count": 12,
      "inpatient_count": 3,
      "avg_AQI": 85.5,
      "avg_PM25": 45.2,
      "avg_PM10": 78.3
    }
  ],
  "total_records": 365,
  "date_range": ["2022-12-01", "2022-12-31"],
  "timestamp": "2026-05-02T10:30:00"
}
```

**使用示例**:
```bash
curl "http://localhost:8000/api/history/aggregated?start_date=2022-12-01&end_date=2022-12-31&aggregation=daily"
```

---

### 2. 网格 GeoJSON

#### `GET /api/grids/geojson`

获取指定日期的网格数据 GeoJSON 格式，用于地图可视化。

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `date` | string | 是 | 日期 (YYYY-MM-DD) |
| `district` | string | 否 | 区县名称筛选 |
| `risk_level` | string | 否 | 风险等级筛选 |

**响应示例**:
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [114.305, 30.598]
      },
      "properties": {
        "grid_id": "r100_c200",
        "latitude": 30.598,
        "longitude": 114.305,
        "district": "武昌区",
        "total_cases": 5,
        "population_density": 12500
      }
    }
  ],
  "timestamp": "2026-05-02T10:30:00"
}
```

**使用示例**:
```bash
curl "http://localhost:8000/api/grids/geojson?date=2022-12-15"
```

---

### 3. 多日风险预测

#### `POST /api/predict/multi-day`

生成指定日期开始的多日网格风险预测。

**请求体**:
```json
{
  "date": "2022-12-15",
  "days": 7,
  "district": "武昌区"
}
```

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `date` | string | 是 | 开始日期 (YYYY-MM-DD) |
| `days` | integer | 否 | 预测天数 (1-14, 默认 7) |
| `district` | string | 否 | 区县名称筛选 |

**响应示例**:
```json
{
  "predictions": [
    {
      "grid_id": "r100_c200",
      "latitude": 30.598,
      "longitude": 114.305,
      "risk_1day": 0.75,
      "risk_3day": 0.68,
      "risk_7day": 0.72,
      "risk_level": "medium_high",
      "confidence": 0.85
    }
  ],
  "total_grids": 998601,
  "date_range": ["2022-12-15", "2022-12-21"],
  "model_version": "1.3.7",
  "timestamp": "2026-05-02T10:30:00"
}
```

**使用示例**:
```bash
curl -X POST "http://localhost:8000/api/predict/multi-day" \
  -H "Content-Type: application/json" \
  -d '{"date": "2022-12-15", "days": 7}'
```

---

### 4. 网格历史数据

#### `GET /api/grids/{grid_id}/history`

获取指定网格的历史数据。

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `grid_id` | string | 是 | 网格 ID (如 `r100_c200`) |
| `days` | integer | 否 | 历史天数 (1-365, 默认 30) |

**响应示例**:
```json
{
  "grid_id": "r100_c200",
  "district": "武昌区",
  "history": [
    {
      "date": "2022-12-01",
      "cases": 5,
      "outpatient": 4,
      "inpatient": 1
    }
  ],
  "timestamp": "2026-05-02T10:30:00"
}
```

**使用示例**:
```bash
curl "http://localhost:8000/api/grids/r100_c200/history?days=30"
```

---

## 错误处理

**通用错误响应格式**:
```json
{
  "detail": "错误描述信息"
}
```

**常见错误码**:
| 状态码 | 说明 |
|--------|------|
| 400 | 请求参数错误 (日期格式错误、超出范围等) |
| 404 | 资源不存在 (网格 ID 无效等) |
| 500 | 服务器内部错误 |

---

## 数据字典

### 风险等级 (risk_level)

| 等级 | 风险值范围 | 颜色 |
|------|-----------|------|
| `low` | 0.0 - 0.2 | 绿色 (#22c55e) |
| `medium_low` | 0.2 - 0.4 | 蓝色 (#3b82f6) |
| `medium` | 0.4 - 0.6 | 黄色 (#eab308) |
| `medium_high` | 0.6 - 0.8 | 橙色 (#f97316) |
| `high` | 0.8 - 1.0 | 红色 (#ef4444) |

### 区县列表

- 江岸区、江汉区、硚口区、汉阳区、武昌区
- 青山区、洪山区、东西湖区、汉南区、蔡甸区
- 江夏区、黄陂区、新洲区

---

## 性能优化

- **缓存**: 特征数据缓存 TTL 为 1 小时
- **批量处理**: 网格预测按 10,000 个/批处理
- **分页**: 大结果集自动限制 (最多 50,000 条)

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-05-02 | 初始版本：历史聚合、网格 GeoJSON、多日预测 |