287 lines
15 KiB
Markdown
287 lines
15 KiB
Markdown
# 贷款管理一致性验证设计文档
|
||
|
||
## 概述
|
||
|
||
贷款管理一致性验证功能是对现有数字债权服务系统的增强模块，通过验证债权凭证与服务周期贷款合同的一致性，确保只有通过验证的贷款记录才会在银行的贷款管理界面中显示。该功能基于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框架进行属性测试实现 |