# EMS后端代码风格与架构设计

## 代码风格规范

### Java编码规范
1. **包命名**: 使用`com.dne.ems`作为根包
2. **类命名**: 使用PascalCase，如`AuthController`、`UserService`
3. **方法命名**: 使用camelCase，如`getUserById`、`createTask`
4. **常量命名**: 使用UPPER_SNAKE_CASE
5. **变量命名**: 使用camelCase

### 注解使用
- **Lombok**: 广泛使用`@Data`、`@Builder`、`@NoArgsConstructor`等
- **Spring**: 使用`@RestController`、`@Service`、`@Repository`等
- **验证**: 使用`@Valid`、`@NotNull`、`@Size`等JSR-303注解
- **文档**: 使用Javadoc注释，特别是公共API

### 文件组织
```
com.dne.ems/
├── config/          # 配置类，如WebConfig、SecurityConfig
├── controller/      # REST控制器，处理HTTP请求
├── dto/            # 数据传输对象，用于API交互
├── event/          # 事件定义，用于解耦组件
├── exception/      # 自定义异常和全局异常处理
├── listener/       # 事件监听器
├── model/          # 数据模型和实体类
├── repository/     # 数据访问层，JSON文件操作
├── security/       # 安全相关配置和工具
├── service/        # 业务逻辑层
└── validation/     # 自定义验证器
```

## 架构设计原则

### 分层架构
1. **Controller层**: 处理HTTP请求，参数验证，调用Service
2. **Service层**: 业务逻辑处理，事务管理
3. **Repository层**: 数据访问，JSON文件操作
4. **Model层**: 数据模型定义

### 设计模式
1. **依赖注入**: 使用Spring的IoC容器
2. **事件驱动**: 使用Spring Events解耦组件
3. **Builder模式**: 使用Lombok的@Builder
4. **策略模式**: 在业务逻辑中使用

### JSON数据存储设计
- 每个实体对应一个JSON文件
- 使用Repository模式封装文件操作
- 实现类似JPA的CRUD操作
- 支持分页和排序

## 安全设计

### JWT认证
- 使用JWT Token进行无状态认证
- Token包含用户ID、角色等信息
- 设置合理的过期时间

### 权限控制
- 基于角色的访问控制(RBAC)
- 使用Spring Security的方法级安全
- 支持多种用户角色：ADMIN、SUPERVISOR、GRID_WORKER、PUBLIC

## 异常处理

### 全局异常处理
- 使用`@ControllerAdvice`统一处理异常
- 返回标准化的错误响应格式
- 记录详细的错误日志

### 自定义异常
- `ResourceNotFoundException`: 资源未找到
- `InvalidOperationException`: 非法操作
- `UserAlreadyExistsException`: 用户已存在
- `FileStorageException`: 文件存储异常

## API设计规范

### RESTful设计
- 使用标准HTTP方法：GET、POST、PUT、DELETE
- 资源命名使用复数形式
- 使用HTTP状态码表示操作结果

### 响应格式
```json
{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2025-01-XX"
}
```

### 分页响应
```json
{
  "content": [],
  "totalElements": 100,
  "totalPages": 10,
  "size": 10,
  "number": 0
}
```

## 性能优化

### 缓存策略
- 使用Google Guava进行内存缓存
- 缓存频繁访问的数据
- 设置合理的缓存过期时间

### 异步处理
- 使用`@Async`注解处理耗时操作
- 配置线程池参数
- 事件处理异步化

## 日志规范

### 日志级别
- ERROR: 系统错误，需要立即处理
- WARN: 警告信息，可能的问题
- INFO: 重要的业务流程信息
- DEBUG: 调试信息，开发环境使用

### 日志内容
- 包含请求ID便于追踪
- 记录关键业务操作
- 敏感信息脱敏处理

## 测试规范

### 单元测试
- 使用JUnit 5
- Service层测试覆盖率>80%
- 使用Mockito进行依赖模拟

### 集成测试
- 使用Spring Boot Test
- 测试完整的API流程
- 使用测试数据库或文件