1

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

@@ -0,0 +1,142 @@
+# 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流程
+- 使用测试数据库或文件