2026-01-04 19:57:45 +08:00

15 KiB

Raw Permalink Blame History

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

概述

贷款管理一致性验证功能是对现有数字债权服务系统的增强模块，通过验证债权凭证与服务周期贷款合同的一致性，确保只有通过验证的贷款记录才会在银行的贷款管理界面中显示。该功能基于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)

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)

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)

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

错误处理

验证异常处理策略

数据不存在异常
- 当债权凭证或服务周期数据不存在时，标记为验证失败
- 记录详细的缺失数据信息
- 通知相关用户补充数据
网络超时异常
- 实现重试机制，最多重试3次
- 使用指数退避策略
- 超时后标记为验证待处理状态
规则执行异常
- 记录规则执行错误日志
- 跳过有问题的规则，继续执行其他规则
- 通知管理员检查规则配置
缓存异常处理
- 缓存不可用时直接查询数据库
- 记录缓存异常日志
- 自动尝试恢复缓存连接

降级策略

验证服务降级
- 当验证服务不可用时，显示所有贷款记录但标注未验证状态
- 提供手动验证入口
- 记录降级事件日志
性能降级
- 当系统负载过高时，启用异步验证模式
- 优先处理高优先级贷款记录
- 延迟处理低优先级验证请求

测试策略

单元测试

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

集成测试

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

性能测试

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

属性测试配置

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

15 KiB Raw Permalink Blame History Unescape Escape