wkc/loan-pricing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5839a76f871f099d69f3ab8525b3952901ca7c7b
loan-pricing/doc/2026-04-09-shangyu-retail-input-params-design.md

9.3 KiB
Raw Blame History

上虞个人利率测算输入参数对齐设计文档

1. 背景

根据 doc/上虞利率测算接口文档.xlsx 的 入参 sheet，个人利率测算模型当前要求的输入参数为：

  • serialNum
  • orgCode
  • runType
  • custIsn
  • custType
  • custName
  • idType
  • idNum
  • guarType
  • applyAmt
  • loanPurpose
  • loanTerm
  • bizProof
  • loanLoop
  • collThirdParty
  • collType

现有个人新增弹窗与模型调用链路未完全覆盖该输入集合：

  • 页面缺少 loanPurpose
  • 页面缺少 loanTerm
  • collType 选项与 Excel 不一致
  • 页面开关字段当前提交的是 true/false
  • 模型调用 DTO 当前缺少 loanTerm、loanLoop

本次目标是按 Excel 的个人输入参数定义，对齐个人新增弹窗输入项和模型调用入参，不扩展到企业链路，不引入兜底或兼容分支。

2. 已确认范围

  • 仅处理个人新增弹窗
  • 仅处理个人创建流程到模型调用的入参链路
  • 保持现有页面交互结构，不新增系统字段输入区
  • loanTerm 使用固定年限下拉，选项按 Excel 定义
  • 系统字段继续自动生成或默认赋值
  • 不修改企业新增弹窗
  • 不修改模型计算规则

3. 输入参数获取方式整理

3.1 系统自动带值

以下字段不放到新增弹窗中，由现有服务链路自动提供：

  • serialNum
    • 由 LoanPricingWorkflowServiceImpl#createLoanPricing 按时间戳生成
  • orgCode
    • 由 LoanPricingWorkflowServiceImpl#createLoanPricing 在空值时补默认值
  • runType
    • 由 LoanPricingWorkflowServiceImpl#createLoanPricing 在空值时补默认值 1
  • custType
    • 由 LoanPricingConverter#toEntity(PersonalLoanPricingCreateDTO) 固定写为 个人

3.2 用户直接输入

  • 文本输入：
    • custIsn
    • custName
    • idNum
    • applyAmt
  • 下拉选择：
    • idType
    • guarType
    • loanPurpose
    • loanTerm
    • collType
  • 开关选择：
    • bizProof
    • loanLoop
    • collThirdParty

4. 现状分析

4.1 前端现状

PersonalCreateDialog.vue 当前已经提供：

  • custIsn
  • custName
  • idType
  • idNum
  • guarType
  • applyAmt
  • bizProof
  • loanLoop
  • collType
  • collThirdParty

当前缺失或不一致点：

  • 缺少 loanPurpose
  • 缺少 loanTerm
  • collType 选项为 一线/一类/二类，与 Excel 的 一类/二类/三类 不一致
  • 开关字段提交值为 true/false

4.2 后端现状

PersonalLoanPricingCreateDTO.java 当前未定义：

  • loanPurpose
  • loanTerm

LoanPricingConverter.java 当前未把以上字段映射到 LoanPricingWorkflow。

ModelInvokeDTO.java 当前未定义：

  • loanTerm
  • loanLoop

这意味着即使页面补齐字段，当前模型调用也无法完整带出 Excel 要求的个人入参。

5. 方案对比

方案一：页面补齐用户输入，系统字段继续自动带值

做法：

  • 在个人新增弹窗新增 loanPurpose 下拉
  • 在个人新增弹窗新增 loanTerm 固定年限下拉
  • 修正 collType 选项
  • 后端 DTO、转换器、模型调用 DTO 同步补字段
  • 模型调用前统一将开关字段转换为 Excel 要求的 0/1

优点：

  • 与现有个人/企业创建方式一致
  • 改动最小
  • 页面输入、流程入库、模型调用职责边界清晰

缺点：

  • 需要同时修改前后端

方案二：前端少改，后端在模型调用前兜底补参数

做法：

  • 页面只补部分字段
  • 其余由后端按默认逻辑拼接模型参数

优点：

  • 页面改动更少

缺点：

  • 页面输入和真实模型入参不一致
  • 后续排查问题时难以定位参数来源
  • 不符合本次“按现有输入方式整理字段获取方式”的要求

方案三：Excel 全量字段全部暴露到弹窗

做法：

  • 把 serialNum、orgCode、runType、custType 也作为页面字段给用户填写

优点：

  • 页面可见字段与 Excel 完全一一对应

缺点：

  • 与当前产品交互方式不一致
  • 增加误填风险
  • 不符合最短路径要求

6. 设计结论

采用方案一。

6.1 页面设计

个人新增弹窗保留现有分组结构，在“贷款信息”区域补齐：

  • loanPurpose
    • 下拉选项：consumer、business
  • loanTerm
    • 固定年限下拉
    • 选项固定为 1/2/3/4/5/6

同时修正：

  • collType 选项改为 一类/二类/三类

6.2 参数来源设计

  • 系统带值：
    • serialNum
    • orgCode
    • runType
    • custType
  • 页面透传：
    • custIsn
    • custName
    • idType
    • idNum
    • guarType
    • applyAmt
    • loanPurpose
    • loanTerm
    • collType
  • 页面开关，经模型调用层转换：
    • bizProof
    • loanLoop
    • collThirdParty

6.3 链路设计

  1. 前端提交个人创建请求时，补齐 loanPurpose、loanTerm
  2. 后端个人创建 DTO 接收新增字段
  3. 转换器将新增字段写入 LoanPricingWorkflow
  4. 模型调用 DTO 增加 loanPurpose、loanTerm、loanLoop
  5. LoanPricingModelService 在调用模型前，将个人链路中的开关字段转换为 0/1
  6. ModelService 继续以 application/x-www-form-urlencoded 方式调用模型接口

6.3.1 后端模型调用输入参数确认

后端最终发给模型的个人入参，按 Excel 要求确认为以下 16 个字段：

  • serialNum
    • 来源：LoanPricingWorkflowServiceImpl#createLoanPricing 自动生成
  • orgCode
    • 来源：LoanPricingWorkflowServiceImpl#createLoanPricing 默认赋值
    • 当前代码值：892000
  • runType
    • 来源：LoanPricingWorkflowServiceImpl#createLoanPricing
    • 当前值：1
  • custIsn
    • 来源：页面输入，经个人创建 DTO 和转换器透传
  • custType
    • 来源：LoanPricingConverter#toEntity(PersonalLoanPricingCreateDTO)
    • 当前值：固定 个人
  • custName
    • 来源：页面输入
    • 说明：入库时加密，调用模型前解密
  • idType
    • 来源：页面输入
  • idNum
    • 来源：页面输入
    • 说明：入库时加密，调用模型前解密
  • guarType
    • 来源：页面输入
  • applyAmt
    • 来源：页面输入
  • loanPurpose
    • 来源：页面输入
    • 当前状态：需补齐到个人 DTO、流程实体映射和模型 DTO
  • loanTerm
    • 来源：页面输入
    • 当前状态：需补齐到个人 DTO、流程实体映射和模型 DTO
  • bizProof
    • 来源：页面开关
    • 模型值：调用模型前统一转换为 0/1
  • loanLoop
    • 来源：页面开关
    • 当前状态：需补齐到模型 DTO
    • 模型值：调用模型前统一转换为 0/1
  • collThirdParty
    • 来源：页面开关
    • 模型值：调用模型前统一转换为 0/1
  • collType
    • 来源：页面下拉
    • 模型值：按 一类/二类/三类 直接透传

后端调用方式确认如下：

  • 参数载体：ModelInvokeDTO
  • 参数来源：BeanUtils.copyProperties(loanPricingWorkflow, modelInvokeDTO)
  • 请求构造：ModelService#entityToMap
  • 请求格式：application/x-www-form-urlencoded
  • 发送入口：ModelService#invokeModel

6.4 展示闭环

为保证输入项可在详情页回看，个人详情页同步补齐：

  • loanPurpose

loanTerm 详情展示已存在，不需要新增区域。

7. 校验与错误处理

  • 前端新增 loanPurpose 必选校验
  • 前端新增 loanTerm 必选校验
  • loanTerm 只能通过固定下拉选择，不提供自由输入
  • 后端 DTO 对 loanPurpose、loanTerm 增加必填约束
  • 保持现有创建失败与模型调用失败的错误提示方式
  • 不新增兼容逻辑、兜底逻辑或补丁式分支

8. 验证设计

  • 前端源码断言个人新增弹窗已出现 loanPurpose、loanTerm
  • 前端源码断言 loanTerm 为固定下拉、collType 选项为 一类/二类/三类
  • 后端测试或源码断言 PersonalLoanPricingCreateDTO、LoanPricingConverter、ModelInvokeDTO 已补齐字段
  • 后端测试或日志断言调用模型前最终请求参数完整包含以上 16 个字段
  • 重启后端后，覆盖以下接口验证：
    • 正常场景：完整参数创建成功
    • 必填缺失场景：缺少 loanPurpose 或 loanTerm 被拦截
    • 分支场景：bizProof、loanLoop、collThirdParty 开关不同组合能正确转换为 0/1
  • 启动前端页面并通过浏览器检查：
    • 新增弹窗展示正确
    • 提交流程后详情页能回显 loanPurpose、loanTerm
  • 验证完成后停止本次启动的前后端进程

9. 已确认项

  • orgCode 统一为 892000
  • ModelInvokeDTO 注释已统一为 892000
  • 数据库 loan_pricing_workflow.org_code 默认值已统一为 892000
  • 存量 loan_pricing_workflow.org_code 数据已通过迁移脚本统一为 892000

10. 非目标

  • 不调整企业新增弹窗
  • 不修改企业模型调用参数
  • 不修改流程列表逻辑
  • 不改模型返回字段映射逻辑
Reference in New Issue View Git Blame Copy Permalink