# 应急推演功能使用指南

## 功能概述

本功能实现了 Issue #70 要求的"应急推演（爆管模拟 + 水质异常处置预案）"，包括：

1. **爆管模拟**：分析爆管影响区域、关阀方案、受影响用户、恢复时间
2. **水质异常处置**：停水方案、备用水源、风险等级评估
3. **预案管理**：应急预案的创建、应用和管理
4. **应急响应**：基于推演结果生成调度指令

## 技术实现

### 核心组件

- **EmergencySimulationService**: 应急推演核心服务
- **EmergencyPlanService**: 应急预案管理服务
- **EmergencyDispatchService**: 应急调度服务
- **EmergencySimulationController**: 推演API控制器
- **EmergencyPlanController**: 预案API控制器
- **EmergencyDispatchController**: 调度API控制器

### 数据库表

- `prod_emergency_simulation`: 应急推演记录表
- `prod_emergency_plan`: 应急预案表

### 主要功能流程

1. 创建推演 → 执行推演 → 生成调度指令 → 应用应急预案 → 完成响应

## API接口文档

### 1. 快速爆管模拟

```bash
POST /api/emergency/dispatch/quick-pipe-burst
Content-Type: application/json

{
  "lng": 116.4074,
  "lat": 39.9042,
  "pipeDiameter": "DN100",
  "operatorName": "operator_name"
}
```

响应示例：
```json
{
  "success": true,
  "simulation": {
    "simulationNo": "SIM-20240614010001",
    "scenarioType": "pipe_burst",
    "scenarioName": "爆管应急推演",
    "affectedArea": "半径500m圆形区域",
    "affectedCustomers": 230,
    "estimatedRecoveryHours": 4,
    "status": "completed"
  },
  "executionResult": {
    "impactAnalysis": {
      "affectedArea": "半径500m圆形区域",
      "affectedCustomers": 230,
      "estimatedRecoveryHours": 4
    },
    "emergencyMeasures": {
      "valveShutdown": "关闭上游阀门 V-001, V-002",
      "emergencyWater": "启动应急供水方案 B",
      "userNotification": "通知受影响用户（短信+公告）",
      "repairTeam": "调度抢修队出发"
    }
  },
  "suggestedCommands": [
    {
      "title": "爆管应急推演",
      "type": "emergency",
      "priority": "high",
      "content": "爆管应急响应..."
    }
  ]
}
```

### 2. 快速水质异常模拟

```bash
POST /api/emergency/dispatch/quick-water-quality
Content-Type: application/json

{
  "area": "市中心区域",
  "pollutant": "重金属",
  "lng": 116.4074,
  "lat": 39.9042,
  "operatorName": "operator_name"
}
```

### 3. 应急预案管理

```bash
# 创建预案
POST /api/emergency/plan/create
?planName=预案名称&planType=disaster&scenario=爆管&operatorName=operator_name

# 激活预案
POST /api/emergency/plan/{planId}/activate
?operatorName=operator_name

# 查询预案列表
GET /api/emergency/plan/list
?page=1&size=10&planType=all&status=active
```

### 4. 应急状态查询

```bash
GET /api/emergency/dispatch/status
```

响应示例：
```json
{
  "success": true,
  "status": {
    "alertLevel": "medium",
    "preparednessScore": 85,
    "recentSimulations": [...],
    "activePlans": [...],
    "activeCommands": [...]
  }
}
```

### 5. 生成应急报告

```bash
GET /api/emergency/dispatch/report?period=week
```

## 数据模型

### EmergencySimulation（应急推演记录）

| 字段 | 类型 | 描述 |
|------|------|------|
| simulationNo | String | 推演编号 |
| scenarioType | String | 推演类型（pipe_burst/water_quality） |
| scenarioName | String | 推演名称 |
| locationLng | Double | 经度 |
| locationLat | Double | 纬度 |
| pipeDiameter | String | 管道直径 |
| affectedArea | String | 影响区域 |
| affectedCustomers | Integer | 受影响用户数 |
| estimatedRecoveryHours | Integer | 预计恢复时间 |
| status | String | 状态（draft/executing/completed/with_plan） |

### EmergencyPlan（应急预案）

| 字段 | 类型 | 描述 |
|------|------|------|
| planNo | String | 预案编号 |
| planName | String | 预案名称 |
| planType | String | 预案类型（disaster/accident/emergency） |
| scenario | String | 适用场景 |
| triggerConditions | String | 触发条件 |
| responseProcedure | String | 响应流程 |
| responsibleDepartments | String | 责任部门 |
| contactInfo | String | 联系信息 |
| resourceRequirements | String | 资源需求 |
| backupSolutions | String | 备用方案 |
| status | String | 状态（draft/active/inactive/expired） |

## 业务流程

### 爆管应急响应流程

1. **触发条件检测**
   - 管道压力异常波动
   - 地面出现喷水现象
   - 用户报告大面积停水
   - 系统监测到漏水量异常

2. **影响分析**
   - 基于管道直径计算影响半径
   - 计算受影响用户数量
   - 生成关阀方案

3. **应急措施**
   - 关闭上游阀门
   - 启动应急供水方案
   - 通知受影响用户
   - 调度抢修队

4. **恢复重建**
   - 组织抢修
   - 水质检测
   - 恢复供水
   - 用户通知

### 水质异常应急响应流程

1. **触发条件检测**
   - 水质检测指标超标
   - 用户反映水质异常
   - 上游水源污染报告
   - 系统监测到浊度/色度异常

2. **影响分析**
   - 评估污染程度和范围
   - 确定风险等级
   - 选择备用水源

3. **应急措施**
   - 立即停止异常区域供水
   - 启动备用水源
   - 水质采样送检
   - 发布停水通知

4. **恢复重建**
   - 水质达标后恢复供水
   - 清洗管道系统
   - 用户通知和解释

## 预警级别定义

### 警报级别

- **低级**（low）：日常监测，无需特别关注
- **中级**（medium）：有推演记录，需要关注
- **高级**（high）：高风险事件，需要立即响应

### 风险等级（水质异常）

- **中等**（medium）：一般污染物影响，2-4小时恢复
- **高**（high）：较严重污染物，4-8小时恢复
- **严重**（critical）：剧毒污染物，8小时以上恢复

## 系统集成

### 与现有调度系统集成

1. **DispatchCommandService**: 生成调度指令
2. **DispatchTrackingService**: 跟踪指令执行
3. **AlertEngine**: 警报系统集成

### 与其他系统集成

- **用户服务**: 获取用户信息
- **通知服务**: 发送用户通知
- **GIS服务**: 地理信息分析
- **物联网平台**: 设备状态监控

## 测试和验证

### 自动化测试

运行测试脚本验证功能：
```bash
cd water-management-system
python test_emergency_simulation.py
```

### 手动测试清单

- [x] 爆管模拟创建和执行
- [x] 水质异常模拟创建和执行
- [x] 应急预案创建和管理
- [x] 应急状态查询
- [x] 应急报告生成
- [x] 调度指令生成和应用
- [x] 数据库完整性检查

## 部署和配置

### 数据库迁移

```sql
-- 执行数据库迁移脚本
psql -d water_management -f wm-production/src/main/resources/db/V3__emergency_simulation.sql
psql -d water_management -f wm-production/src/main/resources/db/V3__emergency_simulation_data.sql
```

### Spring Boot 配置

在 `application.yml` 中添加：
```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/water_management
    username: water_user
    password: water_pass
```

## 故障排除

### 常见问题

1. **数据库连接失败**
   - 检查数据库配置
   - 确认数据库服务运行

2. **API接口返回500错误**
   - 检查日志文件
   - 确认参数格式正确

3. **推演结果异常**
   - 检查输入参数
   - 确认地理坐标有效

### 日志查看

```bash
# 查看应用日志
tail -f logs/wm-production.log

# 查看数据库日志
tail -f postgresql.log
```

## 扩展功能

### 未来规划

1. **AI驱动的智能推演**
   - 机器学习预测影响范围
   - 智能推荐最佳方案

2. **3D可视化**
   - 三维地理信息展示
   - 实时监控和预警

3. **移动端支持**
   - 手机端应急响应
   - 现场数据采集

### 性能优化

1. **缓存机制**
   - 缓存常用预案
   - 缓存地理信息

2. **异步处理**
   - 推演任务异步执行
   - 推送通知异步处理

3. **负载均衡**
   - 分布式部署
   - 负载均衡配置

## 联系支持

如有问题请联系：
- 开发团队：dev-team@water.com
- 技术支持：support@water.com
- 紧急联系：400-123-4567