# 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 操作日志仓库
```