7.0 KiB
7.0 KiB
2. 详细设计
2.1 功能模块详细设计
本章节将对核心功能模块的内部设计进行更深入的阐述。
2.1.1 反馈管理模块
反馈管理模块是系统与用户交互的核心，负责处理所有环境问题的上报和初步处理。
核心组件:
- 主要控制器:
FeedbackController,PublicController - 核心服务:
FeedbackService,FeedbackAiReviewService - 关键DTO:
FeedbackSubmissionRequest,FeedbackResponseDTO,ProcessFeedbackRequest
设计要点:
- 采用
@RequestPart同时接收JSON数据和文件上传，实现了富文本内容的反馈提交。 - 通过发布
FeedbackSubmittedForAiReviewEvent事件，将AI审核流程解耦并异步化，提高了API的响应速度。 - 提供了强大的多条件动态查询能力，支持按状态、类型、严重等级、地理位置和时间范围进行组合过滤。
反馈状态流转:
SUBMITTED → AI_REVIEWED → PENDING_REVIEW → APPROVED/REJECTED → PROCESSED → CLOSED
主要业务流程:
- 公众用户提交反馈，系统生成唯一事件ID
- AI自动审核内容，识别垃圾信息和重复提交
- 主管进行人工审核，确认反馈有效性
- 有效反馈转化为任务，进入任务管理模块
- 任务完成后，反馈状态更新为已关闭
2.1.2 任务管理模块
任务管理模块负责将已批准的反馈转化为具体的可执行任务，并对其进行全生命周期管理。
核心组件:
- 主要控制器:
TaskManagementController,TaskAssignmentController,GridWorkerTaskController - 核心服务:
TaskService,TaskAssignmentService - 关键DTO:
TaskCreationRequest,TaskDetailDTO,TaskAssignmentRequest,TaskSummaryDTO
设计要点:
- 清晰的状态机管理任务的生命周期（CREATED → ASSIGNED → IN_PROGRESS → SUBMITTED → APPROVED/REJECTED）。
- 任务分配逻辑考虑了网格员的地理位置和当前负载，旨在实现智能化的高效分配。
- 为主管和网格员提供了完全独立的API端点，严格分离了不同角色的操作权限。
任务分配算法: 任务分配采用了一种多因素加权评分机制，综合考虑以下因素：
- 地理距离: 计算网格员当前位置到任务位置的距离
- 当前负载: 评估网格员手头的任务数量和优先级
- 专业匹配度: 根据任务类型和网格员的专业技能进行匹配
- 历史表现: 考虑网格员的历史完成率和质量评分
这些因素通过加权计算得出每个候选网格员的综合得分，系统推荐得分最高的网格员。主管可以接受系统建议或手动选择其他网格员。
主要业务流程:
- 从审核通过的反馈自动创建任务，或由主管手动创建临时任务
- 系统推荐最适合的处理人员，或由主管手动指定
- 任务分配给网格员，并发送通知
- 网格员接受任务，更新状态为进行中
- 网格员处理任务，提交处理结果
- 主管审核处理结果，确认任务完成或要求重新处理
2.1.3 用户与人员管理模块
用户与人员管理模块为系统的权限管理和组织架构提供了基础。
核心组件:
- 主要控制器:
PersonnelController,UserProfileController - 核心服务:
UserAccountService,OperationLogService - 关键DTO:
UserCreationRequest,UserUpdateRequest,UserRoleUpdateRequest
设计要点:
- 提供了对用户账户的完整CRUD操作。
- 实现了用户角色和状态的精细化管理。
- 所有关键操作均通过
OperationLogService记录日志，便于审计和追踪。
用户角色体系: 系统定义了五种核心角色，每种角色具有不同的权限范围：
- ADMIN: 系统管理员，拥有所有功能的访问权限
- DECISION_MAKER: 决策者，主要访问统计数据和决策支持功能
- SUPERVISOR: 主管，负责审核反馈和任务分配
- GRID_WORKER: 网格员，负责执行具体任务
- PUBLIC_USER: 公众用户，仅能提交反馈和查询自己的反馈历史
主要业务流程:
- 管理员创建和管理系统用户
- 用户登录系统，获取JWT令牌
- 用户访问系统功能，系统根据角色进行权限控制
- 用户可以更新个人信息和密码
- 管理员可以禁用或重新激活用户账号
2.1.4 网格与地图模块
网格与地图模块是系统实现区域化、网格化管理的核心。
核心组件:
- 主要控制器:
GridController,MapController - 核心服务:
GridService,PathfindingService - 关键算法:
AStarService
设计要点:
- 支持对地理区域进行灵活的网格化定义，并可将网格标记为障碍。
- 实现了网格与网格员的关联管理。
- 核心亮点是集成了
AStarService，该服务封装了A*寻路算法，为任务路径规划提供支持。
网格数据结构: 每个网格单元包含以下关键信息：
- 网格坐标(x, y)
- 所属城市和区域
- 是否为障碍物
- 关联的网格员(可选)
- 描述信息
A*寻路算法实现: 系统实现了高效的A*寻路算法，用于为网格员规划从当前位置到任务地点的最优路径：
- 使用优先队列管理开放列表，确保每次选择F值最小的节点
- F值计算为从起点到当前节点的实际代价(G值)与从当前节点到目标的估计代价(H值)之和
- 使用曼哈顿距离作为启发函数，适合网格化的移动模式
- 动态加载地图障碍物信息，确保路径规划避开不可通行区域
主要业务流程:
- 管理员定义城市网格系统
- 管理员将网格员分配到特定网格
- 用户提交反馈时，系统自动关联到对应网格
- 网格员接收任务后，系统提供从当前位置到任务地点的最优路径
- 管理层可查看基于网格的统计数据，识别问题高发区域
2.1.5 决策支持模块
决策支持模块为管理层提供数据洞察和可视化报告，辅助决策制定。
核心组件:
- 主要控制器:
DashboardController,ReportController - 核心服务:
DashboardService,StatisticsService - 关键DTO:
DashboardStatsDTO,AqiDistributionDTO,HeatmapPointDTO
设计要点:
- 采用数据聚合和统计分析技术，从系统运行数据中提取有价值的信息。
- 提供多维度的数据可视化，包括趋势图、分布图和热力图。
- 支持数据导出功能，便于进一步分析和报告生成。
核心统计指标:
- 反馈处理效率: 平均响应时间、处理时长分布
- 任务完成情况: 按时完成率、任务状态分布
- 区域问题分布: 按网格统计的问题密度和类型分布
- 人员绩效: 网格员的任务完成量和质量评分
主要业务流程:
- 决策者登录系统，访问决策支持模块
- 系统实时计算和展示核心业务指标
- 决策者可选择不同维度进行数据分析
- 系统生成可视化图表，展示数据趋势和分布
- 决策者可导出分析结果，用于报告和决策支持