# 贷款定价流程客户敏感信息加密改造设计文档 ## 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` 完成存储加密和展示脱敏改造。 该方案满足当前客户安全要求，并保持实现路径最短、责任边界清晰、业务链路闭环完整。