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.
2026-06-05 02:13:49 +08:00
commit fc468464b2
117 changed files with 18282 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,374 @@
+# 武汉市疾病监测预警系统 - 部署文档
+
+## 系统要求
+
+### 硬件要求
+- **CPU**: 4 核以上
+- **内存**: 8GB 以上 (推荐 16GB)
+- **存储**: 50GB 可用空间
+- **网络**: 本地部署无需公网
+
+### 软件要求
+- **Docker**: 20.10+
+- **Docker Compose**: 2.0+
+- **PostgreSQL**: 15+ (通过 Docker 提供)
+- **Node.js**: 18+ (仅开发环境)
+- **Python**: 3.11+ (仅开发环境)
+
+---
+
+## 快速开始 (Docker Compose)
+
+### 1. 克隆项目
+
+```bash
+git clone <repository-url>
+cd CA
+```
+
+### 2. 配置环境变量
+
+```bash
+cp deploy/.env.example deploy/.env
+```
+
+编辑 `deploy/.env` 文件，修改以下关键配置:
+
+```bash
+# 数据库密码 (必须修改)
+POSTGRES_PASSWORD=your_secure_password
+
+# 数据库连接字符串 (必须与密码一致)
+DATABASE_URL=postgresql://wuhan_user:your_secure_password@postgres:5432/wuhan_disease
+
+# API 地址 (开发环境)
+VITE_API_URL=http://localhost:8000
+```
+
+### 3. 启动服务
+
+```bash
+cd deploy
+docker compose up -d
+```
+
+### 4. 验证部署
+
+```bash
+# 检查服务状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f
+
+# 测试后端 API
+curl http://localhost:8000/health
+
+# 测试前端
+curl http://localhost:3000
+```
+
+### 5. 访问应用
+
+- **前端**: http://localhost:3000
+- **后端 API**: http://localhost:8000
+- **API 文档**: http://localhost:8000/docs
+- **PostgreSQL**: localhost:5432
+
+---
+
+## 服务架构
+
+```
+┌─────────────────┐
+│   Frontend      │  Port 3000
+│   (Nginx)       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Backend      │  Port 8000
+│   (FastAPI)     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   PostgreSQL    │  Port 5432
+│   (PostGIS)     │
+└─────────────────┘
+```
+
+---
+
+## Docker Compose 配置说明
+
+### 服务列表
+
+| 服务 | 镜像 | 端口 | 说明 |
+|------|------|------|------|
+| `postgres` | `postgis/postgis:15-3.3` | 5432 | PostgreSQL + PostGIS |
+| `backend` | 本地构建 | 8000 | FastAPI 后端 |
+| `frontend` | 本地构建 | 3000:80 | Nginx 前端 |
+
+### 数据持久化
+
+PostgreSQL 数据存储在 Docker volume `postgres_data` 中:
+
+```bash
+# 查看 volume
+docker volume ls | grep postgres
+
+# 备份数据
+docker run --rm -v ca_deploy_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .
+
+# 恢复数据
+docker run --rm -v ca_deploy_postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /data
+```
+
+---
+
+## 初始化数据库
+
+### 1. 创建 grids 表
+
+```bash
+docker compose exec postgres psql -U wuhan_user -d wuhan_disease -f /docker-entrypoint-initdb.d/init.sql
+```
+
+或手动执行:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS postgis;
+
+CREATE TABLE IF NOT EXISTS grids (
+    grid_id VARCHAR(20) PRIMARY KEY,
+    geometry GEOMETRY(POLYGON, 4326) NOT NULL,
+    center_lat DOUBLE PRECISION NOT NULL,
+    center_lon DOUBLE PRECISION NOT NULL,
+    district VARCHAR(50),
+    dem DOUBLE PRECISION,
+    population_density DOUBLE PRECISION,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_grids_geometry ON grids USING GIST (geometry);
+CREATE INDEX idx_grids_district ON grids (district);
+```
+
+### 2. 导入网格数据
+
+```bash
+# 从容器外复制数据到容器
+docker cp processed/grid_100m_index.parquet $(docker compose ps -q postgres):/tmp/grid_data.parquet
+
+# 在容器内导入
+docker compose exec postgres python3 << 'EOF'
+import pandas as pd
+import geopandas as gpd
+from sqlalchemy import create_engine
+
+df = pd.read_parquet('/tmp/grid_data.parquet')
+gdf = gpd.GeoDataFrame(
+    df,
+    geometry=gpd.points_from_xy(df['center_lon'], df['center_lat']),
+    crs='EPSG:4326'
+)
+
+engine = create_engine('postgresql://wuhan_user:wuhan_password@localhost:5432/wuhan_disease')
+gdf.to_postgis('grids', engine, if_exists='replace', index=False)
+EOF
+```
+
+---
+
+## 开发环境部署
+
+### 1. 后端开发环境
+
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 2. 前端开发环境
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+### 3. 运行测试
+
+```bash
+# 后端测试
+cd backend
+pytest
+
+# 前端测试
+cd frontend
+npm test
+
+# E2E 测试
+cd frontend
+npx playwright test
+```
+
+---
+
+## 生产环境部署
+
+### 1. 安全配置
+
+```bash
+# .env 文件
+POSTGRES_PASSWORD=<强密码>
+DATABASE_URL=postgresql://wuhan_user:<强密码>@postgres:5432/wuhan_disease
+
+# 启用 HTTPS (通过反向代理)
+# 配置 Nginx SSL 证书
+```
+
+### 2. 性能优化
+
+```bash
+# 增加 PostgreSQL 连接池
+# 编辑 postgresql.conf
+max_connections = 200
+shared_buffers = 2GB
+
+# 启用后端缓存
+# 编辑 backend/app/performance.py
+FEATURE_CACHE_TTL=7200  # 2 小时
+```
+
+### 3. 日志管理
+
+```bash
+# 查看实时日志
+docker compose logs -f backend
+docker compose logs -f frontend
+docker compose logs -f postgres
+
+# 导出日志
+docker compose logs > all-logs.txt
+```
+
+---
+
+## 故障排查
+
+### 常见问题
+
+#### 1. 后端无法连接数据库
+
+```bash
+# 检查数据库服务
+docker compose ps postgres
+
+# 查看数据库日志
+docker compose logs postgres
+
+# 测试连接
+docker compose exec backend python -c "import asyncpg; asyncio.run(asyncpg.connect('postgresql://...'))"
+```
+
+#### 2. 前端无法连接后端
+
+```bash
+# 检查 VITE_API_URL 配置
+docker compose exec frontend env | grep VITE
+
+# 测试后端可达性
+docker compose exec frontend curl http://backend:8000/health
+```
+
+#### 3. 内存不足
+
+```bash
+# 限制容器内存
+# 编辑 docker-compose.yml
+services:
+  backend:
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+```
+
+---
+
+## 备份与恢复
+
+### 备份
+
+```bash
+# 数据库备份
+docker compose exec postgres pg_dump -U wuhan_user wuhan_disease > backup.sql
+
+# 完整备份 (数据库 + 配置文件)
+tar czf backup-$(date +%Y%m%d).tar.gz \
+  deploy/.env \
+  backup.sql \
+  processed/
+```
+
+### 恢复
+
+```bash
+# 数据库恢复
+docker compose exec -T postgres psql -U wuhan_user -d wuhan_disease < backup.sql
+
+# 解压备份
+tar xzf backup-20260502.tar.gz
+```
+
+---
+
+## 监控与告警
+
+### 健康检查端点
+
+- **后端**: `GET http://localhost:8000/health`
+- **前端**: `GET http://localhost:3000`
+- **数据库**: `docker compose exec postgres pg_isready`
+
+### Prometheus 指标 (未来扩展)
+
+```bash
+# 启用指标端点
+# 编辑 backend/main.py
+from prometheus_fastapi_instrumentator import Instrumentator
+Instrumentator().instrument(app).expose(app)
+```
+
+---
+
+## 更新与升级
+
+### 更新代码
+
+```bash
+git pull
+docker compose down
+docker compose build
+docker compose up -d
+```
+
+### 数据库迁移
+
+```bash
+# 运行迁移脚本
+docker compose exec backend python scripts/migrate.py
+```
+
+---
+
+## 联系与支持
+
+- **项目仓库**: `<repository-url>`
+- **问题反馈**: GitHub Issues
+- **文档**: `/docs` 目录