# 渤海保险API报价功能设计分析

## 概述

渤海保险模块采用标准RESTful API方式与渤海保险外部系统进行集成，提供完整的车险报价服务。该模块位于 `tenant/insurance/quotation-bohai` 目录下，采用分层架构设计，支持交强险、商业险和驾意险的统一报价处理。

## 技术架构

### 模块结构

```mermaid
graph TB
    A[quotation-bohai] --> B[api]
    B --> C[service]
    B --> D[component] 
    B --> E[entity]
    B --> F[build]
    B --> G[repository]
    B --> H[util]
    
    C --> C1[BoHaiApiRequest接口]
    C --> C2[BoHaiApiRequestImpl实现]
    
    D --> D1[BoHaiRequestApiComponent]
    
    E --> E1[request请求实体]
    E --> E2[response响应实体]
    E --> E3[vo视图对象]
    E --> E4[po持久化对象]
    
    F --> F1[BoHaiApiQuoteResultsVoBuild]
    
    G --> G1[BoHaiApiOrderRepository]
    
    H --> H1[加密工具类]
    H --> H2[签名工具类]
```

### 核心组件

| 组件 | 职责 | 说明 |
|------|------|------|
| BoHaiApiRequestImpl | 报价业务逻辑实现 | 核心服务类，协调整个报价流程 |
| BoHaiRequestApiComponent | API通信组件 | 处理与渤海外部系统的HTTP通信 |
| BoHaiApiQuoteResultsVoBuild | 结果构建器 | 将外部响应转换为内部统一数据格式 |
| BoHaiApiOrderService | 订单服务 | 管理报价订单的持久化操作 |
| SignatureUtils | 签名工具 | 处理请求签名和数据加解密 |

## API端点定义

### 核心接口方法

| 方法 | 功能 | 入参 | 返回值 |
|------|------|------|--------|
| quote() | 车险报价 | QuoteVo | QuoteResultsVo |
| underwriting() | 核保处理 | UnderwritingVo | UnderwritingResultsVo |
| getPaymentLink() | 获取支付链接 | PaymentLinkVo | PaymentLinkResultsVo |
| uploadImage() | 影像上传 | InsuranceUploadImageVo | void |
| downloadPolicy() | 保单下载 | DownloadPolicyVo | DownloadPolicyResultVo |
| queryOrderState() | 订单状态查询 | OrderStatusVo | OrderStatusResultVo |

### 渤海外部API对接

| 接口编码 | 接口名称 | 请求类型 | 功能描述 |
|----------|----------|----------|----------|
| Z00002 | 生成订单号 | GenerateOrderNoRequest | 生成渤海系统订单号 |
| Z00004 | 车型查询 | VehicleTypeQueryRequest | 查询车辆型号信息 |
| Z00005 | 车辆确认 | VehicleConfirmationRequest | 确认车辆信息 |
| Z00006 | 报价接口 | QuotationRequest | 获取保险报价 |
| Z00007 | 核保接口 | UnderwritingRequest | 提交核保申请 |
| Z00008 | 支付接口 | PaymentRequest | 获取支付链接 |

## 报价流程详细设计

### 主要报价流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Service as BoHaiApiRequestImpl  
    participant Component as BoHaiRequestApiComponent
    participant Builder as BoHaiApiQuoteResultsVoBuild
    participant OrderService as BoHaiApiOrderService
    participant External as 渤海外部API

    Client->>Service: quote(QuoteVo)
    Service->>Service: 获取配置信息
    Service->>Component: generateOrderNo()
    Component->>External: 生成订单号请求
    External-->>Component: 返回订单号
    Component-->>Service: GenerateOrderNoResponse
    
    Service->>Service: 处理车辆品牌名称
    Service->>Component: vehicleTypeQuery()
    Component->>External: 车型查询请求
    External-->>Component: 车型列表
    Component-->>Service: VehicleModelsDTO
    
    Service->>Component: vehicleConfirmation()
    Component->>External: 车辆确认请求
    External-->>Component: 车辆确认结果
    Component-->>Service: VehicleConfirmationResponse
    
    alt 车型编码错误
        Service->>Service: 提取正确车型编码
        Service->>Component: 重新车辆确认
    end
    
    Service->>Service: 构建QuotationRequest
    Service->>Service: repeatQuote()递归调用
    Service->>Component: quotation()
    Component->>External: 报价请求
    External-->>Component: 报价结果
    Component-->>Service: QuotationResponse
    
    alt 重复投保处理
        Service->>Service: 调整起保日期
        Service->>Service: 递归重新报价
    end
    
    alt 报价成功
        Service->>OrderService: 保存成功订单
        Service->>Builder: buildQuoteResultsVo()
        Builder-->>Service: QuoteResultsVo
    else 报价失败
        Service->>OrderService: 保存失败订单
        Service->>Builder: buildQuoteFailResultsVo()
        Builder-->>Service: QuoteResultsVo
    end
    
    Service-->>Client: 返回报价结果
```

### 重复投保处理逻辑

```mermaid
flowchart TD
    Start([接收报价响应]) --> CheckSuccess{报价是否成功?}
    CheckSuccess --> |成功| CheckBusinessError{商业险有错误信息?}
    CheckSuccess --> |失败| CheckTrafficError{交强险重复投保?}
    
    CheckBusinessError --> |有错误| CheckRepeatBusiness{包含重复投保?}
    CheckBusinessError --> |无错误| End([处理完成])
    
    CheckRepeatBusiness --> |是| ExtractBusinessDate[提取终保日期]
    CheckRepeatBusiness --> |否| End
    
    ExtractBusinessDate --> AdjustBusinessDate[调整商业险起保日期]
    AdjustBusinessDate --> RecursiveQuoteBusiness[递归调用报价]
    
    CheckTrafficError --> |是| ExtractTrafficDate[提取交强险日期]
    CheckTrafficError --> |否| End
    
    ExtractTrafficDate --> AdjustTrafficDate[调整交强险起保日期]
    AdjustTrafficDate --> RecursiveQuoteTraffic[递归调用报价]
    
    RecursiveQuoteBusiness --> Start
    RecursiveQuoteTraffic --> Start
```

## 数据模型设计

### 核心请求实体

```mermaid
classDiagram
    class QuotationRequest {
        +String argueSolution
        +TrafficPolicyDTO trafficPolicy
        +BusinessPolicyDTO businessPolicy
        +RealNameCheckDTO realNameCheck
        +List~UnAutoDTO~ unAutos
    }
    
    class TrafficPolicyDTO {
        +String startDate
        +String endDate
        +VehicleTaxDTO vehicleTax
    }
    
    class BusinessPolicyDTO {
        +String startDate
        +String endDate
        +List~CoveragesDTO~ coverages
        +FloatingRateOptionDTO floatingRateOption
    }
    
    class CoveragesDTO {
        +String coverageCode
        +String coverageName
        +Map~String,String~ extendInfos
        +String sumInsurd
    }
    
    class UnAutoDTO {
        +String productCode
        +String packageCode
        +String copies
    }
    
    QuotationRequest --> TrafficPolicyDTO
    QuotationRequest --> BusinessPolicyDTO
    QuotationRequest --> UnAutoDTO
    BusinessPolicyDTO --> CoveragesDTO
```

### 响应数据模型

```mermaid
classDiagram
    class QuotationResponse {
        +String responseCode
        +String responseMsg
        +DataDTO data
    }
    
    class DataDTO {
        +TrafficPolicyDTO trafficPolicy
        +BusinessPolicyDTO businessPolicy
        +UnAutoPremiumDTO unAutoPremium
    }
    
    class TrafficPolicyDTO {
        +String premium
        +String startDate
        +String endDate
        +VehicleTaxDTO vehicleTax
        +String errorMsg
    }
    
    class BusinessPolicyDTO {
        +String premium
        +String startDate  
        +String endDate
        +List~CoveragesDTO~ coverages
        +String errorMsg
    }
    
    QuotationResponse --> DataDTO
    DataDTO --> TrafficPolicyDTO
    DataDTO --> BusinessPolicyDTO
```

## 安全机制设计

### 加密通信流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Component as BoHaiRequestApiComponent
    participant Utils as SignatureUtils
    participant External as 渤海API

    Client->>Component: 发起API请求
    Component->>Component: 构建请求JSON
    Component->>Utils: encryptAndSign()
    Utils->>Utils: AES加密请求内容
    Utils->>Utils: RSA签名加密内容
    Utils-->>Component: 返回加密内容+签名
    
    Component->>Component: 设置signature请求头
    Component->>External: HTTP POST请求
    External-->>Component: 加密响应
    
    Component->>Utils: decryptByPrivateKey()
    Utils->>Utils: RSA解密响应
    Utils-->>Component: 解密后的响应内容
    Component-->>Client: 返回解析结果
```

### 配置参数管理

| 配置项 | 说明 | 示例 |
|--------|------|------|
| sysSourceCode | 系统来源代码 | 标识接入系统 |
| selfPrivateKey | 己方私钥 | RSA私钥用于解密 |
| boHaiPublicKey | 渤海公钥 | RSA公钥用于加密 |
| apiUrl | 接口地址 | 渤海API基础URL |

## 错误处理机制

### 响应码处理

| 响应码 | 含义 | 处理策略 |
|--------|------|----------|
| R_Z00001 | 成功 | 正常处理业务逻辑 |
| R_Z00002 | 数据正在处理中 | 自动重试机制 |
| R_Z00004 | 业务失败 | 检查错误信息，特殊处理重复投保 |
| R_Z00005 | 系统异常 | 抛出SystemException |

### 特殊错误处理

```mermaid
flowchart TD
    A[接收到错误响应] --> B{是否车型编码错误?}
    B --> |是| C[正则提取正确编码]
    B --> |否| D{是否重复投保?}
    
    C --> E[重新构建请求]
    E --> F[递归调用接口]
    
    D --> |是| G[解析起保终保日期]
    D --> |否| H[抛出异常或记录失败]
    
    G --> I[调整保险日期]
    I --> J[递归重新报价]
    
    F --> K[返回处理结果]
    J --> K
    H --> K
```

## 性能与监控

### 性能优化策略

1. **请求重试机制**: 针对渤海系统处理中状态(R_Z00002)自动重试
2. **递归调用控制**: 重复投保处理使用递归，需要控制递归深度
3. **缓存机制**: 车型查询结果可考虑缓存以提升性能
4. **连接池管理**: RestTemplate使用连接池管理HTTP连接

### 监控指标

| 指标类型 | 监控内容 | 阈值建议 |
|----------|----------|----------|
| 响应时间 | API调用响应时间 | <3秒 |
| 成功率 | 报价成功率 | >95% |
| 错误率 | 各类错误码占比 | <5% |
| 重试次数 | 递归调用深度 | <5次 |

### 日志记录

```mermaid
flowchart LR
    A[请求开始] --> B[记录请求参数]
    B --> C[记录加密前参数]
    C --> D[记录HTTP请求]
    D --> E[记录响应结果]
    E --> F[记录解密后参数]
    F --> G[记录业务处理结果]
```

## 完整报价流程图

```mermaid
flowchart TD
    Start([开始报价]) --> GetConfig[获取配置信息]
    GetConfig --> GenOrder[生成订单号]
    GenOrder --> ProcessBrand[处理车辆品牌名称]
    ProcessBrand --> QueryVehicle[车型查询]
    QueryVehicle --> ConfirmVehicle[车辆确认]
    
    ConfirmVehicle --> CheckVehicleError{车型编码错误?}
    CheckVehicleError --> |是| ExtractCode[提取正确编码]
    CheckVehicleError --> |否| BuildRequest[构建报价请求]
    
    ExtractCode --> QueryVehicleAgain[重新车型查询确认]
    QueryVehicleAgain --> BuildRequest
    
    BuildRequest --> CallQuote[调用报价接口]
    CallQuote --> CheckResponse{报价响应检查}
    
    CheckResponse --> |成功无错误| SaveSuccess[保存成功订单]
    CheckResponse --> |成功有错误| CheckRepeat{重复投保?}
    CheckResponse --> |失败| HandleFailure[处理失败]
    
    CheckRepeat --> |商业险重复| AdjustBusiness[调整商业险日期]
    CheckRepeat --> |交强险重复| AdjustTraffic[调整交强险日期] 
    CheckRepeat --> |其他错误| HandleFailure
    
    AdjustBusiness --> RecursiveQuote[递归报价]
    AdjustTraffic --> RecursiveQuote
    RecursiveQuote --> CallQuote
    
    SaveSuccess --> BuildSuccessResult[构建成功结果]
    HandleFailure --> SaveFailure[保存失败订单]
    SaveFailure --> BuildFailResult[构建失败结果]
    
    BuildSuccessResult --> End([返回结果])
    BuildFailResult --> End
```