---
description: 对象转换Convert类规范，DO/VO/DTO分层隔离转换
globs: ["**/*Convert.java"]
alwaysApply: false
---
# 冲突优先级声明
Java编码规范、达梦实体规则优先级高于本文件。

# 对象转换Convert类开发规范
## 一、基础规范
1. 存放路径：convert包下，命名 XxxConvert；
2. 类添加 @Mapper(componentModel = "spring") 注解，使用MapStruct自动生成转换实现；
3. 所有转换方法为静态/实例抽象方法，禁止手动编写set赋值转换逻辑；
4. 转换类只做对象属性拷贝，不编写业务计算、数据查询逻辑。

## 二、标准转换方法定义
### 1. DO ↔ RespVO
RespVO toRespVO(DO entity);
List<RespVO> toRespVOList(List<DO> list);

### 2. SaveReqVO → DO
DO toDO(SaveReqVO reqVO);

### 3. DO ↔ Feign DTO（跨服务传输）
DTO toDTO(DO entity);
DO toDO(DTO dto);
List<DTO> toDTOList(List<DO> list);

## 三、特殊字段转换处理规则
1. 字典翻译、关联名称等富化字段：转换基础拷贝后，在Service层单独赋值，Convert不处理；
2. 时间字段 LocalDateTime 自动映射，无需额外转换配置；
3. 雪花ID String类型自动映射，无精度丢失问题；
4. 枚举字段：统一存储Integer编码，转换时直接拷贝数字，中文翻译在VO层处理；
5. 集合List<String> JSON字段：MyBatis类型处理器处理，转换层直接拷贝。

## 四、MapStruct 注解配置规范
1. 字段名称完全一致时，无需额外@Mapping；
2. 字段名称不一致时，添加映射注解：
    @Mapping(source = "userId", target = "uid")
3. 忽略不需要拷贝的字段：
    @Mapping(target = "richName", ignore = true)
4. 禁止使用复杂表达式在@Mapping中，复杂逻辑交给Service处理。

## 五、Convert通用禁止项
❌ 禁止手动new对象+连环set做转换，必须MapStruct自动生成；
❌ 禁止在转换方法中调用Mapper、Feign、Service查询数据；
❌ 禁止转换类添加业务工具方法、常量；
❌ 禁止跨模块直接转换VO与DO，跨服务只能通过DTO中转；
❌ 禁止转换方法返回null，空集合统一返回空列表Collections.emptyList()。
