# 贷款一致性验证实体类说明

## 概述

本文档描述了贷款管理一致性验证功能相关的三个核心实体类，这些实体类用于支持债权凭证与服务周期贷款合同的一致性验证功能。

## 实体类列表

### 1. LoanConsistencyValidation (贷款一致性验证记录)

**表名**: `dc_loan_consistency_validation`

**用途**: 记录每次贷款一致性验证的详细信息和结果

**核心字段**:
- `validationId`: 验证记录的唯一标识
- `loanId`: 被验证的贷款ID (必填)
- `creditId`: 关联的债权凭证ID
- `servicePeriodId`: 关联的服务周期ID
- `validationStatus`: 验证状态 (PASS/FAIL/PENDING/ERROR/TIMEOUT)
- `validationResult`: 详细的验证结果信息
- `failureReason`: 验证失败时的具体原因
- `validationTime`: 验证执行时间 (必填)
- `validatedBy`: 执行验证的系统或用户
- `validationScore`: 验证得分 (0-100)
- `ruleVersion`: 使用的验证规则版本

**业务规则**:
- 验证状态必须为预定义的常量值之一
- 验证得分范围为0-100
- 验证时间不能为空
- 失败原因长度不超过1000字符
- 验证结果详情长度不超过2000字符

**业务方法**:
- `isPassed()`: 检查验证是否通过
- `isFailed()`: 检查验证是否失败
- `isPending()`: 检查验证是否正在进行中

### 2. ValidationRule (验证规则配置)

**表名**: `dc_validation_rule`

**用途**: 存储可配置的验证规则，支持规则的动态管理和热更新

**核心字段**:
- `ruleId`: 规则的唯一标识
- `ruleName`: 规则名称 (必填，唯一)
- `ruleType`: 规则类型 (必填)
- `ruleExpression`: 规则表达式 (必填)
- `priority`: 执行优先级 (必填，大于0)
- `ruleStatus`: 规则状态 (ACTIVE/INACTIVE/DRAFT/DEPRECATED)
- `description`: 规则描述
- `configJson`: 规则配置的JSON格式数据
- `createdBy`: 规则创建人

**业务规则**:
- 规则名称必须唯一且不能为空
- 优先级必须大于0，数值越小优先级越高
- 规则表达式不能为空，长度不超过2000字符
- 规则状态必须为预定义的常量值之一
- 配置JSON长度不超过4000字符

**预定义规则类型**:
- `CREDIT_EXISTENCE`: 债权凭证存在性验证
- `CREDIT_VALIDITY`: 债权凭证有效性验证
- `CONTRACT_MATCH`: 合同匹配验证
- `AMOUNT_CONSISTENCY`: 金额一致性验证
- `DATE_CONSISTENCY`: 日期一致性验证
- `STATUS_VALIDATION`: 状态验证
- `CUSTOM`: 自定义规则

**业务方法**:
- `isActive()`: 检查规则是否激活
- `isDraft()`: 检查规则是否为草稿状态
- `isDeprecated()`: 检查规则是否已废弃

### 3. ValidationStatistics (验证统计信息)

**表名**: `dc_validation_statistics`

**用途**: 记录验证过程的统计信息，用于系统监控和性能优化

**核心字段**:
- `statisticsId`: 统计记录的唯一标识
- `statisticsDate`: 统计日期 (必填，唯一)
- `totalValidations`: 总验证次数 (必填)
- `passedValidations`: 通过验证次数 (必填)
- `failedValidations`: 失败验证次数 (必填)
- `passRate`: 通过率 (0.0-1.0)
- `avgValidationTime`: 平均验证时间(毫秒)
- `cacheHitRate`: 缓存命中率 (0-100)
- `topFailureReason`: 主要失败原因
- `errorValidations`: 验证错误次数
- `timeoutValidations`: 验证超时次数
- `maxValidationTime`: 最大验证时间(毫秒)
- `minValidationTime`: 最小验证时间(毫秒)

**业务规则**:
- 统计日期必须唯一，每天只能有一条记录
- 所有验证次数字段不能小于0
- 通过率范围为0.0-1.0
- 缓存命中率范围为0-100
- 验证时间字段不能小于0

**业务方法**:
- `calculatePassRate()`: 自动计算通过率
- `hasValidationData()`: 检查是否有验证数据
- `getFailureRate()`: 获取失败率

## 数据库设计特点

### 索引策略
1. **主键索引**: 每个表都有自增主键
2. **业务索引**: 为常用查询字段创建索引
3. **复合索引**: 为多字段查询场景优化
4. **唯一索引**: 确保业务唯一性约束

### 性能优化
1. **分区策略**: 验证记录表可按时间分区
2. **归档策略**: 历史统计数据定期归档
3. **缓存策略**: 验证结果支持Redis缓存

### 数据一致性
1. **外键约束**: 通过应用层保证引用完整性
2. **事务控制**: 验证过程使用事务确保数据一致性
3. **乐观锁**: 使用版本号防止并发更新冲突

## 使用示例

### 创建验证记录
```java
LoanConsistencyValidation validation = new LoanConsistencyValidation();
validation.setLoanId(12345L);
validation.setCreditId(67890L);
validation.setServicePeriodId(11111L);
validation.setValidationStatus(LoanConsistencyValidation.STATUS_PASS);
validation.setValidationTime(new Date());
validation.setValidatedBy("system");
validation.setValidationScore(95);
```

### 创建验证规则
```java
ValidationRule rule = new ValidationRule();
rule.setRuleName("自定义金额验证");
rule.setRuleType(ValidationRule.TYPE_AMOUNT_CONSISTENCY);
rule.setRuleExpression("ABS(credit.amount - loan.amount) <= 100");
rule.setPriority(10);
rule.setRuleStatus(ValidationRule.STATUS_ACTIVE);
rule.setDescription("允许100元以内的金额差异");
```

### 创建统计记录
```java
ValidationStatistics stats = new ValidationStatistics();
stats.setStatisticsDate(new Date());
stats.setTotalValidations(1000);
stats.setPassedValidations(950);
stats.setFailedValidations(50);
stats.calculatePassRate(); // 自动计算通过率
```

## 注意事项

1. **数据验证**: 所有实体类都包含完整的Bean Validation注解
2. **加密字段**: 敏感数据字段使用@EncryptedField注解
3. **审计字段**: 继承BaseEntity获得创建时间和更新时间
4. **常量定义**: 状态值使用常量定义，避免硬编码
5. **业务方法**: 提供便捷的业务判断方法
6. **toString方法**: 使用Apache Commons Lang的ToStringBuilder

## 扩展性考虑

1. **规则引擎**: 支持插件化的验证规则扩展
2. **统计维度**: 可扩展更多统计维度和指标
3. **验证类型**: 支持新增验证类型和验证逻辑
4. **配置化**: 验证参数和阈值支持配置化管理