323 lines
9.3 KiB
Markdown
323 lines
9.3 KiB
Markdown
# 上虞个人利率测算输入参数对齐设计文档
|
||
|
||
## 1. 背景
|
||
|
||
根据 [doc/上虞利率测算接口文档.xlsx](/Users/wkc/Desktop/loan-pricing/loan-pricing/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](/Users/wkc/Desktop/loan-pricing/loan-pricing/ruoyi-ui/src/views/loanPricing/workflow/components/PersonalCreateDialog.vue) 当前已经提供：
|
||
|
||
- `custIsn`
|
||
- `custName`
|
||
- `idType`
|
||
- `idNum`
|
||
- `guarType`
|
||
- `applyAmt`
|
||
- `bizProof`
|
||
- `loanLoop`
|
||
- `collType`
|
||
- `collThirdParty`
|
||
|
||
当前缺失或不一致点：
|
||
|
||
- 缺少 `loanPurpose`
|
||
- 缺少 `loanTerm`
|
||
- `collType` 选项为 `一线/一类/二类`，与 Excel 的 `一类/二类/三类` 不一致
|
||
- 开关字段提交值为 `true/false`
|
||
|
||
### 4.2 后端现状
|
||
|
||
[PersonalLoanPricingCreateDTO.java](/Users/wkc/Desktop/loan-pricing/loan-pricing/ruoyi-loan-pricing/src/main/java/com/ruoyi/loanpricing/domain/dto/PersonalLoanPricingCreateDTO.java) 当前未定义：
|
||
|
||
- `loanPurpose`
|
||
- `loanTerm`
|
||
|
||
[LoanPricingConverter.java](/Users/wkc/Desktop/loan-pricing/loan-pricing/ruoyi-loan-pricing/src/main/java/com/ruoyi/loanpricing/util/LoanPricingConverter.java) 当前未把以上字段映射到 `LoanPricingWorkflow`。
|
||
|
||
[ModelInvokeDTO.java](/Users/wkc/Desktop/loan-pricing/loan-pricing/ruoyi-loan-pricing/src/main/java/com/ruoyi/loanpricing/domain/dto/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. 非目标
|
||
|
||
- 不调整企业新增弹窗
|
||
- 不修改企业模型调用参数
|
||
- 不修改流程列表逻辑
|
||
- 不改模型返回字段映射逻辑
|