696 lines
20 KiB
Markdown
696 lines
20 KiB
Markdown
# 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`) |