207 lines
6.3 KiB
Markdown
207 lines
6.3 KiB
Markdown
# 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应用的最佳实践。 |