# 实体类规则

## 1. 目录结构
- **基础实体类和接口**：放置在 `common/src/main/java/com/ecep/contract/model/` 目录下
- **业务领域实体类**：放置在 `server/src/main/java/com/ecep/contract/ds/{业务领域}/model/` 目录下，按业务领域组织
  - 例如：公司相关实体在 `ds/company/model/` 目录下
  - 合同相关实体在 `ds/contract/model/` 目录下
  - 客户相关实体在 `ds/customer/model/` 目录下
  - 项目相关实体在 `ds/project/model/` 目录下
  - 供应商相关实体在 `ds/vendor/model/` 目录下

## 2. 命名规范
- 类名：使用驼峰命名法，首字母大写，如 `Contract.java`、`Company.java`
- 表名：通常与类名对应，使用大写字母和下划线，如 `CONTRACT`、`COMPANY`
- 字段名：使用小写字母和驼峰命名法，对应数据库中使用大写字母和下划线的列名

## 3. 继承与接口实现
- 实体类通常实现以下接口：
  - `IdentityEntity`：提供主键ID的getter/setter及equals方法实现
  - `BasedEntity`：提供toPrettyString()方法
  - `NamedEntity`：提供name属性的getter/setter（适用于有名称的实体）
  - `Voable<T>`：提供toVo()方法，用于将实体转换为对应的VO对象
  - **特定领域接口**：放置在对应的业务领域目录下，如 `CompanyBasedEntity` 在 `ds/company/model/` 目录下，定义与某一业务领域相关的通用方法（如getter/setter）

## 4. 注解规范
- **JPA注解**：
  - `@Entity`：标记为实体类
  - `@Table(name = "表名", schema = "supplier_ms")`：指定对应的数据库表，schema通常为"supplier_ms"
  - `@Id`：标记主键字段
  - `@GeneratedValue(strategy = GenerationType.IDENTITY)`：指定主键生成策略
  - `@Column(name = "列名", nullable = false, length = 长度)`：指定字段对应的数据库列属性
  - `@ManyToOne(fetch = FetchType.LAZY)`：指定多对一关系，通常使用LAZY加载
  - `@JoinColumn(name = "外键列名")`：指定外键列
  - `@Enumerated(EnumType.ORDINAL)`：指定枚举类型的存储方式
  - `@Lob`：指定大对象类型
  - `@Version`：指定乐观锁版本字段
- **Lombok注解**：
  - `@Getter`：生成getter方法
  - `@Setter`：生成setter方法
  - `@ToString`：生成toString方法，复杂关联对象可使用`@ToString.Exclude`排除

## 5. 字段规范
- 主键字段：
  - 类型：`Integer`
  - 命名：`id`
  - 注解：`@Id`、`@GeneratedValue(strategy = GenerationType.IDENTITY)`
- 其他字段：
  - 基本类型：使用Java包装类型（如`Integer`、`Boolean`）而不是原始类型
  - 时间类型：使用`java.time.LocalDate`或`java.time.LocalDateTime`
  - 布尔类型：使用`boolean`或`Boolean`，对应数据库中的`BIT`或`BOOLEAN`类型
  - 关联关系：使用`@ManyToOne`、`@OneToMany`等注解定义

## 6. 方法规范
- `equals`方法：通常使用`HibernateProxyUtils`工具类处理代理对象的比较
- `hashCode`方法：通常使用`HibernateProxyUtils.hashCode(this)`实现
- `toVo`方法：实现`Voable`接口，将实体转换为对应的VO对象
- `toString`方法：通常使用Lombok的`@ToString`注解生成

## 7. 注释规范
- 类注释：使用JavaDoc格式，描述实体类的用途
- 字段注释：使用JavaDoc格式，描述字段的含义、数据来源、取值范围等
- 对于特殊字段，可包含详细的说明表格或示例

## 8. 序列化规范
- **重要**：实体类**不包含**`Serializable`接口和`serialVersionUID`字段
- 序列化相关功能由对应的VO类实现

## 9. 最佳实践
- 实体类应保持简洁，只包含数据和基本的数据访问方法
- 业务逻辑应在服务层实现
- 复杂的查询逻辑应在Repository层或通过Specification实现
- 避免在实体类中使用复杂的计算逻辑
- 对于多对多关系，建议使用中间表和两个一对多关系实现
- 关联关系应使用懒加载（LAZY）以提高性能