1

ems-backend/.serena/memories/controller_implementations.md

@@ -0,0 +1,207 @@
+# 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`)
+
+**关键特性**:
+```java
+@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格式）
+- 反馈查询（支持多条件过滤和分页）
+- 反馈统计数据获取
+- 反馈处理和状态更新
+
+**权限控制**:
+```java
+@PreAuthorize("isAuthenticated()") // 提交反馈
+@PreAuthorize("hasAnyRole('ADMIN', 'SUPERVISOR', 'DECISION_MAKER')") // 查看详情
+@PreAuthorize("hasAnyRole('ADMIN', 'SUPERVISOR')") // 处理反馈
+```
+
+**高级查询支持**:
+- 状态过滤：PENDING_REVIEW/PROCESSED/REJECTED
+- 污染类型：AIR/WATER/SOIL/NOISE
+- 严重程度：LOW/MEDIUM/HIGH/CRITICAL
+- 地理位置：城市/区县
+- 时间范围：开始日期至结束日期
+- 关键词模糊匹配
+
+**文件上传支持**:
+```java
+@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`
+
+**主要功能**:
+- 任务创建与分配
+- 任务状态管理（审核、批准、拒绝、取消）
+- 从反馈创建任务
+- 任务查询与过滤
+
+**权限设计**:
+```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`)
+
+**从反馈创建任务**:
+```java
+@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操作
+- 用户角色管理
+- 用户信息查询与更新
+
+**权限控制**:
+```java
+@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. 统一的响应格式
+```java
+// 成功响应
+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. 参数验证
+```java
+@Valid @RequestBody // 请求体验证
+@Valid @RequestPart // 文件上传验证
+@NotBlank @Email String email // 参数级验证
+```
+
+### 4. API文档
+- 使用Swagger/OpenAPI注解
+- 详细的JavaDoc文档
+- 参数说明和示例
+
+### 5. 异常处理
+- 全局异常处理器
+- 自定义业务异常
+- 统一错误响应格式
+
+### 6. 日志记录
+```java
+@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应用的最佳实践。