admin/Environment-Monitoring-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2ec68c672e21dc8fd64a2e0780a6c7823adce7f7
Environment-Monitoring-System/Design/API测试文档.md
ChuXun 4ce487588a 1
2025-10-19 20:31:01 +08:00

20 KiB
Raw Blame History

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): 
    {
  "email": "admin@example.com",
  "password": "password123"
}
  • 成功响应 (200 OK, JwtAuthenticationResponse): 
    {
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "name": "Admin User",
    "email": "admin@example.com",
    "role": "ADMIN"
  }
}
  • 失败响应: 401 Unauthorized (凭证无效)

1.2 用户注册

  • 功能: 使用提供的用户信息和验证码创建新用户账户。
  • URL: /api/auth/signup
  • 方法: POST
  • 请求体 (SignUpRequest): 
    {
  "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): 
    {
  "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): 
    {
  "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): 
      {
  "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): 
    {
  "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): 
      {
  "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): 
    {
  "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)
  • 请求体: 
    {
  "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)
  • 请求体: 
    {
  "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): 
    {
  "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): 
    {
  "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): 
    {
  "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): 
    {
  "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): 
    {
  "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): 
    {
  "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): 
    {
  "feedbackId": 10,
  "assigneeId": 123
}
  • 成功响应 (200 OK): Assignment (创建的任务分配记录)

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

Reference in New Issue View Git Blame Copy Permalink