## 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. 决策者可导出分析结果，用于报告和决策支持