loan-pricing/docs/superpowers/specs/2026-05-11-shangyu-pricing-field-adjustment-design.md

上虞利率定价字段口径调整设计

背景

当前上虞利率定价新增流程已经具备个人、企业两个新增弹窗，并已有业务种类、历史贷款利率和历史贷款合同选择链路。本次需求是在现有链路上调整字段口径：

• 前端通用业务种类改为 新增/存量新增/存量转贷，仅 存量转贷 查询历史贷款合同。
• 质押 + 存单质押 时新增 couponRate 存单票面利率，客户经理填写后上传。
• 上虞对私剔除 loanPurpose 贷款用途和 bizProof 是否有经营佐证。
• 上虞对私、对公按客户类型和担保方式分别调整 collType 可选值。

用户已确认本次按页面、创建接口、服务校验、流程保存、模型调用参数全链路同步调整。用户也确认 couponRate 在 质押 + 存单质押 时必须填写。对公 businessType 上传模型接口这一条用户已明确要求忽略，因此本设计不新增、不验证 businessType 模型入参链路；本次模型入参调整只覆盖 couponRate。

范围

本次包含

• 调整个人和企业新增弹窗的 businessType 选项。
• 保持 businessType=存量转贷 才查询历史贷款合同。
• 新增 couponRate 条件展示、必填校验、提交和模型入参传递。
• 移除个人新增弹窗中的 loanPurpose 和 bizProof。
• 后端取消个人创建 DTO 对 loanPurpose 和 bizProof 的必填依赖。
• 按个人/企业和抵押/质押分别校验 collType 可选值。
• 新增或更新数据库字段定义，使 couponRate 能保存到流程表。
• 更新直接相关的前端静态断言和后端单元测试。

本次不包含

• 不重做历史贷款合同查询接口。
• 不改历史贷款合同选择弹窗结构。
• 不新增字典配置或字段配置化能力。
• 不处理旧历史数据回填。
• 不新增或验证对公 businessType 上传模型逻辑；该条按用户确认忽略。

推荐方案

采用全链路最短路径同步方案。

页面负责字段展示、条件清空和提交前整理。后端负责创建 DTO 接收、统一业务校验、流程实体保存和模型入参传递。SQL 同步补充 coupon_rate 字段，保证新环境和已有环境都能落库。

不采用只改前端的方式，因为直接调用创建接口会绕过 couponRate 必填和 collType 口径校验。不采用配置化字段规则，因为本次口径明确，配置化会超出需求范围。

前端设计

通用业务种类

个人新增弹窗和企业新增弹窗的 businessType 选项统一为：

• 新增
• 存量新增
• 存量转贷

交互规则：

• 选择 存量转贷 时，沿用现有客户内码查询历史贷款合同逻辑。
• 选择 新增 或 存量新增 时，清空历史合同选择和 loanRateHistory。
• 非 存量转贷 提交前不上传 loanRateHistory。

存单票面利率

个人和企业新增弹窗都新增 couponRate 输入框，字段名称展示为 存单票面利率。

展示和提交规则：

• 仅当 guarType=质押 且 collType=存单质押 时展示。
• 展示时必填。
• 切换担保方式或抵质押类型后，如果不再满足 质押 + 存单质押，清空 couponRate。
• 不满足条件时提交前不上传 couponRate。

上虞对私字段调整

个人新增弹窗移除：

• 贷款用途 loanPurpose
• 是否有经营佐证 bizProof

个人提交数据不再包含这两个字段。个人的 loanLoop、collThirdParty 等既有字段保持现有处理方式。

个人 collType 选项：

• guarType=抵押：一线/一类/二类/三类
• guarType=质押：存单质押/其他质押

上虞对公字段调整

企业 collType 选项：

• guarType=抵押：一类/二类/三类/四类/排污权抵押/设备等其他不动产抵押
• guarType=质押：存单质押/股权质押/其他质押

企业其他既有上传字段保持现状。

后端设计

DTO 和实体

PersonalLoanPricingCreateDTO：

• businessType 允许值改为 新增/存量新增/存量转贷。
• 移除 loanPurpose 必填和枚举校验。
• 移除 bizProof 业务依赖。
• 新增 couponRate。

CorporateLoanPricingCreateDTO：

• businessType 允许值改为 新增/存量新增/存量转贷。
• 新增 couponRate。
• collType 允许值覆盖对公抵押和质押新口径。

LoanPricingWorkflow：

• businessType 注释更新为 新增/存量新增/存量转贷。
• 新增 couponRate 字段，对应数据库 coupon_rate。
• 个人剔除字段不再作为本次创建链路必需字段。

ModelInvokeDTO：

• 新增 couponRate，用于模型调用参数。
• 不新增或调整 businessType 模型入参；该条按用户确认不纳入本次范围。

LoanPricingConverter：

• 个人和企业创建 DTO 都映射 couponRate。
• 个人转换不再依赖 loanPurpose 和 bizProof。

服务层校验

创建流程统一校验放在 LoanPricingWorkflowServiceImpl，确保绕过前端直接调用接口也会被拦截。

校验规则：

• businessType 必填，只允许 新增/存量新增/存量转贷。
• businessType=存量转贷 时，loanRateHistory 必填。
• guarType=质押 且 collType=存单质押 时，couponRate 必填。
• custType=个人 且 guarType=抵押 时，collType 只允许 一线/一类/二类/三类。
• custType=个人 且 guarType=质押 时，collType 只允许 存单质押/其他质押。
• custType=企业 且 guarType=抵押 时，collType 只允许 一类/二类/三类/四类/排污权抵押/设备等其他不动产抵押。
• custType=企业 且 guarType=质押 时，collType 只允许 存单质押/股权质押/其他质押。

当担保方式不是抵押或质押时，不要求 collType 和 couponRate。

数据库设计

流程表新增字段：

ALTER TABLE `loan_pricing_workflow`
  ADD COLUMN `coupon_rate` varchar(100) DEFAULT NULL COMMENT '存单票面利率' AFTER `loan_rate_history`;

需要同步更新：

• 当前迁移 SQL。
• sql/loan_pricing_workflow.sql。
• sql/loan_pricing_schema_20260328.sql。
• sql/loan_pricing_prod_init_20260331.sql。

已有历史数据不回填，coupon_rate 允许为空。

数据流

1. 用户进入利率定价列表，选择新增。
2. 用户选择个人或企业客户，并通过客户号映射选择客户内码。
3. 打开对应新增弹窗。
4. 用户选择业务种类。
5. 若业务种类为 存量转贷，前端使用客户内码查询历史贷款合同并回填 loanRateHistory。
6. 用户选择担保方式和抵质押类型。
7. 若选择 质押 + 存单质押，前端展示并要求填写 couponRate。
8. 前端提交前清理不适用字段。
9. 后端创建接口接收 DTO。
10. 转换器映射为 LoanPricingWorkflow。
11. 服务层做业务种类、历史利率、抵质押类型和 couponRate 校验。
12. 流程表保存。
13. 模型调用前复制流程字段到 ModelInvokeDTO，带出 couponRate；businessType 模型入参不在本次设计范围内。

错误处理

• 业务种类为空：提示 请选择业务种类 或后端返回 业务种类不能为空。
• 业务种类为旧值或非法值：后端返回 业务种类必须是：新增、存量新增、存量转贷之一。
• 存量转贷 未选择历史贷款合同：提示或返回 请选择历史贷款合同。
• 质押 + 存单质押 未填写 couponRate：提示或返回 存单票面利率不能为空。
• collType 不符合当前客户类型和担保方式：后端返回对应可选值错误。

测试设计

前端静态断言

更新或新增前端测试脚本，覆盖：

• 个人和企业新增弹窗都包含 新增/存量新增/存量转贷。
• 个人和企业新增弹窗不再包含旧选项 新客。
• 个人新增弹窗不再展示 贷款用途 和 是否有经营佐证。
• 个人抵押选项为 一线/一类/二类/三类。
• 个人质押选项包含 存单质押/其他质押。
• 企业抵押选项为 一类/二类/三类/四类/排污权抵押/设备等其他不动产抵押。
• 企业质押选项为 存单质押/股权质押/其他质押。
• couponRate 仅在 质押 + 存单质押 条件下展示、必填、提交。
• 非适用条件提交前删除 couponRate。

后端单元测试

更新 LoanPricingWorkflowServiceImplTest 或新增直接相关测试，覆盖：

• businessType=新增 通过。
• businessType=新客 拒绝。
• businessType=存量转贷 且缺少 loanRateHistory 拒绝。
• guarType=质押、collType=存单质押 且缺少 couponRate 拒绝。
• 个人抵押允许 一线/一类/二类/三类，拒绝对公专属抵押值。
• 企业抵押允许 排污权抵押/设备等其他不动产抵押。
• 企业质押允许 股权质押/其他质押。

实际页面验证

实现完成后按项目规则验证：

• 使用 nvm 控制前端 Node 版本。
• 启动前端页面并用 Playwright 打开真实页面，不使用 prototype。
• 验证个人新增弹窗字段移除、业务种类选项、抵押/质押选项和 couponRate 条件展示。
• 验证企业新增弹窗业务种类选项、抵押/质押选项和 couponRate 条件展示。
• 验证 存量转贷 仍会触发历史合同查询，新增/存量新增 不触发。
• 测试结束关闭本次启动的前后端进程。

验收标准

• 页面字段和选项与本设计一致。
• 创建接口不能接受旧业务种类 新客。
• 质押 + 存单质押 未填 couponRate 时前后端都不能提交成功。
• 不适用 couponRate 时不会上传该字段。
• couponRate 能保存到流程表并进入模型调用参数。
• 对私不再要求或上传 loanPurpose、bizProof。
• 前端静态断言、后端单元测试和真实页面验证通过。