contract-manager/.trae/rules/vo_rules.md

VO类规则

1. 目录结构

• VO类统一放置在 common/src/main/java/com/ecep/contract/vo/ 目录下
• 按业务领域组织，不使用子目录

2. 命名规范

• 类名：使用驼峰命名法，首字母大写，以Vo结尾，如 ContractVo.java、CompanyVo.java

3. 继承与接口实现

• 必须实现 java.io.Serializable 接口，用于对象序列化
• 通常实现 IdentityEntity 接口，提供主键ID的getter/setter方法
• 可能实现 NamedEntity 接口，提供name属性的getter/setter方法（适用于有名称的VO）
• 可能实现特定领域接口，如：
  • CompanyBasedVo：提供companyId属性的getter/setter方法
  • ProjectBasedVo：提供project属性的getter/setter方法
  • ContractBasedVo：提供contractId属性的getter/setter方法
  • 其他类似的基于特定实体的接口

4. 注解规范

• 通常使用Lombok的 @Data 注解，自动生成getter、setter、equals、hashCode和toString方法

5. 序列化规范

• 必须包含 private static final long serialVersionUID = 1L; 字段，用于版本控制
• 所有字段类型必须是可序列化的

6. 字段规范

• 字段类型：
  • 整数类型：可使用 Integer 包装类型或 int 原始类型
  • 布尔类型：可使用 Boolean 包装类型或 boolean 原始类型
  • 时间类型：使用 java.time.LocalDate（日期）或 java.time.LocalDateTime（日期时间）
  • 字符串类型：使用 String
  • 浮点数类型：使用 double 或 Double
• 关联关系：
  • 通常只包含关联实体的ID字段，如 companyId、project、contractId 等
  • 不包含实体对象的直接引用
• 默认值：
  • 布尔类型字段通常有默认值（如 false）
  • 其他类型根据业务需求设置默认值

7. 注释规范

• 类注释：使用JavaDoc格式，描述VO类的用途，如 /** 项目报价视图对象 */
• 字段注释：使用JavaDoc格式，描述字段的含义、用途或业务规则
• 关键字段（如外键、状态字段）应提供清晰的注释说明

8. 最佳实践

• VO类应保持简洁，只包含数据和基本的数据访问方法
• 避免在VO类中包含复杂的业务逻辑
• 字段命名应与对应的实体类保持一致或有明确的映射关系
• 确保所有字段都是可序列化的
• 对于有默认值的字段，应在声明时初始化

9. 与实体类的区别

• 序列化：VO类必须实现 Serializable 接口并包含 serialVersionUID 字段，而实体类不包含
• 用途：VO类主要用于数据传输和展示，实体类主要用于持久化
• 关联关系：VO类通常只包含关联实体的ID，实体类包含实体对象的引用
• 注解：VO类主要使用Lombok注解，实体类使用JPA注解和Lombok注解
• 方法：VO类通常只有getter/setter方法，实体类可能包含更多业务相关方法