# Project Context

## Purpose

ERPTurbo_Server 是一个现代化的企业资源规划(ERP)系统后端服务，专注于供应链管理和业务流程自动化。系统采用微服务架构，支持采购管理、产品管理、订单管理、经销商管理、用户权限管理等核心业务功能。

## Tech Stack

### 核心技术栈
- **Java版本**: Java 21 (LTS)
- **框架**: Spring Boot 3.4.5, Spring Cloud 2024.0.1, Spring Cloud Alibaba 2023.0.3.3
- **架构模式**: DDD (领域驱动设计) + COLA架构
- **微服务**: Apache Dubbo 3.2.10
- **服务发现**: Nacos
- **数据库**: MySQL 8.0.28
- **ORM**: MyBatis Plus 3.5.10.1, MyBatis 3.0.4
- **连接池**: Druid 1.2.20
- **缓存**: Redis, Redisson
- **认证授权**: Sa-Token
- **API文档**: Swagger/OpenAPI
- **构建工具**: Maven
- **日志**: Logback

### 开发工具
- **代码生成**: Lombok
- **对象映射**: MapStruct
- **参数校验**: Validation
- **数据库连接池**: Druid
- **分布式事务**: Seata (可选)

## Project Conventions

### Code Style

#### 命名规范
- **实体类**: `Product` (领域实体), `ProductDO` (数据对象)
- **服务接口**: `功能名+ServiceI`
- **服务实现**: `功能名+ServiceImpl`
- **查询执行器**: `功能名+QryExe`
- **命令执行器**: `功能名+CmdExe`
- **网关实现**: `功能名+GatewayImpl`
- **转换器**: `功能名+Convert`
- **控制器**: `功能名+Controller`

#### 代码注解规范
- 使用Lombok简化代码 (`@Data`, `@RequiredArgsConstructor`, `@Builder`)
- MapStruct进行对象转换 (`@Mapper`)
- 统一的异常处理
- Spring注解: `@Service`, `@Component`, `@DubboService`, `@DubboReference`
- 权限注解: `@SaCheckLogin`, `@SaCheckRole`, `@SaCheckPermission`
- API文档注解: `@Tag`, `@Operation`, `@Schema`

#### 包结构规范
```
com.xunhong.erp.turbo/
├── api/           # API接口定义
│   ├── dto/       # 数据传输对象
│   │   ├── cmd/   # 命令对象
│   │   ├── qry/   # 查询对象
│   │   ├── vo/    # 视图对象
│   │   └── enums/ # 枚举类
│   └── api/       # 服务接口
├── biz/           # 业务逻辑层
│   ├── app/       # 应用服务
│   │   ├── service/     # 服务实现
│   │   └── executor/    # 执行器
│   ├── domain/    # 领域层
│   │   ├── entity/      # 领域实体
│   │   └── gateway/     # 网关接口
│   └── infrastructure/ # 基础设施层
│       ├── entity/      # 数据实体
│       ├── mapper/      # 数据访问
│       └── convert/     # 对象转换
```

### Architecture Patterns

#### 分层架构
项目采用严格的分层架构，遵循DDD和COLA架构原则：

1. **API层**: 接口定义，包括DTO、Command、Query、VO
2. **应用层**: Service服务实现，Executor执行器
3. **领域层**: Entity实体，Gateway网关接口
4. **基础设施层**: DO数据对象，Mapper数据访问，Convert转换器

#### 微服务架构
- 基于Dubbo的RPC通信
- Nacos作为注册中心和配置中心
- 模块化设计，职责单一

#### 数据访问模式
- 使用MyBatis Plus进行数据库操作
- DO与领域实体分离
- 通过MapStruct进行对象转换
- 支持多数据源

### Testing Strategy

#### 测试框架
- **单元测试**: JUnit
- **集成测试**: Spring Boot Test
- **内存数据库**: H2 (用于测试)

#### 测试规范
- 测试类命名: `被测试类+Test`
- 单元测试覆盖核心业务逻辑
- 集成测试验证API接口
- 使用H2内存数据库进行测试

### Git Workflow

#### 分支策略
- **master**: 主分支，稳定版本
- **develop**: 开发分支
- **feature/xxx**: 功能分支
- **hotfix/xxx**: 热修复分支

#### 提交规范
基于Conventional Commits规范：
- `feat`: 新功能
- `fix`: 修复
- `refactor`: 重构
- `docs`: 文档
- `style`: 格式调整
- `test`: 测试
- `chore`: 构建或辅助工具变动

## Domain Context

### 核心业务领域
1. **采购管理**: 供应商管理、采购订单、采购成本控制
2. **产品管理**: 产品信息维护、成本费用关联、分类管理
3. **订单管理**: 订单处理、订单供应商关联、包装发货
4. **经销商管理**: 经销商信息、仓库管理、返利客户
5. **权限管理**: 用户、角色、权限的完整RBAC模型
6. **基础设施**: 字典、平台、渠道、物料、协议等基础数据

### 业务规则
- 严格的权限控制体系
- 多租户支持 (基于平台维度)
- 审计日志记录
- 数据一致性要求高

## Important Constraints

### 技术约束
- 必须使用Java 21 LTS版本
- 严格遵循DDD和COLA架构
- 微服务间通信必须使用Dubbo
- 数据库操作必须通过MyBatis Plus
- 权限控制必须集成Sa-Token

### 业务约束
- 数据一致性要求高，特别是财务相关数据
- 需要支持高并发访问
- 严格的审计要求
- 多租户数据隔离

### 安全约束
- 所有API接口必须进行权限校验
- 敏感数据必须加密存储
- 审计日志必须完整记录
- 防止SQL注入和XSS攻击

## External Dependencies

### 核心依赖
- **Spring生态**: Spring Boot, Spring Cloud, Spring Security
- **数据库**: MySQL 8.0.28
- **缓存**: Redis
- **消息队列**: 可选RocketMQ/RabbitMQ
- **服务治理**: Nacos, Dubbo
- **监控**: Micrometer, Prometheus (可选)

### 外部服务
- **第三方支付**: 支付宝、微信支付 (如需要)
- **物流服务**: 快递公司API接口 (如需要)
- **短信服务**: 阿里云短信、腾讯云短信 (如需要)

### 开发工具
- **构建工具**: Maven 3.8+
- **IDE**: IntelliJ IDEA (推荐)
- **版本控制**: Git
- **API测试**: Postman/Swagger UI
