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/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -0,0 +1,364 @@
+# 武汉市疾病监测预警系统 - 用户手册
+
+## 目录
+
+1. [系统概述](#系统概述)
+2. [快速入门](#快速入门)
+3. [功能说明](#功能说明)
+4. [常见问题](#常见问题)
+
+---
+
+## 系统概述
+
+武汉市疾病监测预警系统是一个基于 Web 的地理信息系统 (GIS)，用于:
+
+- **实时监测**: 查看武汉市各区域的病例分布情况
+- **风险预测**: 预测未来 1-7 天的疾病风险等级
+- **历史分析**: 分析历史病例数据和气象数据的关系
+- **预警通知**: 高风险区域自动触发预警
+
+### 主要功能
+
+| 功能 | 说明 |
+|------|------|
+| 📍 地图可视化 | 100m 网格级别的病例和风险展示 |
+| 📊 统计图表 | 病例趋势、区县对比、风险分布 |
+| ⏱️ 时间轴播放 | 动态查看历史数据变化 |
+| 🔮 风险预测 | 基于 AI 模型的未来风险预测 |
+| 📱 响应式设计 | 支持桌面、平板、手机访问 |
+
+---
+
+## 快速入门
+
+### 1. 访问系统
+
+打开浏览器，访问: **http://localhost:3000**
+
+### 2. 主界面介绍
+
+```
+┌────────────────────────────────────────────┐
+│  顶部导航栏 (首页、监测、预警、分析)        │
+├────────────────────────────────────────────┤
+│                                            │
+│  地图区域 (病例分布/风险预测)               │
+│                                            │
+│                                            │
+├────────────────────────────────────────────┤
+│  时间轴播放器 (播放/暂停/速度控制)          │
+└────────────────────────────────────────────┘
+```
+
+### 3. 基本操作
+
+#### 查看病例分布
+
+1. 点击顶部导航栏的 **"监测"**
+2. 在地图上查看各区域的病例分布
+3. 点击任意网格查看详细统计信息
+
+#### 查看风险预测
+
+1. 点击顶部导航栏的 **"预警"**
+2. 选择预测天数 (1 天/3 天/7 天)
+3. 查看不同风险等级的区域分布
+
+#### 播放历史数据
+
+1. 在监测页面底部找到时间轴播放器
+2. 点击 ▶️ 播放按钮
+3. 使用滑块调整播放速度 (0.5x - 10x)
+
+---
+
+## 功能说明
+
+### 1. 监测仪表板 (Monitoring Dashboard)
+
+**访问路径**: `/monitoring`
+
+**功能**:
+- 实时病例分布地图
+- 时间轴播放器
+- 统计图表 (病例趋势、AQI 趋势)
+- 区县筛选
+
+**操作步骤**:
+
+1. **选择日期**
+   - 使用时间轴播放器选择日期
+   - 或直接拖动滑块到指定日期
+
+2. **筛选区域**
+   - 点击右上角"区域筛选"下拉框
+   - 选择特定区县查看该区域数据
+
+3. **查看详情**
+   - 点击地图上的任意网格
+   - 右侧弹出详细信息面板
+
+4. **播放动画**
+   - 点击 ▶️ 播放按钮
+   - 自动按日播放病例变化
+   - 点击 ⏸️ 暂停播放
+
+**界面元素**:
+
+| 元素 | 说明 |
+|------|------|
+| 📊 累计病例 | 选定时间范围内的总病例数 |
+| 📅 日均病例 | 平均每日新增病例数 |
+| 📈 趋势 | 病例变化趋势 (上升/下降/平稳) |
+| 🗺️ 地图 | 病例分布热力图 |
+| ⏱️ 时间轴 | 日期选择和播放控制 |
+
+---
+
+### 2. 风险预警 (Alerts Dashboard)
+
+**访问路径**: `/alerts`
+
+**功能**:
+- 高风险区域预警列表
+- 预警优先级排序 (P1/P2)
+- 预警原因说明
+- 预测时间显示
+
+**预警等级**:
+
+| 等级 | 颜色 | 说明 |
+|------|------|------|
+| P1 | 红色 | 紧急预警，需立即响应 |
+| P2 | 橙色 | 重要预警，需关注 |
+
+**预警触发条件**:
+- 风险值 > 0.8
+- 24 小时内风险上升 > 25%
+- 连续 3 天风险上升
+- 气象条件恶化 (AQI > 150)
+
+---
+
+### 3. 趋势分析 (Trend Analysis)
+
+**访问路径**: `/trend`
+
+**功能**:
+- 病例时间趋势图
+- 区县对比柱状图
+- 风险等级分布饼图
+- 气象因素关联分析
+
+**图表类型**:
+
+1. **时间趋势图**
+   - X 轴：日期
+   - Y 轴：病例数
+   - 多条线：门诊/住院/总计
+
+2. **区县对比图**
+   - 柱状图显示各区县病例数
+   - 按病例数降序排列
+
+3. **风险分布图**
+   - 饼图显示各风险等级占比
+   - 颜色对应风险等级
+
+---
+
+### 4. 区域洞察 (Insights)
+
+**访问路径**: `/insights`
+
+**功能**:
+- AI 生成的洞察报告
+- 关键发现摘要
+- 趋势分析
+- 相关性分析
+
+**洞察类型**:
+
+| 类型 | 图标 | 说明 |
+|------|------|------|
+| ⚠️ 警告 | 🔴 | 需要关注的异常情况 |
+| ✅ 成功 | 🟢 | 防控成效明显的区域 |
+| ℹ️ 信息 | 🔵 | 一般性统计分析 |
+
+---
+
+## 地图操作指南
+
+### 基本操作
+
+| 操作 | 方法 |
+|------|------|
+| 平移地图 | 鼠标左键拖动 |
+| 缩放地图 | 鼠标滚轮滚动 |
+| 放大区域 | 双击地图 |
+| 复位地图 | 点击右下角"复位"按钮 |
+
+### 图层控制
+
+点击地图右上角的 **图层图标** (📚):
+
+1. **病例分布** - 显示病例数据
+2. **风险预测** - 显示预测风险
+3. **预警区域** - 显示预警区域
+4. **网格** - 显示 100m 网格边界
+
+**调整透明度**:
+- 每个图层有透明度滑块
+- 拖动滑块调整透明度 (0-100%)
+
+---
+
+## 时间轴播放器使用指南
+
+### 播放控制
+
+| 按钮 | 功能 |
+|------|------|
+| ⏮️ | 跳到开始日期 |
+| ▶️/⏸️ | 播放/暂停 |
+| ⏭️ | 跳到下一天 |
+| 📅 | 日期滑块 |
+
+### 速度控制
+
+点击速度按钮切换播放速度:
+- **0.5x** - 慢速 (2 秒/天)
+- **1x** - 正常 (1 秒/天)
+- **2x** - 快速 (0.5 秒/天)
+- **5x** - 极快 (0.2 秒/天)
+- **10x** - 最快 (0.1 秒/天)
+
+---
+
+## 常见问题
+
+### Q1: 地图加载缓慢
+
+**原因**: 网格数据量较大 (近 100 万个单元)
+
+**解决方案**:
+1. 缩小地图范围
+2. 使用区县筛选功能
+3. 等待数据缓存完成
+
+### Q2: 时间轴播放卡顿
+
+**原因**: 浏览器性能限制
+
+**解决方案**:
+1. 降低播放速度
+2. 关闭其他浏览器标签页
+3. 使用 Chrome 或 Edge 浏览器
+
+### Q3: 预警信息不更新
+
+**原因**: 数据更新延迟
+
+**解决方案**:
+1. 刷新页面 (F5)
+2. 检查网络连接
+3. 联系系统管理员
+
+### Q4: 移动端显示异常
+
+**原因**: 屏幕尺寸过小
+
+**解决方案**:
+1. 横屏使用
+2. 使用平板或桌面设备
+3. 更新浏览器到最新版本
+
+---
+
+## 快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| `Space` | 播放/暂停时间轴 |
+| `←` | 上一天 |
+| `→` | 下一天 |
+| `Home` | 跳到开始日期 |
+| `End` | 跳到结束日期 |
+| `+` | 放大地图 |
+| `-` | 缩小地图 |
+
+---
+
+## 数据说明
+
+### 数据来源
+
+- **病例数据**: 武汉市各医院门诊和住院数据
+- **气象数据**: 武汉市气象监测站点数据
+- **人口数据**: LandScan 高分辨率人口密度数据
+- **高程数据**: DEM 数字高程模型
+
+### 更新频率
+
+| 数据类型 | 更新频率 |
+|----------|----------|
+| 病例数据 | 每日更新 |
+| 气象数据 | 每小时更新 |
+| 风险预测 | 每日更新 |
+| 预警信息 | 实时更新 |
+
+### 数据范围
+
+- **时间范围**: 2022 年 1 月 - 至今
+- **地理范围**: 武汉市全域 (约 8,500 km²)
+- **网格分辨率**: 100m × 100m (约 85 万个网格)
+
+---
+
+## 技术支持
+
+### 联系方式
+
+- **系统管理员**: admin@example.com
+- **技术支持**: support@example.com
+- **问题反馈**: GitHub Issues
+
+### 文档版本
+
+- **版本**: 1.0.0
+- **更新日期**: 2026-05-02
+- **适用系统版本**: 1.0.0+
+
+---
+
+## 附录
+
+### A. 风险等级说明
+
+| 等级 | 风险值 | 颜色 | 建议措施 |
+|------|--------|------|----------|
+| 低风险 | 0.0-0.2 | 绿色 | 常规监测 |
+| 中低风险 | 0.2-0.4 | 蓝色 | 加强监测 |
+| 中风险 | 0.4-0.6 | 黄色 | 关注动态 |
+| 中高风险 | 0.6-0.8 | 橙色 | 准备响应 |
+| 高风险 | 0.8-1.0 | 红色 | 立即响应 |
+
+### B. 区县列表
+
+- 江岸区、江汉区、硚口区、汉阳区、武昌区
+- 青山区、洪山区、东西湖区、汉南区、蔡甸区
+- 江夏区、黄陂区、新洲区
+
+### C. 图例说明
+
+**病例分布图例**:
+- 🟢 绿色：0-10 例
+- 🔵 蓝色：11-50 例
+- 🟡 黄色：51-100 例
+- 🟠 橙色：101-500 例
+- 🔴 红色：500+ 例
+
+**风险预测图例**:
+- 颜色对应风险等级 (见上表)
+- 数值范围：0.0 (无风险) - 1.0 (最高风险)