463 lines
20 KiB
Markdown
463 lines
20 KiB
Markdown
# EMS后端系统技术图表文档
|
||
|
||
## 项目概述
|
||
|
||
环境管理系统(EMS)后端是一个基于Spring Boot的Java应用程序，用于处理环境问题反馈、任务分配和用户管理。系统采用分层架构，包含控制器、服务、仓库和模型层。
|
||
|
||
## 1. 系统时序图
|
||
|
||
### 1.1 用户登录认证流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant AuthController as 认证控制器
|
||
participant AuthService as 认证服务
|
||
participant UserRepository as 用户仓库
|
||
participant JwtUtil as JWT工具
|
||
participant Database as JSON持久化存储
|
||
|
||
User->>AuthController: POST /api/auth/login
|
||
AuthController->>AuthService: signIn(LoginRequest)
|
||
AuthService->>UserRepository: findByEmailOrPhone()
|
||
UserRepository->>Database: 查询用户信息
|
||
Database-->>UserRepository: 返回用户数据
|
||
UserRepository-->>AuthService: 返回UserAccount
|
||
AuthService->>AuthService: 验证密码
|
||
AuthService->>JwtUtil: 生成JWT令牌
|
||
JwtUtil-->>AuthService: 返回JWT
|
||
AuthService-->>AuthController: JwtAuthenticationResponse
|
||
AuthController-->>User: 返回JWT令牌
|
||
```
|
||
|
||
### 1.2 反馈提交处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant FeedbackController as 反馈控制器
|
||
participant FeedbackService as 反馈服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant AIService as AI服务
|
||
participant EventPublisher as 事件发布器
|
||
participant Database as JSON持久化存储
|
||
|
||
User->>FeedbackController: POST /api/feedback/submit
|
||
FeedbackController->>FeedbackService: submitFeedback(request, files)
|
||
FeedbackService->>FeedbackService: 生成事件ID
|
||
FeedbackService->>FeedbackRepository: save(feedback)
|
||
FeedbackRepository->>Database: 保存反馈数据
|
||
Database-->>FeedbackRepository: 返回保存结果
|
||
FeedbackRepository-->>FeedbackService: 返回Feedback实体
|
||
FeedbackService->>EventPublisher: 发布反馈创建事件
|
||
EventPublisher->>AIService: 触发AI处理
|
||
AIService->>AIService: 分析反馈内容
|
||
FeedbackService-->>FeedbackController: 返回Feedback
|
||
FeedbackController-->>User: 201 Created
|
||
```
|
||
|
||
### 1.3 任务分配流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Supervisor as 主管
|
||
participant TaskController as 任务控制器
|
||
participant TaskService as 任务服务
|
||
participant AssignmentService as 分配服务
|
||
participant UserRepository as 用户仓库
|
||
participant TaskRepository as 任务仓库
|
||
participant GridWorker as 网格工作人员
|
||
|
||
Supervisor->>TaskController: POST /api/tasks/assign
|
||
TaskController->>TaskService: assignTask(taskId, workerId)
|
||
TaskService->>UserRepository: findById(workerId)
|
||
UserRepository-->>TaskService: 返回GridWorker
|
||
TaskService->>AssignmentService: createAssignment()
|
||
AssignmentService->>TaskRepository: updateTaskStatus()
|
||
TaskRepository-->>AssignmentService: 更新成功
|
||
AssignmentService-->>TaskService: Assignment创建成功
|
||
TaskService->>TaskService: 发送通知给工作人员
|
||
TaskService-->>TaskController: 分配成功
|
||
TaskController-->>Supervisor: 200 OK
|
||
Note over GridWorker: 接收任务通知
|
||
```
|
||
|
||
### 1.4 主管审核反馈并创建任务
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Supervisor as 主管
|
||
participant FeedbackController as 反馈控制器
|
||
participant FeedbackService as 反馈服务
|
||
participant TaskService as 任务服务
|
||
participant TaskRepository as 任务仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
Supervisor->>FeedbackController: POST /api/feedback/{id}/process
|
||
FeedbackController->>FeedbackService: processFeedback(feedbackId, request)
|
||
FeedbackService->>FeedbackService: 验证反馈状态和主管权限
|
||
alt 同意反馈并创建任务
|
||
FeedbackService->>TaskService: createTaskFromFeedback(feedback)
|
||
TaskService->>TaskRepository: save(task)
|
||
TaskRepository->>Database: 保存新任务
|
||
Database-->>TaskRepository: 返回保存的任务
|
||
TaskRepository-->>TaskService: 返回Task实体
|
||
TaskService->>FeedbackService: 更新反馈状态为PENDING_ASSIGNMENT
|
||
FeedbackService-->>FeedbackController: 返回处理结果
|
||
else 拒绝反馈
|
||
FeedbackService->>FeedbackService: 更新反馈状态为REJECTED
|
||
FeedbackService-->>FeedbackController: 返回处理结果
|
||
end
|
||
FeedbackController-->>Supervisor: 200 OK
|
||
```
|
||
|
||
### 1.5 用户密码重置流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant AuthController as 认证控制器
|
||
participant AuthService as 认证服务
|
||
participant VerificationCodeService as 验证码服务
|
||
participant MailService as 邮件服务
|
||
participant UserRepository as 用户仓库
|
||
|
||
User->>AuthController: POST /api/auth/send-password-reset-code (email)
|
||
AuthController->>AuthService: requestPasswordReset(email)
|
||
AuthService->>UserRepository: findByEmail(email)
|
||
UserRepository-->>AuthService: 返回UserAccount
|
||
AuthService->>VerificationCodeService: createAndSendPasswordResetCode(user)
|
||
VerificationCodeService->>MailService: sendEmail(to, subject, content)
|
||
MailService-->>VerificationCodeService: 邮件发送成功
|
||
VerificationCodeService-->>AuthService: 验证码发送成功
|
||
AuthService-->>AuthController: 200 OK
|
||
AuthController-->>User: 提示验证码已发送
|
||
|
||
User->>AuthController: POST /api/auth/reset-password-with-code (email, code, newPassword)
|
||
AuthController->>AuthService: resetPasswordWithCode(email, code, newPassword)
|
||
AuthService->>VerificationCodeService: validateCode(email, code)
|
||
VerificationCodeService-->>AuthService: 验证码有效
|
||
AuthService->>UserRepository: save(user) with new password
|
||
UserRepository-->>AuthService: 用户密码更新成功
|
||
AuthService-->>AuthController: 200 OK
|
||
AuthController-->>User: 密码重置成功
|
||
```
|
||
|
||
### 1.6 用户获取自己的反馈历史
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant ProfileController as 个人资料控制器
|
||
participant UserFeedbackService as 用户反馈服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
User->>ProfileController: GET /api/me/feedback
|
||
ProfileController->>UserFeedbackService: getFeedbackHistoryByUserId(userId, pageable)
|
||
UserFeedbackService->>FeedbackRepository: findBySubmitterId(userId, pageable)
|
||
FeedbackRepository->>Database: 查询用户反馈数据
|
||
Database-->>FeedbackRepository: 返回反馈数据
|
||
FeedbackRepository-->>UserFeedbackService: 返回Page<Feedback>
|
||
UserFeedbackService->>UserFeedbackService: 转换为UserFeedbackSummaryDTO列表
|
||
UserFeedbackService-->>ProfileController: 返回Page<UserFeedbackSummaryDTO>
|
||
ProfileController-->>User: 返回反馈历史列表
|
||
```
|
||
|
||
### 1.7 网格员获取和管理任务
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant GridWorker as 网格员
|
||
participant GridWorkerTaskController as 网格员任务控制器
|
||
participant GridWorkerTaskService as 网格员任务服务
|
||
participant TaskRepository as 任务仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
alt 获取任务列表
|
||
GridWorker->>GridWorkerTaskController: GET /api/worker/tasks
|
||
GridWorkerTaskController->>GridWorkerTaskService: getAssignedTasks(workerId, status, pageable)
|
||
GridWorkerTaskService->>TaskRepository: findByAssigneeIdAndStatus(workerId, status, pageable)
|
||
TaskRepository->>Database: 查询任务数据
|
||
Database-->>TaskRepository: 返回任务数据
|
||
TaskRepository-->>GridWorkerTaskService: 返回Page<Task>
|
||
GridWorkerTaskService->>GridWorkerTaskService: 转换为TaskSummaryDTO列表
|
||
GridWorkerTaskService-->>GridWorkerTaskController: 返回Page<TaskSummaryDTO>
|
||
GridWorkerTaskController-->>GridWorker: 返回任务列表
|
||
end
|
||
|
||
alt 接受任务
|
||
GridWorker->>GridWorkerTaskController: POST /api/worker/tasks/{taskId}/accept
|
||
GridWorkerTaskController->>GridWorkerTaskService: acceptTask(taskId, workerId)
|
||
GridWorkerTaskService->>TaskRepository: findById(taskId)
|
||
TaskRepository->>Database: 查询任务
|
||
Database-->>TaskRepository: 返回任务
|
||
TaskRepository-->>GridWorkerTaskService: 返回Task
|
||
GridWorkerTaskService->>GridWorkerTaskService: 验证任务状态并更新为ACCEPTED
|
||
GridWorkerTaskService->>TaskRepository: save(task)
|
||
TaskRepository->>Database: 更新任务状态
|
||
Database-->>TaskRepository: 返回更新后的任务
|
||
TaskRepository-->>GridWorkerTaskService: 返回更新后的Task
|
||
GridWorkerTaskService->>GridWorkerTaskService: 转换为TaskSummaryDTO
|
||
GridWorkerTaskService-->>GridWorkerTaskController: 返回TaskSummaryDTO
|
||
GridWorkerTaskController-->>GridWorker: 返回更新后的任务摘要
|
||
end
|
||
|
||
alt 提交任务
|
||
GridWorker->>GridWorkerTaskController: POST /api/worker/tasks/{taskId}/submit
|
||
GridWorkerTaskController->>GridWorkerTaskService: submitTaskCompletion(taskId, workerId, request, files)
|
||
GridWorkerTaskService->>TaskRepository: findById(taskId)
|
||
TaskRepository->>Database: 查询任务
|
||
Database-->>TaskRepository: 返回任务
|
||
TaskRepository-->>GridWorkerTaskService: 返回Task
|
||
GridWorkerTaskService->>GridWorkerTaskService: 验证并更新任务状态为COMPLETED
|
||
GridWorkerTaskService->>GridWorkerTaskService: (如果存在)处理附件上传
|
||
GridWorkerTaskService->>TaskRepository: save(task)
|
||
TaskRepository->>Database: 更新任务
|
||
Database-->>TaskRepository: 返回更新后的任务
|
||
TaskRepository-->>GridWorkerTaskService: 返回更新后的Task
|
||
GridWorkerTaskService->>GridWorkerTaskService: 转换为TaskSummaryDTO
|
||
GridWorkerTaskService-->>GridWorkerTaskController: 返回TaskSummaryDTO
|
||
GridWorkerTaskController-->>GridWorker: 返回更新后的任务摘要
|
||
end
|
||
```
|
||
|
||
### 1.8 决策者获取仪表盘数据
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant DecisionMaker as 决策者
|
||
participant DashboardController as 仪表盘控制器
|
||
participant DashboardService as 仪表盘服务
|
||
participant variousRepositories as 各类仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
alt 获取核心统计数据
|
||
DecisionMaker->>DashboardController: GET /api/dashboard/stats
|
||
DashboardController->>DashboardService: getDashboardStats()
|
||
DashboardService->>variousRepositories: (并行)调用多个仓库方法获取数据
|
||
variousRepositories->>Database: 查询统计数据
|
||
Database-->>variousRepositories: 返回数据
|
||
variousRepositories-->>DashboardService: 返回统计结果
|
||
DashboardService->>DashboardService: 聚合数据为DashboardStatsDTO
|
||
DashboardService-->>DashboardController: 返回DashboardStatsDTO
|
||
DashboardController-->>DecisionMaker: 返回核心统计数据
|
||
end
|
||
|
||
alt 获取AQI分布
|
||
DecisionMaker->>DashboardController: GET /api/dashboard/reports/aqi-distribution
|
||
DashboardController->>DashboardService: getAqiDistribution()
|
||
DashboardService->>variousRepositories: 查询AQI数据并分组统计
|
||
variousRepositories->>Database: 查询AQI数据
|
||
Database-->>variousRepositories: 返回数据
|
||
variousRepositories-->>DashboardService: 返回统计结果
|
||
DashboardService->>DashboardService: 转换为AqiDistributionDTO列表
|
||
DashboardService-->>DashboardController: 返回List<AqiDistributionDTO>
|
||
DashboardController-->>DecisionMaker: 返回AQI等级分布数据
|
||
end
|
||
|
||
alt 获取热力图数据
|
||
DecisionMaker->>DashboardController: GET /api/dashboard/map/heatmap
|
||
DashboardController->>DashboardService: getHeatmapData()
|
||
DashboardService->>variousRepositories: 查询反馈的地理位置数据
|
||
variousRepositories->>Database: 查询地理位置数据
|
||
Database-->>variousRepositories: 返回数据
|
||
variousRepositories-->>DashboardService: 返回位置数据列表
|
||
DashboardService->>DashboardService: 转换为HeatmapPointDTO列表
|
||
DashboardService-->>DashboardController: 返回List<HeatmapPointDTO>
|
||
DashboardController-->>DecisionMaker: 返回热力图数据
|
||
end
|
||
```
|
||
|
||
### 1.9 主管审核反馈
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Supervisor as 主管
|
||
participant SupervisorController as 主管控制器
|
||
participant SupervisorService as 主管服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
alt 获取待审核列表
|
||
Supervisor->>SupervisorController: GET /api/supervisor/reviews
|
||
SupervisorController->>SupervisorService: getFeedbackForReview()
|
||
SupervisorService->>FeedbackRepository: findByStatus(PENDING_REVIEW)
|
||
FeedbackRepository->>Database: 查询待审核反馈
|
||
Database-->>FeedbackRepository: 返回反馈列表
|
||
FeedbackRepository-->>SupervisorService: 返回List<Feedback>
|
||
SupervisorService-->>SupervisorController: 返回List<Feedback>
|
||
SupervisorController-->>Supervisor: 显示待审核列表
|
||
end
|
||
|
||
alt 批准反馈
|
||
Supervisor->>SupervisorController: POST /api/supervisor/reviews/{feedbackId}/approve
|
||
SupervisorController->>SupervisorService: approveFeedback(feedbackId)
|
||
SupervisorService->>FeedbackRepository: findById(feedbackId)
|
||
FeedbackRepository->>Database: 查询反馈
|
||
Database-->>FeedbackRepository: 返回反馈
|
||
FeedbackRepository-->>SupervisorService: 返回Feedback
|
||
SupervisorService->>SupervisorService: 更新反馈状态为APPROVED
|
||
SupervisorService->>FeedbackRepository: save(feedback)
|
||
TaskRepository->>Database: 更新反馈状态
|
||
Database-->>TaskRepository: 返回更新后的反馈
|
||
TaskRepository-->>SupervisorService: 返回更新后的Feedback
|
||
SupervisorService-->>SupervisorController: 返回成功响应
|
||
SupervisorController-->>Supervisor: 操作成功
|
||
end
|
||
|
||
alt 拒绝反馈
|
||
Supervisor->>SupervisorController: POST /api/supervisor/reviews/{feedbackId}/reject
|
||
SupervisorController->>SupervisorService: rejectFeedback(feedbackId, request)
|
||
SupervisorService->>FeedbackRepository: findById(feedbackId)
|
||
FeedbackRepository->>Database: 查询反馈
|
||
Database-->>FeedbackRepository: 返回反馈
|
||
FeedbackRepository-->>SupervisorService: 返回Feedback
|
||
SupervisorService->>SupervisorService: 更新反馈状态为REJECTED并记录原因
|
||
SupervisorService->>FeedbackRepository: save(feedback)
|
||
TaskRepository->>Database: 更新反馈状态
|
||
Database-->>TaskRepository: 返回更新后的反馈
|
||
TaskRepository-->>SupervisorService: 返回更新后的Feedback
|
||
SupervisorService-->>SupervisorController: 返回成功响应
|
||
SupervisorController-->>Supervisor: 操作成功
|
||
end
|
||
```
|
||
|
||
### 1.10 路径规划 (A* 寻路算法)
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant PathfindingController as 寻路控制器
|
||
participant AStarService as A*服务
|
||
participant MapData as 地图数据
|
||
|
||
User->>+PathfindingController: POST /api/pathfinding/find (起点, 终点)
|
||
PathfindingController->>+AStarService: findPath(start, end)
|
||
AStarService->>+MapData: getObstacles()
|
||
MapData-->>-AStarService: 返回障碍物信息
|
||
AStarService->>AStarService: 执行A*算法计算路径
|
||
AStarService-->>-PathfindingController: 返回计算出的路径
|
||
PathfindingController-->>-User: 200 OK (路径坐标列表)
|
||
```
|
||
|
||
### 1.11 公众提交反馈
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant FeedbackController as 反馈控制器
|
||
participant FeedbackService as 反馈服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant FileService as 文件服务
|
||
participant Database as JSON持久化存储
|
||
|
||
User->>+FeedbackController: POST /api/feedback/submit (反馈信息, 附件)
|
||
FeedbackController->>+FeedbackService: submitFeedback(request, files)
|
||
alt 包含附件
|
||
FeedbackService->>+FileService: store(files)
|
||
FileService-->>-FeedbackService: 返回文件存储路径
|
||
end
|
||
FeedbackService->>+FeedbackRepository: save(feedback)
|
||
FeedbackRepository->>+Database: INSERT INTO feedbacks
|
||
Database-->>-FeedbackRepository: 返回已保存的反馈
|
||
FeedbackRepository-->>-FeedbackService: 返回已保存的反馈
|
||
FeedbackService-->>-FeedbackController: 返回创建的反馈
|
||
FeedbackController-->>-User: 201 CREATED (反馈详情)
|
||
```
|
||
|
||
### 1.12 文件下载/预览
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant FileController as 文件控制器
|
||
participant FileStorageService as 文件存储服务
|
||
participant FileSystem as 文件系统
|
||
|
||
User->>+FileController: GET /api/files/{filename} 或 /api/view/{filename}
|
||
FileController->>+FileStorageService: loadFileAsResource(filename)
|
||
FileStorageService->>+FileSystem: 读取文件
|
||
FileSystem-->>-FileStorageService: 返回文件资源
|
||
FileStorageService-->>-FileController: 返回文件资源
|
||
FileController->>FileController: 设置HTTP响应头 (Content-Type, Content-Disposition)
|
||
FileController-->>-User: 200 OK (文件内容)
|
||
```
|
||
|
||
### 1.13 管理员分配网格员
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as 管理员
|
||
participant GridController as 网格控制器
|
||
participant UserAccountService as 用户账户服务
|
||
participant GridService as 网格服务
|
||
participant OperationLogService as 操作日志服务
|
||
participant Database as JSON持久化存储
|
||
|
||
Admin->>GridController: POST /api/grids/assign-worker (userId, gridId)
|
||
activate GridController
|
||
|
||
GridController->>UserAccountService: getUserById(userId)
|
||
activate UserAccountService
|
||
UserAccountService->>Database: 查询用户
|
||
Database-->>UserAccountService: 返回用户信息
|
||
UserAccountService-->>GridController: 返回用户
|
||
deactivate UserAccountService
|
||
|
||
alt 用户角色是网格员 (role == 'GRID_WORKER')
|
||
GridController->>GridService: assignGridToUser(userId, gridId)
|
||
activate GridService
|
||
GridService->>Database: 更新用户的 grid_id
|
||
Database-->>GridService: 更新成功
|
||
GridService-->>GridController: 分配成功
|
||
deactivate GridService
|
||
|
||
GridController->>OperationLogService: recordOperation(adminId, 'ASSIGN_GRID', '...details...')
|
||
activate OperationLogService
|
||
OperationLogService->>Database: 记录日志
|
||
Database-->>OperationLogService: 记录成功
|
||
OperationLogService-->>GridController: 记录完成
|
||
deactivate OperationLogService
|
||
|
||
GridController-->>Admin: 200 OK - 分配成功
|
||
else 用户角色不是网格员
|
||
GridController-->>Admin: 400 Bad Request - 用户不是网格员
|
||
end
|
||
deactivate GridController
|
||
```
|
||
|
||
### 1.14 初始化地图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as 管理员
|
||
participant MapController as 地图控制器
|
||
participant MapGridRepository as 地图网格仓库
|
||
participant Database as JSON持久化存储
|
||
|
||
Admin->>+MapController: POST /api/map/initialize (width, height)
|
||
MapController->>+MapGridRepository: deleteAll()
|
||
MapGridRepository->>+Database: DELETE FROM map_grids
|
||
Database-->>-MapGridRepository: 删除成功
|
||
MapGridRepository-->>-MapController: 返回
|
||
loop for y from 0 to height-1
|
||
loop for x from 0 to width-1
|
||
MapController->>+MapGridRepository: save(cell)
|
||
MapGridRepository->>+Database: INSERT INTO map_grids
|
||
Database-->>-MapGridRepository: 插入成功
|
||
MapGridRepository-->>-MapController: 返回
|
||
end
|
||
end
|
||
MapController-->>-Admin: 200 OK (Initialized a WxH map.)
|
||
```
|
||
|
||
### 1.15 管理员获取操作日志
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as 管理员
|
||
participant OperationLogController as 操作日志控制器
|
||
participant OperationLogService as 操作日志服务
|
||
participant OperationLogRepository as 操作日志仓库
|
||
``` |