Environment-Monitoring-System/ems-backend/.serena/memories/controller_implementations.md

EMS后端控制器实现详解

控制器架构概览

基于之前的分析，现在补充实际的控制器实现细节。项目采用标准的Spring MVC架构，所有控制器都位于com.dne.ems.controller包下。

核心控制器实现

1. AuthController - 认证控制器

位置: src/main/java/com/dne/ems/controller/AuthController.java

主要功能:

• 用户注册 (/api/auth/signup)
• 用户登录 (/api/auth/login)
• 用户登出 (/api/auth/logout)
• 发送验证码 (/api/auth/send-verification-code)
• 密码重置 (/api/auth/reset-password-with-code)

关键特性:

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
@Slf4j
public class AuthController {
    private final AuthService authService;
    private final VerificationCodeService verificationCodeService;
    private final OperationLogService operationLogService;
}

API设计亮点:

• 使用@Valid进行请求参数验证
• 支持JWT令牌认证响应
• 提供新旧两套密码重置API（向后兼容）
• 完整的JavaDoc文档

2. FeedbackController - 反馈管理控制器

位置: src/main/java/com/dne/ems/controller/FeedbackController.java

主要功能:

• 反馈提交（支持JSON和multipart格式）
• 反馈查询（支持多条件过滤和分页）
• 反馈统计数据获取
• 反馈处理和状态更新

权限控制:

@PreAuthorize("isAuthenticated()") // 提交反馈
@PreAuthorize("hasAnyRole('ADMIN', 'SUPERVISOR', 'DECISION_MAKER')") // 查看详情
@PreAuthorize("hasAnyRole('ADMIN', 'SUPERVISOR')") // 处理反馈

高级查询支持:

• 状态过滤：PENDING_REVIEW/PROCESSED/REJECTED
• 污染类型：AIR/WATER/SOIL/NOISE
• 严重程度：LOW/MEDIUM/HIGH/CRITICAL
• 地理位置：城市/区县
• 时间范围：开始日期至结束日期
• 关键词模糊匹配

文件上传支持:

@PostMapping(value = "/submit", consumes = {"multipart/form-data"})
public ResponseEntity<Feedback> submitFeedback(
    @Valid @RequestPart("feedback") FeedbackSubmissionRequest request,
    @RequestPart(value = "files", required = false) MultipartFile[] files,
    @AuthenticationPrincipal CustomUserDetails userDetails)

3. TaskManagementController - 任务管理控制器

位置: src/main/java/com/dne/ems/controller/TaskManagementController.java

主要功能:

• 任务创建与分配
• 任务状态管理（审核、批准、拒绝、取消）
• 从反馈创建任务
• 任务查询与过滤

权限设计:

@PreAuthorize("hasRole('SUPERVISOR')") // 类级别权限
@PreAuthorize("hasAnyAuthority('ADMIN', 'SUPERVISOR', 'DECISION_MAKER')") // 查询权限
@PreAuthorize("hasRole('ADMIN')") // 批准/拒绝权限

任务生命周期管理:

1. 创建任务 (POST /api/management/tasks)
2. 分配任务 (POST /{taskId}/assign)
3. 审核任务 (POST /{taskId}/review)
4. 批准任务 (POST /{taskId}/approve)
5. 拒绝任务 (POST /{taskId}/reject)
6. 取消任务 (POST /{taskId}/cancel)

从反馈创建任务:

@PostMapping("/feedback/{feedbackId}/create-task")
@PreAuthorize("hasRole('SUPERVISOR')")
public ResponseEntity<TaskDetailDTO> createTaskFromFeedback(
    @PathVariable Long feedbackId,
    @RequestBody @Valid TaskFromFeedbackRequest request)

4. PersonnelController - 人员管理控制器

位置: src/main/java/com/dne/ems/controller/PersonnelController.java

主要功能:

• 用户账号CRUD操作
• 用户角色管理
• 用户信息查询与更新

权限控制:

@PreAuthorize("hasRole('ADMIN')") // 类级别，仅管理员可访问
@PreAuthorize("hasRole('ADMIN') or hasRole('GRID_WORKER')") // 查询权限扩展

用户管理功能:

• 创建用户：POST /api/personnel/users
• 查询用户：GET /api/personnel/users（支持角色和姓名过滤）
• 获取用户详情：GET /api/personnel/users/{userId}
• 更新用户信息：PUT /api/personnel/users/{userId}
• 更新用户角色：PATCH /api/personnel/users/{userId}/role
• 删除用户：DELETE /api/personnel/users/{userId}

其他控制器

5. 其他重要控制器

根据目录结构，还包含以下控制器：

• DashboardController: 仪表板数据
• FileController: 文件管理
• GridController: 网格管理
• GridWorkerTaskController: 网格员任务
• MapController: 地图相关
• OperationLogController: 操作日志
• PathfindingController: 路径规划
• ProfileController: 用户配置
• PublicController: 公共接口
• SupervisorController: 主管功能
• TaskAssignmentController: 任务分配

设计模式与最佳实践

1. 统一的响应格式

// 成功响应
ResponseEntity.ok(data)
ResponseEntity.status(HttpStatus.CREATED).body(data)

// 分页响应
PageDTO<T> pageDTO = new PageDTO<>(
    page.getContent(),
    page.getTotalElements(),
    page.getTotalPages(),
    page.getNumber(),
    page.getSize()
);

2. 权限控制策略

• 类级别权限: 整个控制器的基础权限
• 方法级别权限: 特定操作的细粒度权限
• 角色层次: ADMIN > SUPERVISOR > DECISION_MAKER > GRID_WORKER > USER

3. 参数验证

@Valid @RequestBody // 请求体验证
@Valid @RequestPart // 文件上传验证
@NotBlank @Email String email // 参数级验证

4. API文档

• 使用Swagger/OpenAPI注解
• 详细的JavaDoc文档
• 参数说明和示例

5. 异常处理

• 全局异常处理器
• 自定义业务异常
• 统一错误响应格式

6. 日志记录

@Slf4j // Lombok日志注解
log.debug("Creating user with username: {}", request.getUsername());
log.info("User created successfully with ID: {}", user.getId());
log.error("Failed to create user: {}", e.getMessage(), e);

控制器交互流程

典型的请求处理流程：

1. 请求接收: Controller接收HTTP请求
2. 权限验证: Spring Security进行权限检查
3. 参数验证: @Valid注解触发参数验证
4. 业务处理: 调用Service层处理业务逻辑
5. 响应返回: 返回标准化的ResponseEntity
6. 异常处理: 全局异常处理器处理异常情况
7. 日志记录: 记录操作日志和审计信息

这种设计确保了代码的可维护性、安全性和可扩展性，体现了现代Spring Boot应用的最佳实践。