# 贷款管理一致性验证设计文档

## 概述

贷款管理一致性验证功能是对现有数字债权服务系统的增强模块，通过验证债权凭证与服务周期贷款合同的一致性，确保只有通过验证的贷款记录才会在银行的贷款管理界面中显示。该功能基于RuoYi框架的现有架构，集成到ruoyi-credit模块中，提供高性能的实时验证和缓存机制。

## 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                 贷款管理一致性验证架构                        │
├─────────────────────────────────────────────────────────────┤
│                 前端展示层 (Vue3)                           │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │         loan-management.vue (增强版)                    │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│  │  │贷款列表展示 │ │验证状态显示 │ │ 统计信息面板        │ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                 Web控制层 (Controller)                      │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │         LoanConsistencyController                       │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│  │  │贷款列表API  │ │验证状态API  │ │ 验证统计API         │ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                 业务服务层 (Service)                        │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │         LoanConsistencyService                          │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│  │  │一致性验证   │ │缓存管理     │ │ 通知服务            │ │ │
│  │  │规则引擎     │ │性能优化     │ │ 日志记录            │ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                 数据访问层 (Mapper)                         │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│  │  │债权数据访问 │ │服务周期访问 │ │ 验证记录访问        │ │ │
│  │  │贷款数据访问 │ │合同数据访问 │ │ 日志数据访问        │ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                 数据持久层                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│  │MySQL数据库  │ │Redis缓存    │ │ 验证配置文件            │ │
│  │(业务数据)   │ │(验证结果)   │ │ (规则配置)              │ │
│  └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 模块集成

该功能将集成到现有的ruoyi-credit模块中，作为新的子模块：

```
ruoyi-credit
├── controller
│   └── LoanConsistencyController.java
├── service
│   ├── ILoanConsistencyService.java
│   └── impl
│       └── LoanConsistencyServiceImpl.java
├── domain
│   ├── LoanConsistencyValidation.java
│   └── ValidationRule.java
├── mapper
│   └── LoanConsistencyMapper.java
└── config
    └── ValidationRuleConfig.java
```

## 组件和接口

### 核心组件

#### 1. 贷款一致性验证服务 (LoanConsistencyService)
- **所属模块**: ruoyi-credit
- **架构层级**: 业务服务层
- **职责**: 执行债权凭证与服务周期贷款合同的一致性验证
- **接口**:
  - `getValidatedLoanList(queryParams)`: 获取通过验证的贷款列表（后端自动验证所有记录）
  - `revalidateLoan(loanId)`: 重新验证指定贷款记录
  - `validateAllLoansInBackground()`: 后台批量验证所有贷款记录

#### 2. 验证规则引擎 (ValidationRuleEngine)
- **所属模块**: ruoyi-credit
- **架构层级**: 业务服务层
- **职责**: 管理和执行可配置的验证规则
- **接口**:
  - `loadValidationRules()`: 加载验证规则配置
  - `executeRule(ruleName, context)`: 执行指定验证规则
  - `registerRule(rule)`: 注册新的验证规则
  - `updateRule(ruleName, rule)`: 更新验证规则
  - `validateRuleConfiguration(config)`: 验证规则配置有效性

#### 3. 验证缓存管理器 (ValidationCacheManager)
- **所属模块**: ruoyi-credit
- **架构层级**: 数据访问层
- **职责**: 管理验证结果的缓存和性能优化
- **接口**:
  - `cacheValidationResult(loanId, result)`: 缓存验证结果
  - `getCachedValidationResult(loanId)`: 获取缓存的验证结果
  - `invalidateCache(loanId)`: 失效指定贷款的缓存
  - `preloadValidationCache(loanIds)`: 预加载验证结果缓存

**注意**: 验证通知功能将复用现有的ruoyi-notification模块中的NotificationService，不需要创建新的通知服务组件。

### API接口设计

#### RESTful API端点

```
# 贷款一致性验证API
GET    /api/credit/loan-consistency/validated-loans    # 获取通过验证的贷款列表（后端自动验证）
PUT    /api/credit/loan-consistency/revalidate/{loanId} # 重新验证贷款
POST   /api/credit/loan-consistency/validate-all       # 触发后台批量验证

# 验证规则管理API
GET    /api/credit/validation-rules                    # 获取验证规则列表
POST   /api/credit/validation-rules                    # 创建验证规则
PUT    /api/credit/validation-rules/{ruleId}           # 更新验证规则
DELETE /api/credit/validation-rules/{ruleId}           # 删除验证规则
POST   /api/credit/validation-rules/reload             # 重新加载规则配置

# 验证缓存管理API
DELETE /api/credit/loan-consistency/cache/{loanId}     # 清除指定贷款缓存
DELETE /api/credit/loan-consistency/cache              # 清除所有验证缓存
```

## 数据模型

### 核心实体

#### 贷款一致性验证记录 (LoanConsistencyValidation)
```java
public class LoanConsistencyValidation {
    private Long validationId;        // 验证记录ID
    private Long loanId;              // 贷款ID
    private Long creditId;            // 债权凭证ID
    private Long servicePeriodId;     // 服务周期ID
    private String validationStatus;  // 验证状态: PASS/FAIL/PENDING
    private String validationResult;  // 验证结果详情
    private String failureReason;     // 失败原因
    private Date validationTime;      // 验证时间
    private String validatedBy;       // 验证执行者
    private Integer validationScore;  // 验证得分(0-100)
    private String ruleVersion;       // 使用的规则版本
    private Date createTime;          // 创建时间
    private Date updateTime;          // 更新时间
}
```

#### 验证规则配置 (ValidationRule)
```java
public class ValidationRule {
    private Long ruleId;              // 规则ID
    private String ruleName;          // 规则名称
    private String ruleType;          // 规则类型
    private String ruleExpression;    // 规则表达式
    private Integer priority;         // 优先级
    private String ruleStatus;        // 规则状态: ACTIVE/INACTIVE
    private String description;       // 规则描述
    private String configJson;        // 规则配置JSON
    private Date createTime;          // 创建时间
    private Date updateTime;          // 更新时间
    private String createdBy;         // 创建人
}
```

#### 验证统计信息 (ValidationStatistics)
```java
public class ValidationStatistics {
    private Date statisticsDate;      // 统计日期
    private Integer totalValidations; // 总验证次数
    private Integer passedValidations; // 通过验证次数
    private Integer failedValidations; // 失败验证次数
    private Double passRate;          // 通过率
    private Long avgValidationTime;   // 平均验证时间(毫秒)
    private Integer cacheHitRate;     // 缓存命中率
    private String topFailureReason;  // 主要失败原因
}
```

**注意**: ValidationStatistics实体保留用于内部监控和系统优化，但不对外提供统计API接口。

## 正确性属性

*属性是一个特征或行为，应该在系统的所有有效执行中保持为真。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*

### 属性 1: 验证结果一致性
*对于任何* 贷款记录，如果债权凭证与服务周期贷款合同信息完全一致，则验证结果必须为PASS
**验证需求: 1.1, 1.3**

### 属性 2: 验证结果排除性
*对于任何* 验证状态为FAIL的贷款记录，该记录不得出现在返回给银行用户的贷款列表中
**验证需求: 1.4**

### 属性 3: 验证日志完整性
*对于任何* 执行的验证操作，系统必须记录包含验证时间、结果和详细原因的完整日志
**验证需求: 2.1, 2.3**

### 属性 4: 通知及时性
*对于任何* 验证失败的贷款记录，系统必须在验证完成后5分钟内向相关安保公司发送通知
**验证需求: 3.1, 3.2**

### 属性 5: 缓存一致性
*对于任何* 缓存的验证结果，当原始数据发生变化时，缓存必须在5分钟内失效或更新
**验证需求: 5.4, 5.5**

### 属性 6: 规则配置热更新
*对于任何* 验证规则的配置变更，系统必须在不重启服务的情况下应用新规则
**验证需求: 4.2**

### 属性 7: 性能要求保证
*对于任何* 包含100条记录的贷款列表验证，处理时间必须不超过2秒
**验证需求: 5.1**

### 属性 8: 后台验证自动化
*对于任何* 新增或修改的贷款记录，系统必须在后台自动触发验证，无需前端手动操作
**验证需求: 1.1, 1.2**

## 错误处理

### 验证异常处理策略

1. **数据不存在异常**
   - 当债权凭证或服务周期数据不存在时，标记为验证失败
   - 记录详细的缺失数据信息
   - 通知相关用户补充数据

2. **网络超时异常**
   - 实现重试机制，最多重试3次
   - 使用指数退避策略
   - 超时后标记为验证待处理状态

3. **规则执行异常**
   - 记录规则执行错误日志
   - 跳过有问题的规则，继续执行其他规则
   - 通知管理员检查规则配置

4. **缓存异常处理**
   - 缓存不可用时直接查询数据库
   - 记录缓存异常日志
   - 自动尝试恢复缓存连接

### 降级策略

1. **验证服务降级**
   - 当验证服务不可用时，显示所有贷款记录但标注未验证状态
   - 提供手动验证入口
   - 记录降级事件日志

2. **性能降级**
   - 当系统负载过高时，启用异步验证模式
   - 优先处理高优先级贷款记录
   - 延迟处理低优先级验证请求

## 测试策略

### 单元测试
- 验证规则引擎的各个规则执行逻辑
- 缓存管理器的缓存操作功能
- 通知服务的消息发送机制
- 数据访问层的查询和更新操作

### 集成测试
- 完整的验证流程端到端测试
- 与现有债权管理系统的集成测试
- 缓存与数据库的一致性测试
- 通知系统与外部服务的集成测试

### 性能测试
- 100条记录的批量验证性能测试
- 高并发场景下的系统响应时间测试
- 缓存命中率和性能优化效果测试
- 内存使用和垃圾回收影响测试

### 属性测试配置
- 最小100次迭代的属性测试
- 每个属性测试引用对应的设计文档属性
- 标签格式: **Feature: loan-management-consistency, Property {number}: {property_text}**
- 使用jqwik框架进行属性测试实现