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

概述

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

技术架构

模块结构

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	获取支付链接

报价流程详细设计

主要报价流程

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: 返回报价结果

重复投保处理逻辑

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

数据模型设计

核心请求实体

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

响应数据模型

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

安全机制设计

加密通信流程

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

特殊错误处理

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

性能与监控

性能优化策略

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

监控指标

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

日志记录

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

完整报价流程图

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

bohai-insurance-api-quotation-analysis.md 12 KB Bezpośredni odnośnik Historia Czysty

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

概述

技术架构

模块结构

核心组件

API端点定义

核心接口方法

渤海外部API对接

报价流程详细设计

主要报价流程

重复投保处理逻辑

数据模型设计

核心请求实体

响应数据模型

安全机制设计

加密通信流程

配置参数管理

错误处理机制

响应码处理

特殊错误处理

性能与监控

性能优化策略

监控指标

日志记录

完整报价流程图

bohai-insurance-api-quotation-analysis.md 12 KB

Bezpośredni odnośnik Historia Czysty