loan-pricing/doc/2026-04-09-shangyu-retail-input-params-design.md

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

## 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`
  - 固定年限下拉
  - 选项按 Excel 的 `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` 注释中写的是固定值 `931000`

本次设计不擅自调整该默认值，保持现有运行逻辑，待业务另行确认后再处理。

## 10. 非目标

- 不调整企业新增弹窗
- 不修改企业模型调用参数
- 不修改流程列表逻辑
- 不改模型返回字段映射逻辑