# 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应用的最佳实践。