# 网格员任务处理功能 - 设计文档

## 1. 功能描述
本功能模块是为一线网格员（NEPG端）设计的核心操作界面。它使得网格员能够清晰地接收、查看和处理由管理员分配的污染勘查任务，并在简化的网格地图上获得路径指引，最终提交现场的AQI数据，完成任务闭环。

## 2. 涉及角色
- **主要使用者**: `网格员 (GRID_WORKER)`

## 3. 业务规则

### 3.1 任务接收与查看
- 网格员登录后，首页即为任务列表。
- 任务列表默认按`任务优先级`降序、`创建时间`升序排列。
- **任务优先级**由后端动态计算，主要基于反馈的`severityLevel`（严重等级）和任务的等待时长。
- 每个任务项应清晰展示关键信息：`标题`、`文字地址`、`优先级`、`状态`。

### 3.2 任务处理规则
- **任务接受与拒绝**:
  - 对于`severityLevel`为`HIGH`的任务，网格员**不可拒绝**。
  - 对于`severityLevel`为`LOW`或`MEDIUM`的任务，网格员在任务详情页可以点击"拒绝"按钮。
  - 拒绝时需选择一个预设的理由（如"当前任务繁忙"、"超出能力范围"等）。
  - 拒绝后，该任务会从该网格员的列表中移除，并由系统自动进行再分配。
- **数据提交**:
  - 网格员到达现场后，必须在任务详情页填写并提交`AQI数据`表单才能完成任务。
  - `AqiData`记录与`Feedback`记录强关联。
- **主动上报**: 系统允许网格员在没有关联任务的情况下，主动上报其所在网格的AQI数据。

### 3.3 地图与定位规则
- **实时定位**: 进入任务详情页时，App应请求获取网格员的实时地理位置，并在地图上标记。
- **路径规划**: A*路径规划仅在首次进入详情页时计算一次。如果网格员偏离了规划路径，可以提供一个"重新规划"按钮。
- **离线地图**: （未来规划）为节省流量和应对网络不佳的情况，可以考虑支持离线网格地图的缓存。

## 4. 功能实现流程

### 4.1 任务处理流程
```mermaid
graph TD
    subgraph "NEPG 端 (网格员操作)"
        A[登录系统] --> B[查看任务列表];
        B --> C{选择一个任务};
        C --> D[查看任务详情];
        
        D --> E{任务是否为HIGH等级?};
        E -- 否 --> F[显示"接受"和"拒绝"按钮];
        F -- 点击拒绝 --> G[任务被退回，流程结束];
        E -- 是 --> H[只显示"接受"按钮];
        
        F -- 点击接受 --> I{处理任务};
        H --> I;

        I --> J[在网格地图上<br>查看路径指引];
        J --> K[到达现场<br>勘查并记录数据];
        K --> L[填写并提交<br>AQI数据报告];
    end

    subgraph "后端服务"
        L --> M[创建AqiData记录];
        M --> N[更新Feedback状态<br>为SUBMITTED];
    end

    style D fill:#E3F2FD
    style G fill:#FFCDD2
    style N fill:#C8E6C9
```

### 4.2 主动上报流程
```mermaid
graph TD
    A[网格员在主界面<br>点击"主动上报"] --> B[进入上报页面];
    B --> C[系统自动获取<br>当前网格位置];
    C --> D[填写AQI数据表单];
    D --> E{点击提交};
    E --> F[后端创建无关联<br>feedbackId的AqiData记录];
    F --> G[提示"上报成功"];

    style C fill:#E3F2FD
    style F fill:#C8E6C9
```

## 5. API 接口设计

### 5.1 获取我的任务列表
- **URL**: `GET /api/worker/tasks`
- **权限**: `GRID_WORKER`
- **查询参数**: `status` (可选: `ASSIGNED`, `IN_PROGRESS`), `page`, `size`
- **成功响应** (`200 OK`): 返回分页的任务列表。

### 5.2 获取任务详情
- **URL**: `GET /api/worker/tasks/{taskId}`
- **权限**: `GRID_WORKER`
- **成功响应** (`200 OK`): 返回任务的详细信息，包含公众提交的描述、图片，以及A*算法规划出的路径坐标点数组。

### 5.3 接受任务
- **URL**: `POST /api/worker/tasks/{taskId}/accept`
- **权限**: `GRID_WORKER`
- **成功响应** (`200 OK`): `{ "message": "任务已接受" }`

### 5.4 拒绝任务
- **URL**: `POST /api/worker/tasks/{taskId}/reject`
- **权限**: `GRID_WORKER`
- **请求体**: `{"reason": "当前任务繁忙"}`
- **成功响应** (`200 OK`): `{ "message": "任务已拒绝" }`

### 5.5 提交任务报告
- **URL**: `POST /api/worker/tasks/{taskId}/submit`
- **权限**: `GRID_WORKER`
- **请求体** (application/json):
  ```json
  {
    "notes": "已到现场检查，确认存在异味，已要求整改",
    "aqiData": {
      "pm25": 75.5, "pm10": 120.3, "so2": 15.8, 
      "no2": 40.2, "co": 1.2, "o3": 65.2
    }
  }
  ```
- **成功响应** (`200 OK`): `{ "message": "任务报告提交成功，等待主管审核" }`

### 5.6 主动上报AQI数据
- **URL**: `POST /api/worker/aqi-data/report`
- **权限**: `GRID_WORKER`
- **请求体**:
  ```json
  {
    "gridX": 15,
    "gridY": 20,
    "aqiData": { ... }
  }
  ```
- **成功响应** (`201 Created`): `{ "message": "数据上报成功" }`

## 6. 错误处理与边界情况

| 场景 | 触发条件 | 系统处理 | 用户提示 |
| :--- | :--- | :--- | :--- |
| **定位失败** | App无法获取GPS信号 | 地图模块显示默认位置（如市中心），并提示用户检查定位服务 | "无法获取您的位置，请检查GPS设置" |
| **提交时网络中断**| 点击提交后，网络断开 | ① App应缓存用户填写的数据；<br>② 网络恢复后，提示用户是否重新提交。| "网络连接已断开，您的报告已保存。网络恢复后将提示您重新提交。"|
| **任务已被取消/重分配**| 网格员处理一个已被主管取消的任务 | 调用任何与该任务相关的API时，后端返回`404 Not Found`或`409 Conflict` | 详情页提示"该任务已被取消或重新分配"，并引导用户返回列表页 |

## 7. 界面设计要求

### 7.1 任务列表页面
- **布局**: 采用卡片列表形式，每个卡片代表一个任务。
- **卡片内容**:
    - 左上角用不同颜色的标签标示优先级（`高`-红色, `中`-橙色, `低`-蓝色）。
    - 显示反馈`标题`和`文字地址`。
    - 右下角显示任务当前状态（如`待接受`、`处理中`）。
- **交互**: 
    - 点击卡片进入任务详情页。
    - 列表应支持**下拉刷新**功能。
    - 页面右上角提供一个"主动上报"的浮动按钮。

### 7.2 任务详情页面
- **顶部**: 清晰展示任务的`标题`、`详细描述`、`污染类型`、`严重等级`以及公众提交的`现场照片`（支持点击放大）。
- **中部 (地图)**:
    - 内嵌一个简化的网格地图组件。
    - 在地图上用不同图标标示出**网格员当前位置**和**目标任务位置**。
    - 自动规划并高亮显示从起点到终点的**最优路径**（A*算法结果），路径需能绕开障碍网格。
    - 地图右下角应提供"重新定位"和"重新规划路径"的按钮。
- **底部 (操作区)**:
    - **状态: ASSIGNED**: 根据业务规则显示"接受"和"拒绝"按钮。
    - **状态: IN_PROGRESS**: 显示一个"提交报告"按钮。点击后，弹出一个包含AQI数据表单的对话框。
    - **状态: SUBMITTED / COMPLETED**: 不显示任何操作按钮，仅展示任务信息和已提交的报告。
- **AQI数据提交表单 (弹窗)**:
    - 包含`PM2.5`, `PM10`, `SO2`, `NO2`, `CO`, `O3`等数值输入框。
    - 还有一个可选的`备注`多行文本框。
    - 有一个"确认提交"按钮，点击后显示加载状态，成功后关闭弹窗并自动刷新任务详情页的状态。

### 7.3 主动上报页面
- 页面核心是一个地图，自动定位到网格员当前位置。
- 地图下方是一个简化的AQI数据提交表单，允许网格员直接填写数据并提交。
- 提交成功后显示成功提示，并返回到主界面。