loan-pricing/doc/2026-03-30-loan-pricing-sensitive-data-encryption-design.md

贷款定价流程客户敏感信息加密改造设计文档

1. 背景

贷款定价流程当前对客户名称 custName、证件号码 idNum 采用明文传输、明文存储、明文展示的方式处理，不满足客户敏感信息安全要求。

本次需求已经明确限定为：

• 仅覆盖贷款定价流程主链
• 敏感字段仅包含 custName、idNum
• custIsn 不属于本次敏感字段范围
• 不改造传输层字段加密
• 仅要求存储加密、展示脱敏
• 页面不提供任何明文查看入口
• 流程查询改为仅允许通过客户内码 custIsn 查询
• 现有存量数据不迁移，直接清空历史流程数据
• 加密密钥从后端配置文件读取，按当前项目最短路径落地

2. 已确认约束

• 仅修改贷款定价流程相关前后端与数据库脚本，不扩散到系统其他模块
• 不覆盖模型输出表的存储加密治理
• 详情页模型输出“基本信息”中的 custName、idNum 必须纳入展示脱敏范围
• 不新增前端字段级加密协议
• 不引入外部密钥管理系统
• 不新增兼容性字段、补丁式逻辑或降级分支
• 必须保证新流程数据落库为密文
• 必须保证列表页、详情页始终只展示脱敏值
• 必须保证模型调用链路仍能拿到业务所需明文

3. 现状分析

当前贷款定价流程主链如下：

1. 前端个人/企业建单弹窗提交明文 custName、idNum
2. 后端 LoanPricingWorkflowServiceImpl 通过 LoanPricingConverter 将 DTO 转为 LoanPricingWorkflow
3. loan_pricing_workflow.cust_name、loan_pricing_workflow.id_num 直接保存明文
4. 列表页查询 SQL 直接查询 lpw.cust_name
5. 详情页接口直接返回流程实体中的 custName、idNum
6. LoanPricingModelService 从流程表读取数据后直接组装模型调用 DTO

现状问题有三类：

1. 存储层风险：数据库中存在明文客户名称和证件号码
2. 展示层风险：前端列表页、详情页直接展示敏感明文
3. 查询链路风险：当前列表页仍允许按客户名称查询，与密文存储目标冲突

4. 方案对比

方案一：应用层统一 AES 加解密，返回前统一脱敏

做法：

• 在后端新增贷款定价专用敏感字段加解密组件
• 创建流程时对 custName、idNum 加密后再落库
• 查询详情、模型调用前在服务内部解密
• 返回前端前统一转成脱敏值
• 前端仅负责调整查询条件和展示，不做加解密

优点：

• 改动集中，符合最短路径实现
• 与数据库实现解耦，不绑定数据库方言
• 业务边界清晰，易于控制哪些链路允许拿明文
• 便于测试和排查

缺点：

• 需要明确服务内部解密和对外脱敏的边界，避免遗漏

方案二：MyBatis TypeHandler 自动加解密

做法：

• 为实体敏感字段挂载统一的 TypeHandler
• 插入自动加密、查询自动解密
• 返回前再补充脱敏

优点：

• 业务代码表面改动更少

缺点：

• 链路不直观，联表 SQL、VO 查询、模型调用等位置容易出现加解密边界不清
• 调试复杂度高，不符合本次最短路径目标

方案三：数据库函数处理加解密

做法：

• 在 SQL 中直接调用数据库加解密函数
• 应用层只负责脱敏

优点：

• 应用层代码改动相对少

缺点：

• 强依赖数据库能力
• 维护成本高
• 联表与分页查询复杂度上升
• 不符合本次直接、清晰的实现要求

5. 设计结论

采用方案一：应用层统一 AES 加解密，返回前统一脱敏。

最终设计原则如下：

• loan_pricing_workflow.cust_name、loan_pricing_workflow.id_num 仅保存密文
• 服务内部按需短暂解密，仅供业务处理和模型调用使用
• 面向前端返回时，custName、idNum 永远转换为脱敏值
• 列表查询去掉客户名称条件，只保留客户内码等非敏感查询项
• 存量流程数据通过清空历史数据处理，不做迁移兼容

6. 架构设计

本次在贷款定价流程模块内新增两类职责：

6.1 敏感字段加解密服务

新增贷款定价专用组件 SensitiveFieldCryptoService，负责：

• 从后端配置文件读取 AES 密钥
• 对 custName、idNum 执行加密
• 对已落库密文执行解密
• 在密钥缺失或解密失败时抛出明确异常

该组件只处理加密和解密，不参与脱敏展示逻辑。

6.2 敏感字段展示服务

新增贷款定价专用组件 LoanPricingSensitiveDisplayService，负责：

• 对客户名称进行脱敏
• 对证件号码进行脱敏
• 对流程详情对象和列表对象中的敏感字段做统一替换

该组件不依赖当前系统管理员免脱敏逻辑，严格执行全员脱敏规则。

7. 数据链路设计

7.1 创建流程链路

1. 前端建单弹窗提交明文 custName、idNum
2. 后端 DTO 转实体后，在 createLoanPricing 入库前统一加密
3. loan_pricing_workflow 表保存密文
4. 创建成功后后续流程继续使用同一主记录

7.2 列表查询链路

1. 前端列表页移除客户名称搜索项，新增或保留客户内码查询
2. 后端分页查询不再按 custName 过滤
3. 列表 SQL 仍查询 cust_name 字段，但查询结果为密文
4. 服务返回前将列表 VO 中 custName 转为脱敏值
5. 前端直接展示后端返回的脱敏结果

7.3 详情查询链路

1. 后端根据流水号查询流程记录，拿到密文 custName、idNum
2. 服务内部先解密得到业务所需明文
3. 若需要组装详情对象或进行后续处理，使用解密后的值
4. 返回前调用展示服务，将 custName、idNum 替换为脱敏值
5. 前端详情页只展示脱敏内容

7.4 模型调用链路

1. LoanPricingModelService 根据流程主键读取流程记录
2. 读取到的 custName、idNum 为密文
3. 调用模型前先在服务内部解密
4. 将解密后的明文复制到 ModelInvokeDTO
5. 模型调用完成后，模型输出链路保持现状，不纳入本次改造

7.5 模型输出展示链路

1. 详情接口查询到 ModelRetailOutputFields 或 ModelCorpOutputFields
2. 模型输出实体中的 custName、idNum 保持当前存储方式，不做表级加密改造
3. 在详情接口返回前，对模型输出“基本信息”中的 custName、idNum 做统一脱敏
4. 前端 ModelOutputDisplay 组件直接展示后端返回的脱敏值
5. 不提供模型输出基本信息的明文查看入口

8. 后端改造设计

8.1 配置项

后端新增贷款定价敏感字段加密配置项，例如：

• 是否启用敏感字段加解密
• AES 密钥

本次仅要求配置文件读取固定密钥，不扩展到数据库参数表或外部密钥系统。

8.2 服务层改造

需要修改以下关键点：

1. LoanPricingWorkflowServiceImpl#createLoanPricing 在 loanPricingWorkflowMapper.insert 前统一加密 custName、idNum

2. LoanPricingWorkflowServiceImpl#selectLoanPricingBySerialNum 查询详情后先解密，再在返回前脱敏

3. LoanPricingWorkflowServiceImpl#selectLoanPricingPage 分页结果中的 custName 统一转为脱敏值

4. LoanPricingWorkflowServiceImpl#buildQueryWrapper 删除 custName 查询条件，改为仅支持 custIsn、创建者、机构号等非敏感字段

5. LoanPricingModelService#invokeModelAsync 模型调用前解密 custName、idNum，确保模型收到明文业务数据

6. LoanPricingWorkflowServiceImpl#selectLoanPricingBySerialNum 在组装 ModelRetailOutputFields、ModelCorpOutputFields 返回值时，对其 custName、idNum 进行脱敏替换

8.3 对象边界

本次不新增明文返回字段，也不保留“密文字段 + 展示字段”双轨结构，避免对象语义膨胀。

返回前对象中的敏感字段直接替换为脱敏值，确保控制器和前端都不会拿到明文。

9. 前端改造设计

9.1 列表页

修改 ruoyi-ui/src/views/loanPricing/workflow/index.vue：

• 移除“客户名称”查询项
• 改为支持客户内码查询
• 表格中 custName 继续展示，但其值来自后端脱敏结果

9.2 详情页

修改个人与企业详情组件：

• 保持字段布局不变
• custName、idNum 直接展示后端返回的脱敏值
• 不新增“查看明文”“复制原值”等交互入口
• 模型输出组件 ModelOutputDisplay.vue 的“基本信息”页签继续直接消费后端字段，但要求后端返回值已完成脱敏

9.3 建单页

个人和企业建单弹窗仍然录入明文 custName、idNum，不新增前端字段加密逻辑。

10. 数据库处理设计

本次数据库处理遵循最短路径：

1. 不修改 loan_pricing_workflow 表结构
2. 不新增密文字段、副本字段或检索字段
3. 实施前执行历史流程数据清空脚本
4. 清空范围仅限贷款定价流程相关存量数据

因为 custName、idNum 不再承担查询职责，所以现有字段直接存密文即可。

11. 错误处理设计

本次不做兼容性补丁逻辑，错误直接失败：

1. 加密配置缺失 创建流程直接失败，不允许明文落库

2. 解密失败 详情查询失败，模型调用失败，并记录明确错误日志

3. 历史脏数据 通过清空存量数据消除，不增加“密文/明文混读”兼容判断

4. 前端展示 前端只消费后端结果，不承担兜底脱敏职责

12. 测试与验收设计

12.1 后端验收

1. 创建个人贷款定价流程，校验数据库 cust_name、id_num 为密文
2. 创建企业贷款定价流程，校验数据库 cust_name、id_num 为密文
3. 列表查询仅支持通过 custIsn 命中
4. 列表返回中的 custName 为脱敏值
5. 详情返回中的 custName、idNum 为脱敏值
6. 模型输出“基本信息”中的 custName、idNum 返回为脱敏值
7. 模型调用链路成功，证明服务内部解密逻辑成立
8. 配置缺失时创建流程失败，确认不会明文入库

12.2 前端验收

1. 列表页查询项已移除客户名称，改为客户内码
2. 列表页客户名称展示为脱敏值
3. 个人详情页客户名称、证件号码展示为脱敏值
4. 企业详情页客户名称、证件号码展示为脱敏值
5. 个人模型输出“基本信息”页签中的客户名称、证件号码展示为脱敏值
6. 企业模型输出“基本信息”页签中的客户名称、证件号码展示为脱敏值
7. 创建流程、查看详情、设定执行利率等既有功能不受影响

13. 风险与控制

风险一：模型调用读取到密文

控制方式：

• 在 LoanPricingModelService 调用模型前显式解密
• 用测试覆盖模型调用前数据组装逻辑

风险二：返回链路遗漏脱敏

控制方式：

• 统一在服务层返回前调用展示服务
• 列表 VO 与详情 VO 都纳入测试覆盖

风险三：历史明文和新密文混杂

控制方式：

• 实施前清空贷款定价流程历史数据
• 不保留兼容读取分支

14. 范围与非目标

本次包含：

• 贷款定价流程建单入库加密
• 贷款定价流程列表和详情展示脱敏
• 贷款定价流程详情页中的模型输出“基本信息”展示脱敏
• 贷款定价流程查询条件收口为客户内码
• 贷款定价流程存量数据清空处理

本次不包含：

• 模型输出表存储加密改造
• 系统其他模块的敏感字段改造
• 前后端传输层字段加密
• 密钥托管平台接入
• 基于角色的明文查看权限

15. 设计结论

本次采用“应用层统一 AES 加解密 + 返回前统一脱敏”的方式，对贷款定价流程中的 custName、idNum 完成存储加密和展示脱敏改造。

该方案满足当前客户安全要求，并保持实现路径最短、责任边界清晰、业务链路闭环完整。