feat: Initial CBPOA commit — 武汉儿童呼吸疾病风险评估系统
Context: Build a spatial risk assessment system correlating air quality data with children's respiratory disease incidence across Wuhan. Approach: FastAPI backend serving PostGIS spatial queries, React frontend with Deck.gl maps, and a PyTorch SpatialTemporalGCN pipeline for multi-day (1d/3d/7d) risk prediction. Changes: - backend/ — FastAPI API with auth (JWT), alerts, risk analysis, geocoded case data, grid statistics, and report endpoints - frontend/ — React dashboard with interactive risk maps, alert monitoring, district comparison charts, and timeline player - models/ — SpatialTemporalGCN model with trained weights and ONNX export for inference - scripts/ — ETL pipeline for weather + medical data, grid generation, feature engineering, training, and daily inference - deploy/ — Docker Compose configs for backend, frontend, and MLflow - docs/ — API docs, deployment guide, user guide, and code review Impact: Enables spatial risk visualization, alert monitoring, and ML-driven health risk forecasting for environmental health teams.
This commit is contained in:
241
docs/API.md
Normal file
241
docs/API.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 武汉市疾病监测预警系统 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、多日预测 |
|
||||
Reference in New Issue
Block a user