# EMS 后端 API 文档 (v3.0)

本文档为EMS（环境监控系统）后端API提供了全面的接口说明。所有接口均基于RESTful设计原则，使用JSON格式进行数据交换，并通过JWT进行认证授权。

**基础URL**: `http://localhost:8080`

---

## 1. 认证模块 (`/api/auth`)

负责处理用户身份验证、注册、登出和密码管理等所有认证相关操作。

### 1.1 用户登录

- **功能**: 用户通过邮箱和密码登录，成功后返回JWT令牌及用户信息。
- **URL**: `/api/auth/login`
- **方法**: `POST`
- **请求体** (`LoginRequest`):
  ```json
  {
    "email": "admin@example.com",
    "password": "password123"
  }
  ```
- **成功响应** (`200 OK`, `JwtAuthenticationResponse`):
  ```json
  {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "name": "Admin User",
      "email": "admin@example.com",
      "role": "ADMIN"
    }
  }
  ```
- **失败响应**: `401 Unauthorized` (凭证无效)

### 1.2 用户注册

- **功能**: 使用提供的用户信息和验证码创建新用户账户。
- **URL**: `/api/auth/signup`
- **方法**: `POST`
- **请求体** (`SignUpRequest`):
  ```json
  {
    "name": "New User",
    "email": "newuser@example.com",
    "password": "password123",
    "code": "123456" 
  }
  ```
- **成功响应**: `201 Created`
- **失败响应**: `400 Bad Request` (验证码错误、邮箱已存在等)

### 1.3 用户登出

- **功能**: 服务端记录用户登出操作。
- **URL**: `/api/auth/logout`
- **方法**: `POST`
- **认证**: 需要有效的JWT令牌
- **成功响应**: `200 OK`

### 1.4 发送注册验证码

- **功能**: 向指定邮箱发送用于账号注册的验证码。
- **URL**: `/api/auth/send-verification-code`
- **方法**: `POST`
- **请求参数**: 
  - `email` (string, `query`): 接收验证码的邮箱地址。
- **成功响应**: `200 OK`
- **失败响应**: `400 Bad Request` (邮箱格式不正确)

### 1.5 发送密码重置验证码

- **功能**: 向指定邮箱发送用于重置密码的验证码。
- **URL**: `/api/auth/send-password-reset-code`
- **方法**: `POST`
- **请求参数**: 
  - `email` (string, `query`): 注册时使用的邮箱地址。
- **成功响应**: `200 OK`

### 1.6 使用验证码重置密码

- **功能**: 校验验证码并重置为新密码。
- **URL**: `/api/auth/reset-password-with-code`
- **方法**: `POST`
- **请求体** (`PasswordResetWithCodeDto`):
  ```json
  {
    "email": "user@example.com",
    "code": "654321",
    "newPassword": "newSecurePassword456"
  }
  ```
- **成功响应**: `200 OK`
- **失败响应**: `400 Bad Request` (验证码无效或密码不符合要求)

---

## 2. 仪表盘模块 (`/api/dashboard`)

提供决策支持的各类统计和可视化数据。所有端点都需要 `DECISION_MAKER` 或 `ADMIN` 角色权限，特殊权限会单独注明。

### 2.1 核心统计数据

- **功能**: 获取仪表盘的核心统计数据，如总任务数、待处理反馈数等。
- **URL**: `/api/dashboard/stats`
- **方法**: `GET`
- **成功响应** (`200 OK`): `DashboardStatsDTO`

### 2.2 报告与分析

#### AQI等级分布
- **功能**: 获取AQI（空气质量指数）在不同等级下的分布情况。
- **URL**: `/api/dashboard/reports/aqi-distribution`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<AqiDistributionDTO>`

#### 月度超标趋势
- **功能**: 获取过去几个月内环境指标超标事件的趋势。
- **URL**: `/api/dashboard/reports/monthly-exceedance-trend`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<TrendDataPointDTO>`

#### 网格覆盖情况
- **功能**: 按城市统计网格的覆盖率和状态。
- **URL**: `/api/dashboard/reports/grid-coverage`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<GridCoverageDTO>`

#### 污染物统计
- **功能**: 获取主要污染物的统计数据报告。
- **URL**: `/api/dashboard/reports/pollution-stats`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<PollutionStatsDTO>`

#### 任务完成情况
- **功能**: 统计任务的整体完成率和状态分布。
- **URL**: `/api/dashboard/reports/task-completion-stats`
- **方法**: `GET`
- **成功响应** (`200 OK`): `TaskStatsDTO`

#### 污染物月度趋势
- **功能**: 获取不同污染物类型的月度变化趋势。
- **URL**: `/api/dashboard/reports/pollutant-monthly-trends`
- **方法**: `GET`
- **成功响应** (`200 OK`): `Map<String, List<TrendDataPointDTO>>`

### 2.3 地图数据

#### 反馈热力图
- **功能**: 获取用于在地图上展示反馈问题地理分布的热力图数据。
- **URL**: `/api/dashboard/map/heatmap`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<HeatmapPointDTO>`

#### AQI热力图
- **功能**: 获取用于在地图上展示AQI指数地理分布的热力图数据。
- **URL**: `/api/dashboard/map/aqi-heatmap`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<AqiHeatmapPointDTO>`

### 2.4 污染物阈值管理

#### 获取所有阈值
- **功能**: 获取所有污染物的阈值设置。
- **URL**: `/api/dashboard/thresholds`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<PollutantThresholdDTO>`

#### 获取指定污染物阈值
- **功能**: 根据污染物名称获取其特定的阈值设置。
- **URL**: `/api/dashboard/thresholds/{pollutantName}`
- **方法**: `GET`
- **URL参数**: `pollutantName` (string)
- **成功响应** (`200 OK`): `PollutantThresholdDTO`

#### 保存阈值
- **功能**: 创建或更新一个污染物的阈值设置。
- **权限**: **`ADMIN`**
- **URL**: `/api/dashboard/thresholds`
- **方法**: `POST`
- **请求体** (`PollutantThresholdDTO`):
  ```json
  {
    "pollutantName": "PM2.5",
    "goodThreshold": 35,
    "moderateThreshold": 75,
    "unhealthyThreshold": 115
  }
  ```
- **成功响应** (`200 OK`): `PollutantThresholdDTO` (已保存的数据)

---

## 3. 反馈模块 (`/api/feedback`)

处理公众和用户的环境问题反馈，包括提交、查询、统计和处理。

### 3.1 提交反馈

- **功能**: 已认证用户提交环境问题反馈，可附带文件。
- **权限**: **`isAuthenticated()`** (任何已认证用户)
- **URL**: `/api/feedback/submit`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **请求部分**:
  - `feedback` (JSON, `FeedbackSubmissionRequest`):
    ```json
    {
      "title": "River Pollution",
      "description": "The river near downtown is heavily polluted.",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "pollutionType": "WATER",
      "severityLevel": "HIGH"
    }
    ```
  - `files` (File[], optional): (可选) 上传的图片或视频文件。
- **成功响应** (`201 Created`): `Feedback` (包含ID的已创建反馈对象)

### 3.2 获取反馈列表 (分页+过滤)

- **功能**: 根据多种条件组合查询反馈列表，支持分页。
- **权限**: **`isAuthenticated()`**
- **URL**: `/api/feedback`
- **方法**: `GET`
- **请求参数**:
  - `page` (int, optional): 页码 (从0开始)
  - `size` (int, optional): 每页数量
  - `sort` (string, optional): 排序字段，如 `createdAt,desc`
  - `status` (string, optional): 状态 (e.g., `PENDING_REVIEW`, `PROCESSED`)
  - `pollutionType` (string, optional): 污染类型 (e.g., `AIR`, `WATER`)
  - `severityLevel` (string, optional): 严重程度 (e.g., `LOW`, `MEDIUM`)
  - `cityName` (string, optional): 城市名称
  - `districtName` (string, optional): 区县名称
  - `startDate` (string, optional): 开始日期 (格式: `YYYY-MM-DD`)
  - `endDate` (string, optional): 结束日期 (格式: `YYYY-MM-DD`)
  - `keyword` (string, optional): 标题或描述中的关键词
- **成功响应** (`200 OK`): `Page<FeedbackResponseDTO>` (分页的反馈数据)

### 3.3 获取反馈详情

- **功能**: 根据ID获取单个反馈的详细信息。
- **权限**: **`ADMIN`**, **`SUPERVISOR`**, **`DECISION_MAKER`**
- **URL**: `/api/feedback/{id}`
- **方法**: `GET`
- **URL参数**: `id` (long)
- **成功响应** (`200 OK`): `FeedbackResponseDTO`

### 3.4 获取反馈统计

- **功能**: 获取当前用户的反馈统计数据 (例如，不同状态下的反馈数量)。
- **权限**: **`isAuthenticated()`**
- **URL**: `/api/feedback/stats`
- **方法**: `GET`
- **成功响应** (`200 OK`): `FeedbackStatsResponse`

### 3.5 处理反馈 (审批)

- **功能**: 主管或管理员对反馈进行处理，例如审批通过、驳回等。
- **权限**: **`ADMIN`**, **`SUPERVISOR`**
- **URL**: `/api/feedback/{id}/process`
- **方法**: `POST`
- **URL参数**: `id` (long)
- **请求体** (`ProcessFeedbackRequest`):
  ```json
  {
    "newStatus": "PROCESSED",
    "remarks": "Feedback has been verified and assigned."
  }
  ```
- **成功响应** (`200 OK`): `FeedbackResponseDTO` (更新后的反馈对象)

---

## 4. 公共接口模块 (`/api/public`)

无需认证即可访问的接口，主要用于公众参与。

### 4.1 提交公共反馈

- **功能**: 公众用户提交环境问题反馈，可附带文件。
- **URL**: `/api/public/feedback`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **请求部分**:
  - `feedback` (JSON, `PublicFeedbackRequest`):
    ```json
    {
      "title": "Noise Complaint",
      "description": "Loud construction noise at night.",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "contactInfo": "anonymous@example.com"
    }
    ```
  - `files` (File[], optional): 上传的图片或视频等附件。
- **成功响应** (`201 Created`): `Feedback` (包含ID的已创建反馈对象)

---

## 5. 文件模块 (`/api`)

处理系统中文件的访问、下载和预览。

### 5.1 文件下载/预览

- **功能**: 根据文件名获取文件资源，既可用于下载，也可用于浏览器内联预览。
- **URL**: 
  - `/api/files/{filename}`
  - `/api/view/{filename}`
- **方法**: `GET`
- **URL参数**:
  - `filename` (string): 完整的文件名，包含扩展名 (例如, `image.png`, `report.pdf`)。
- **成功响应** (`200 OK`):
  - **Content-Type**: 根据文件类型动态设置 (e.g., `image/jpeg`, `application/pdf`)。
  - **Content-Disposition**: `inline`，建议浏览器内联显示。
  - **Body**: 文件内容的二进制流。
- **失败响应**: `404 Not Found` (文件不存在)

---

## 6. 网格管理模块 (`/api/grids`)

负责环境监督网格的查询、更新以及网格员的分配管理。

### 6.1 获取所有网格

- **功能**: 获取系统中所有的网格数据列表。
- **权限**: `ADMIN`, `DECISION_MAKER`, `GRID_WORKER`
- **URL**: `/api/grids`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<Grid>`

### 6.2 更新网格信息

- **功能**: 更新指定ID的网格信息，例如修改其负责人或状态。
- **权限**: `ADMIN`
- **URL**: `/api/grids/{id}`
- **方法**: `PATCH`
- **URL参数**: `id` (long)
- **请求体** (`GridUpdateRequest`):
  ```json
  {
    "status": "ACTIVE",
    "notes": "This grid is now actively monitored."
  }
  ```
- **成功响应** (`200 OK`): `Grid` (更新后的网格对象)

### 6.3 获取网格覆盖率统计

- **功能**: 按城市统计网格的覆盖情况。
- **权限**: `ADMIN`
- **URL**: `/api/grids/coverage`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<GridCoverageDTO>`

### 6.4 分配/解分配网格员 (通过网格ID)

#### 分配网格员
- **功能**: 将一个网格员分配到指定的网格。
- **权限**: `ADMIN`
- **URL**: `/api/grids/{gridId}/assign`
- **方法**: `POST`
- **URL参数**: `gridId` (long)
- **请求体**:
  ```json
  {
    "userId": 123 
  }
  ```
- **成功响应** (`200 OK`)

#### 解分配网格员
- **功能**: 将一个网格员从指定的网格中移除。
- **权限**: `ADMIN`
- **URL**: `/api/grids/{gridId}/unassign`
- **方法**: `POST`
- **URL参数**: `gridId` (long)
- **成功响应** (`200 OK`)

### 6.5 分配/解分配网格员 (通过坐标)

#### 分配网格员
- **功能**: 将一个网格员分配到指定坐标的网格。
- **权限**: `ADMIN`, `GRID_WORKER`
- **URL**: `/api/grids/coordinates/{gridX}/{gridY}/assign`
- **方法**: `POST`
- **URL参数**: 
  - `gridX` (int)
  - `gridY` (int)
- **请求体**:
  ```json
  {
    "userId": 123 
  }
  ```
- **成功响应** (`200 OK`)

#### 解分配网格员
- **功能**: 将一个网格员从指定坐标的网格中移除。
- **权限**: `ADMIN`, `GRID_WORKER`
- **URL**: `/api/grids/coordinates/{gridX}/{gridY}/unassign`
- **方法**: `POST`
- **URL参数**: 
  - `gridX` (int)
  - `gridY` (int)
- **成功响应** (`200 OK`)

---

## 7. 人员管理模块 (`/api/personnel`)

负责系统中所有用户账户的创建、查询、更新和删除 (CRUD)。

### 7.1 获取用户列表 (分页)

- **功能**: 获取系统中的用户列表，支持按角色和姓名进行筛选，并提供分页。
- **权限**: `ADMIN`, `GRID_WORKER`
- **URL**: `/api/personnel/users`
- **方法**: `GET`
- **请求参数**:
  - `role` (string, optional): 角色名称 (e.g., `ADMIN`, `GRID_WORKER`)
  - `name` (string, optional): 用户姓名 (模糊匹配)
  - `page` (int, optional): 页码
  - `size` (int, optional): 每页数量
- **成功响应** (`200 OK`): `PageDTO<UserAccount>`

### 7.2 创建新用户

- **功能**: 创建一个新的用户账户。
- **权限**: `ADMIN`
- **URL**: `/api/personnel/users`
- **方法**: `POST`
- **请求体** (`UserCreationRequest`):
  ```json
  {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "password": "strongPassword123",
    "role": "GRID_WORKER"
  }
  ```
- **成功响应** (`201 Created`): `UserAccount`

### 7.3 获取用户详情

- **功能**: 根据ID获取单个用户的详细信息。
- **权限**: `ADMIN`
- **URL**: `/api/personnel/users/{userId}`
- **方法**: `GET`
- **URL参数**: `userId` (long)
- **成功响应** (`200 OK`): `UserAccount` (密码字段为空)

### 7.4 更新用户信息

- **功能**: 更新指定用户的信息（例如姓名、邮箱，但不包括角色）。
- **权限**: `ADMIN`
- **URL**: `/api/personnel/users/{userId}`
- **方法**: `PATCH`
- **URL参数**: `userId` (long)
- **请求体** (`UserUpdateRequest`):
  ```json
  {
    "name": "Johnathan Doe",
    "email": "johnathan.doe@example.com"
  }
  ```
- **成功响应** (`200 OK`): `UserAccount`

### 7.5 更新用户角色

- **功能**: 单独更新用户的角色。
- **权限**: `ADMIN`
- **URL**: `/api/personnel/users/{userId}/role`
- **方法**: `PUT`
- **URL参数**: `userId` (long)
- **请求体** (`UserRoleUpdateRequest`):
  ```json
  {
    "role": "SUPERVISOR"
  }
  ```
- **成功响应** (`200 OK`): `UserAccount` (密码字段为空)

### 7.6 删除用户

- **功能**: 从系统中永久删除一个用户。
- **权限**: `ADMIN`
- **URL**: `/api/personnel/users/{userId}`
- **方法**: `DELETE`
- **URL参数**: `userId` (long)
- **成功响应** (`204 No Content`)

---

## 8. 网格员任务模块 (`/api/worker`)

专为网格员 (`GRID_WORKER`) 提供的任务管理接口。

### 8.1 获取我的任务列表

- **功能**: 获取分配给当前登录网格员的任务列表，支持按状态筛选和分页。
- **权限**: `GRID_WORKER`
- **URL**: `/api/worker`
- **方法**: `GET`
- **请求参数**:
  - `status` (string, optional): 任务状态 (e.g., `ASSIGNED`, `IN_PROGRESS`, `COMPLETED`)
  - `page` (int, optional): 页码
  - `size` (int, optional): 每页数量
- **成功响应** (`200 OK`): `Page<TaskSummaryDTO>`

### 8.2 获取任务详情

- **功能**: 获取单个任务的详细信息。
- **权限**: `GRID_WORKER`
- **URL**: `/api/worker/{taskId}`
- **方法**: `GET`
- **URL参数**: `taskId` (long)
- **成功响应** (`200 OK`): `TaskDetailDTO`

### 8.3 接受任务

- **功能**: 网格员接受一个已分配给自己的任务。
- **权限**: `GRID_WORKER`
- **URL**: `/api/worker/{taskId}/accept`
- **方法**: `POST`
- **URL参数**: `taskId` (long)
- **成功响应** (`200 OK`): `TaskSummaryDTO` (更新后的任务摘要)

### 8.4 提交任务完成情况

- **功能**: 网格员提交任务的完成情况，可附带文字说明和文件。
- **权限**: `GRID_WORKER`
- **URL**: `/api/worker/{taskId}/submit`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **URL参数**: `taskId` (long)
- **请求部分**:
  - `comments` (string): 任务完成情况的文字说明。
  - `files` (File[], optional): (可选) 相关的证明文件或图片。
- **成功响应** (`200 OK`): `TaskSummaryDTO` (更新后的任务摘要)

---

## 9. 地图与寻路模块 (`/api/map`, `/api/pathfinding`)

提供地图数据管理和基于A*算法的路径规划功能。

### 9.1 地图管理 (`/api/map`)

#### 获取完整地图网格
- **功能**: 获取用于渲染前端地图的完整网格数据。
- **URL**: `/api/map/grid`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<MapGrid>`

#### 创建或更新网格单元
- **功能**: 创建或更新单个网格单元的信息，如设置障碍物。
- **URL**: `/api/map/grid`
- **方法**: `POST`
- **请求体** (`MapGrid`):
  ```json
  {
    "x": 10,
    "y": 15,
    "obstacle": true,
    "terrainType": "water"
  }
  ```
- **成功响应** (`200 OK`): `MapGrid` (已保存的网格单元)

#### 初始化地图
- **功能**: 清空并重新生成指定大小的地图网格（主要用于开发和测试）。
- **URL**: `/api/map/initialize`
- **方法**: `POST`
- **请求参数**:
  - `width` (int, optional, default=20)
  - `height` (int, optional, default=20)
- **成功响应** (`200 OK`): `String` (例如, "Initialized a 20x20 map.")

### 9.2 路径规划 (`/api/pathfinding`)

#### 查找路径
- **功能**: 使用A*算法计算两点之间的最短路径，会避开障碍物。
- **URL**: `/api/pathfinding/find`
- **方法**: `POST`
- **请求体** (`PathfindingRequest`):
  ```json
  {
    "startX": 0,
    "startY": 0,
    "endX": 18,
    "endY": 18
  }
  ```
- **成功响应** (`200 OK`): `List<Point>` (路径点坐标列表，若无路径则为空列表)

---

## 10. 个人资料模块 (`/api/me`)

处理与当前登录用户个人账户相关的操作。

### 10.1 获取我的反馈历史

- **功能**: 获取当前登录用户提交过的所有反馈记录，支持分页。
- **权限**: `isAuthenticated()` (任何已认证用户)
- **URL**: `/api/me/feedback`
- **方法**: `GET`
- **请求参数**:
  - `page` (int, optional): 页码
  - `size` (int, optional): 每页数量
- **成功响应** (`200 OK`): `Page<UserFeedbackSummaryDTO>`

---

## 11. 主管审核模块 (`/api/supervisor`)

专为主管 (`SUPERVISOR`) 和管理员 (`ADMIN`) 提供的反馈审核接口。

### 11.1 获取待审核列表

- **功能**: 获取所有状态为"待审核"的反馈列表。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/supervisor/reviews`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<Feedback>`

### 11.2 批准反馈

- **功能**: 将指定ID的反馈状态变更为"已批准"(通常意味着后续可被分配任务)。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/supervisor/reviews/{feedbackId}/approve`
- **方法**: `POST`
- **URL参数**: `feedbackId` (long)
- **成功响应** (`200 OK`)

### 11.3 拒绝反馈

- **功能**: 拒绝一个反馈，并记录拒绝理由。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/supervisor/reviews/{feedbackId}/reject`
- **方法**: `POST`
- **URL参数**: `feedbackId` (long)
- **请求体** (`RejectFeedbackRequest`):
  ```json
  {
    "reason": "Insufficient evidence provided."
  }
  ```
- **成功响应** (`200 OK`)

---

## 12. 任务分配模块 (`/api/tasks`)

专为主管 (`SUPERVISOR`) 和管理员 (`ADMIN`) 提供的、将已审核通过的反馈分配为具体任务的接口。

### 12.1 获取未分配的任务

- **功能**: 获取所有已批准但尚未分配给任何网格员的反馈列表。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/tasks/unassigned`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<Feedback>`

### 12.2 获取可用的网格员

- **功能**: 获取系统中所有角色为 `GRID_WORKER` 的用户列表，用于任务分配。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/tasks/grid-workers`
- **方法**: `GET`
- **成功响应** (`200 OK`): `List<UserAccount>`

### 12.3 分配任务

- **功能**: 将一个反馈分配给一个网格员，从而创建一个新任务。
- **权限**: `SUPERVISOR`, `ADMIN`
- **URL**: `/api/tasks/assign`
- **方法**: `POST`
- **请求体** (`AssignmentRequest`):
  ```json
  {
    "feedbackId": 10,
    "assigneeId": 123
  }
  ```
- **成功响应** (`200 OK`): `Assignment` (创建的任务分配记录)

---

## 13. 任务管理模块 (`/api/management/tasks`)