anxin-ruoyi/.kiro/specs/bank-data-consistency-fix/design.md

# 银行数据一致性管理设计文档

## 概述

银行数据一致性管理系统旨在解决当前银行管理界面和服务周期贷款系统之间数据不一致的问题。通过建立统一的数据源、标准化的API接口和自动化的数据同步机制，确保用户在不同界面看到一致的银行信息。

### 核心设计原则

1. **单一数据源原则**: 以服务周期贷款系统的银行数据为唯一标准数据源
2. **API统一化原则**: 所有银行相关功能统一使用服务周期贷款系统的API
3. **实时同步原则**: 确保数据变更能够实时反映到所有相关界面
4. **向后兼容原则**: 保持现有功能的正常运行，平滑过渡到新的数据架构

## 架构设计

### 系统架构图

```mermaid
graph TB
    subgraph "前端层"
        A[银行管理界面] 
        B[服务周期贷款界面]
    end
    
    subgraph "API网关层"
        C[银行数据统一API网关]
    end
    
    subgraph "服务层"
        D[服务周期贷款服务]
        E[数据一致性监控服务]
        F[数据同步服务]
    end
    
    subgraph "数据层"
        G[服务周期贷款银行数据]
        H[银行机构基础数据]
        I[数据一致性日志]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    D --> G
    E --> G
    E --> H
    E --> I
    F --> G
    F --> H
```

### 数据流设计

1. **数据读取流程**: 银行管理界面 → API网关 → 服务周期贷款服务 → 银行数据
2. **数据同步流程**: 数据同步服务 → 监控数据差异 → 执行同步操作 → 记录同步日志
3. **一致性检查流程**: 监控服务 → 比较数据源 → 生成报告 → 触发同步

## 组件和接口设计

### 1. 银行数据统一API网关

**职责**: 提供统一的银行数据访问接口，屏蔽底层数据源的复杂性

**核心接口**:

```java
@RestController
@RequestMapping("/api/unified/bank")
public class UnifiedBankController {
    
    /**
     * 获取银行列表（统一接口）
     */
    @GetMapping("/list")
    public AjaxResult getBankList(@RequestParam Map<String, Object> params);
    
    /**
     * 获取银行详情（统一接口）
     */
    @GetMapping("/{bankId}")
    public AjaxResult getBankDetail(@PathVariable Long bankId);
    
    /**
     * 根据贷款条件匹配银行（统一接口）
     */
    @GetMapping("/match")
    public AjaxResult matchBanks(@RequestParam BigDecimal loanAmount, 
                                @RequestParam Integer termMonths);
}
```

### 2. 数据一致性监控服务

**职责**: 监控银行管理界面和服务周期贷款系统之间的数据一致性

**核心接口**:

```java
@Service
public class BankDataConsistencyService {
    
    /**
     * 检查数据一致性
     */
    public ConsistencyCheckResult checkDataConsistency();
    
    /**
     * 生成一致性报告
     */
    public ConsistencyReport generateConsistencyReport();
    
    /**
     * 获取数据差异详情
     */
    public List<DataDifference> getDataDifferences();
}
```

### 3. 数据同步服务

**职责**: 执行数据同步操作，确保银行管理界面数据与服务周期贷款系统保持一致

**核心接口**:

```java
@Service
public class BankDataSyncService {
    
    /**
     * 执行数据同步
     */
    public SyncResult syncBankData();
    
    /**
     * 同步指定银行数据
     */
    public SyncResult syncSpecificBank(Long bankId);
    
    /**
     * 验证同步结果
     */
    public boolean validateSyncResult();
}
```

## 数据模型设计

### 统一银行数据模型

```java
public class UnifiedBankData {
    private Long bankId;                    // 银行ID
    private String bankCode;                // 银行编码
    private String bankName;                // 银行名称
    private String bankType;                // 银行类型
    private Double baseInterestRate;        // 基准利率
    private BigDecimal minLoanAmount;       // 最低贷款金额
    private BigDecimal maxLoanAmount;       // 最高贷款金额
    private Integer minLoanTermMonths;      // 最短期限
    private Integer maxLoanTermMonths;      // 最长期限
    private String cooperationStatus;       // 合作状态
    private String status;                  // 银行状态
    private Date lastUpdateTime;            // 最后更新时间
    
    // 服务周期贷款系统特有字段
    private String productName;             // 产品名称
    private String termMatch;               // 期限匹配度
    private BigDecimal monthlyPayment;      // 月还款额
    private BigDecimal totalInterest;       // 总利息
}
```

### 数据一致性检查模型

```java
public class ConsistencyCheckResult {
    private boolean isConsistent;           // 是否一致
    private int totalBanks;                 // 总银行数量
    private int inconsistentBanks;          // 不一致银行数量
    private List<DataDifference> differences; // 差异详情
    private Date checkTime;                 // 检查时间
}

public class DataDifference {
    private Long bankId;                    // 银行ID
    private String fieldName;               // 字段名称
    private Object managementValue;         // 银行管理界面值
    private Object loanSystemValue;         // 贷款系统值
    private String differenceType;          // 差异类型
}
```

## 实现策略

### 阶段1: API统一化改造

1. **创建统一API网关**
   - 实现UnifiedBankController
   - 将所有银行查询请求路由到服务周期贷款系统API
   - 保持响应格式的向后兼容性

2. **前端界面改造**
   - 修改银行管理界面的API调用路径
   - 更新数据绑定逻辑以适配新的数据格式
   - 保持用户界面的一致性

### 阶段2: 数据一致性监控

1. **实现监控服务**
   - 定期比较两个数据源的银行信息
   - 生成数据差异报告
   - 提供实时一致性状态查询

2. **建立告警机制**
   - 当检测到数据不一致时发送告警
   - 支持邮件、短信等多种告警方式
   - 提供告警历史记录查询

### 阶段3: 自动化数据同步

1. **实现同步服务**
   - 支持手动触发和自动定时同步
   - 以服务周期贷款系统数据为标准
   - 记录同步操作日志

2. **同步策略优化**
   - 支持增量同步和全量同步
   - 实现冲突检测和解决机制
   - 提供同步回滚功能

## 正确性属性

*属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*

### 属性1: 银行数据一致性验证
*对于任何*银行查询请求，银行管理界面返回的银行信息应当与服务周期贷款系统返回的银行信息完全一致
**验证: 需求 1.1, 1.3**

### 属性2: API调用路径统一性
*对于任何*银行数据获取操作，银行管理界面应当调用服务周期贷款系统的API而不是独立的银行管理API
**验证: 需求 2.1, 2.2**

### 属性3: 数据格式标准化
*对于任何*银行数据API响应，返回的数据结构和字段命名应当与服务周期贷款系统的格式完全一致
**验证: 需求 2.4, 2.5**

### 属性4: 数据同步实时性
*对于任何*服务周期贷款系统中的银行信息更新，银行管理界面应当在指定时间内反映相同的更新
**验证: 需求 1.2, 3.4**

### 属性5: 银行状态同步一致性
*对于任何*银行的可用状态变更，该银行在银行管理界面和服务周期贷款系统中应当显示相同的状态
**验证: 需求 1.4, 1.5**

### 属性6: 数据不一致检测准确性
*对于任何*数据不一致情况，监控系统应当能够准确检测并生成相应的警告和报告
**验证: 需求 3.1, 3.2**

### 属性7: 数据同步操作正确性
*对于任何*数据同步操作，同步完成后银行管理界面的数据应当与服务周期贷款系统的数据完全一致
**验证: 需求 3.3, 3.5**

### 属性8: 银行匹配逻辑一致性
*对于任何*银行筛选条件，银行管理界面和服务周期贷款系统应当返回相同的匹配结果
**验证: 需求 2.3**

## 错误处理

### 1. API调用失败处理

- **服务周期贷款系统不可用**: 提供降级方案，使用缓存数据或显示友好错误信息
- **网络超时**: 实现重试机制，最多重试3次，每次间隔递增
- **数据格式错误**: 记录错误日志，返回标准化错误响应

### 2. 数据同步失败处理

- **部分数据同步失败**: 记录失败的银行ID，支持单独重试
- **同步冲突**: 以服务周期贷款系统数据为准，记录冲突详情
- **同步中断**: 支持断点续传，从上次失败位置继续同步

### 3. 数据一致性检查异常

- **检查服务异常**: 记录异常信息，发送告警通知
- **数据源不可访问**: 跳过本次检查，记录跳过原因
- **检查结果异常**: 人工介入验证，确保检查结果的准确性

## 测试策略

### 单元测试

- **API网关测试**: 验证请求路由和响应格式转换的正确性
- **数据同步服务测试**: 验证同步逻辑和错误处理机制
- **一致性检查服务测试**: 验证数据比较和差异检测算法

### 集成测试

- **端到端数据流测试**: 验证从前端请求到后端数据返回的完整流程
- **数据同步集成测试**: 验证同步操作对实际数据的影响
- **监控告警集成测试**: 验证监控服务与告警系统的集成

### 属性测试配置

- **最小迭代次数**: 每个属性测试运行100次迭代
- **测试标签格式**: **Feature: bank-data-consistency-fix, Property {number}: {property_text}**
- **数据生成策略**: 生成多样化的银行数据和查询条件，覆盖各种边界情况

### 性能测试

- **API响应时间**: 确保统一API的响应时间不超过原有API的1.5倍
- **数据同步性能**: 验证大量银行数据同步的时间和资源消耗
- **并发访问测试**: 验证系统在高并发访问下的稳定性