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