diff --git a/assets/模型默认参数.csv b/assets/模型默认参数.csv new file mode 100644 index 00000000..d7448028 --- /dev/null +++ b/assets/模型默认参数.csv @@ -0,0 +1,20 @@ +id,project_id,model_code,model_name,param_code,param_name,param_desc,param_value,param_unit +1,0,LARGE_TRANSACTION,大额交易模型,SINGLE_TRANSACTION_AMOUNT,单笔大额收入金额,单笔收入超过该金额,1111,元 +2,0,LARGE_TRANSACTION,大额交易模型,CUMULATIVE_TRANSACTION_AMOUNT,累计大额收入金额,年累计收入超过该金额,50000001,元 +3,0,LARGE_TRANSACTION,大额交易模型,annual_turnover,年累计交易额,年累计交易额超过该金额,50000001,元 +4,0,LARGE_TRANSACTION,大额交易模型,LARGE_CASH_DEPOSIT,单笔大额存现金额,单笔存现金额超过,2000001,元 +5,0,LARGE_TRANSACTION,大额交易模型,FREQUENT_CASH_DEPOSIT,单日多次存现次数,24小时内累计存现超过,5,次 +6,0,LARGE_TRANSACTION,大额交易模型,FREQUENT_TRANSFER,单笔大额转账金额,单日转账次数超过,100001,次/日 +,,,,,,,, +7,0,SUSPICIOUS_PART_TIME,可疑兼职模型,MONTHLY_FIXED_INCOME,月度非本行工资收入金额,"除本行工资外,每月固定收入超过",5000,元/月 +8,0,SUSPICIOUS_PART_TIME,可疑兼职模型,FIXED_COUNTERPARTY_TRANSFER,季度稳定收入金额,每季从固定交易对手转入金额,15000,元/季 +,,,,,,,, +10,0,SUSPICIOUS_FOREIGN_EXCHANGE,可疑外汇交易模型,SINGLE_PURCHASE_AMOUNT,单笔购汇金额,单笔购汇超过该金额,50000,美元/笔 +11,0,SUSPICIOUS_FOREIGN_EXCHANGE,可疑外汇交易模型,SINGLE_SETTLEMENT_AMOUNT,单笔结汇金额,单笔结汇超过该金额,50000,美元/笔 +12,0,SUSPICIOUS_FOREIGN_EXCHANGE,可疑外汇交易模型,CROSS_BORDER_REMITTANCE,跨境汇款金额,跨境汇款金额超过,200000,美元/笔 +,,,,,,,, +,,ABNORMAL_BEHAVIOR,异常行为模型,stock_tfr_large,银证转账大额金额,,"1,000,000",元 +,,ABNORMAL_BEHAVIOR,异常行为模型,withdraw_cnt,微信、支付宝单日提现次数,,3,次/日 +,,ABNORMAL_BEHAVIOR,异常行为模型,withdraw_amt,微信、支付宝单日提现金额,,"50,000",元/日 +,,SUSPICIOUS_GAMBLING,疑似赌博交易模型,multi_party_amt_min,疑似赌博金额下限,,500,元 +,,SUSPICIOUS_GAMBLING,疑似赌博交易模型,multi_party_amt_max,疑似赌博金额上限,,"5,000",元 diff --git a/docs/plans/2026-03-16-model-param-csv-alignment-design.md b/docs/plans/2026-03-16-model-param-csv-alignment-design.md new file mode 100644 index 00000000..d5f9a917 --- /dev/null +++ b/docs/plans/2026-03-16-model-param-csv-alignment-design.md @@ -0,0 +1,199 @@ +# 模型默认参数 CSV 对齐设计 + +## 背景 + +当前模型参数配置页面已经支持按模型卡片垂直展示并统一保存,但系统默认参数的实际定义与 `assets/模型默认参数.csv` 不一致,主要体现在模型数量、参数数量、参数编码、名称、描述、默认值和单位上。 + +本次需要将系统默认参数、后端查询保存链路和前端展示统一对齐到 CSV,并明确兼容边界。 + +## 目标 + +- 让系统默认参数数据与 `assets/模型默认参数.csv` 保持一致 +- 前端页面完全根据查询接口动态展示所有模型和参数信息 +- 保持现有 `listAll/saveAll` 接口契约不变 +- 保持默认配置项目和自定义配置项目的既有行为清晰可控 + +## 非目标 + +- 不补齐历史 `config_type = custom` 项目缺失的模型或参数 +- 不调整 `ccdi_model_param` 表结构 +- 不增加前端本地写死的模型定义 +- 不增加任何千分位相关展示、输入或保存逻辑 + +## 现状分析 + +### 现有页面 + +当前前端页面已经具备以下能力: + +- 全局模型参数页支持按模型卡片展示全部参数 +- 项目参数页支持按模型卡片展示全部参数 +- 两个页面均通过 `GET /ccdi/modelParam/listAll` 动态拉取模型参数 +- 两个页面均通过 `POST /ccdi/modelParam/saveAll` 统一保存修改 + +这意味着本次不需要推翻页面结构,重点应放在数据定义对齐和动态渲染稳定性上。 + +### 现有后端 + +当前后端服务已经具备以下能力: + +- 根据 `projectId` 和项目 `configType` 决定查询系统默认参数或项目自定义参数 +- 默认配置项目首次保存时,会把系统默认参数复制到项目下,并切换为 `custom` +- 批量查询和批量保存接口已可复用 + +### 差异点 + +与 CSV 对比后,当前系统存在以下差异: + +- 缺少 `ABNORMAL_BEHAVIOR`、`SUSPICIOUS_GAMBLING` 两个模型 +- 部分旧参数在 CSV 中已被替换或删除 +- 多个参数的 `paramCode`、`paramName`、`paramDesc`、`paramValue`、`paramUnit` 已发生变化 +- 初始化 SQL 与已有数据库环境更新脚本尚未完全统一 + +## 方案对比 + +### 方案一:以数据库默认参数为唯一真实来源 + +- 优点:前后端天然一致,默认项目复制逻辑无需重写,风险最低 +- 优点:新增或删除模型参数后,前端可自动跟随接口展示 +- 缺点:需要认真维护初始化脚本和增量更新脚本 + +### 方案二:前端按 CSV 写死模型定义,后端只保存值 + +- 优点:页面改造直观 +- 缺点:前后端各维护一份模型定义,后续极易漂移 +- 缺点:一旦后端参数集合变化,前端会出现展示与保存不一致 + +### 方案三:后端代码内置元数据,数据库只存参数值 + +- 优点:元数据集中管理 +- 缺点:需要重构当前基于表驱动的实现方式,改动范围过大 +- 缺点:对已有项目参数复制链路影响较大 + +## 最终方案 + +采用方案一,以 `ccdi_model_param` 中 `project_id = 0` 的系统默认参数作为唯一真实来源。 + +### 数据策略 + +- 更新 `sql/ccdi_model_param.sql`,使新环境初始化时直接生成与 CSV 一致的模型参数数据 +- 保留并完善 `sql/2026-03-16-update-ccdi-model-param-defaults.sql`,用于已有环境覆盖系统默认参数 +- 系统默认参数集合以 CSV 为准,共包含 5 个模型、16 个参数 +- 历史 `config_type = custom` 项目不补齐新增模型或参数 + +### 查询策略 + +- `projectId = 0` 时,查询系统默认参数 +- `projectId > 0 && configType = default` 时,仍查询系统默认参数 +- `projectId > 0 && configType = custom` 时,查询项目自己的参数 +- 查询接口继续返回 `models` 数组,前端完全依赖接口返回数据动态渲染 + +### 保存策略 + +- 全局参数保存仍更新 `project_id = 0` 的系统默认参数 +- 默认配置项目首次保存时,复制当前系统默认参数全集到项目,再切换项目 `configType` 为 `custom` +- 已经是 `custom` 的历史项目继续只更新自身已有参数,不做补齐 +- 参数值继续按原始字符串处理,不增加千分位格式化、去逗号或自动转换逻辑 + +## 后端设计 + +### 保持接口契约不变 + +继续使用现有接口: + +- `GET /ccdi/modelParam/listAll` +- `POST /ccdi/modelParam/saveAll` + +这样可以避免额外改动前端请求层和项目参数页调用方式。 + +### 服务层调整点 + +- 保持 `CcdiModelParamServiceImpl` 现有按 `configType` 切换数据源的逻辑 +- 保持默认项目首次保存时复制系统默认参数全集的逻辑 +- 保持空值校验,防止参数值被保存为空字符串 +- 不新增历史 `custom` 项目的补齐逻辑 + +### Mapper 与 SQL 调整点 + +- `selectByProjectId` 查询顺序需要稳定,建议按 `model_code`、`sort_order`、`id` 排序 +- 初始化 SQL 和增量 SQL 的模型定义必须一致,避免新库与老库表现不同 + +## 前端设计 + +### 展示原则 + +前端不写死任何模型或参数定义,完全根据查询接口返回的数据展示: + +- 模型标题使用 `modelName` +- 模型编码使用 `modelCode` +- 参数名称使用 `paramName` +- 参数描述使用 `paramDesc` +- 参数值使用 `paramValue` +- 参数单位使用 `paramUnit` + +### 页面行为 + +- 保留现有“模型卡片垂直堆叠 + 统一保存”布局 +- 不限制模型数量和参数数量 +- 不假设固定模型顺序和参数顺序,以接口返回顺序为准 +- 保存成功后重新查询,保证页面展示与后端数据一致 + +### 修改记录实现 + +当前页面中对修改项的记录依赖 `Set + $forceUpdate`。本次建议改为更稳定的响应式结构,例如: + +- 以 `modelCode:paramCode` 作为唯一键 +- 使用普通对象或数组维护已修改项 + +这样可以减少 Vue 2 对 `Set` 响应式不完整带来的不稳定行为。 + +## 影响范围 + +### 后端 + +- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java` +- `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml` +- `sql/ccdi_model_param.sql` +- `sql/2026-03-16-update-ccdi-model-param-defaults.sql` + +### 前端 + +- `ruoyi-ui/src/views/ccdi/modelParam/index.vue` +- `ruoyi-ui/src/views/ccdiProject/components/detail/ParamConfig.vue` + +## 测试方案 + +### 数据对齐测试 + +- 校验系统默认参数与 CSV 中的模型数量一致 +- 校验每个模型下的参数数量、编码、名称、描述、默认值和单位一致 +- 校验新环境初始化 SQL 和老环境增量 SQL 产出的系统默认参数一致 + +### 功能测试 + +- 全局模型参数页可动态展示所有模型参数 +- 项目参数页可动态展示所有模型参数 +- 全局参数修改后可保存成功 +- 默认配置项目读取系统默认参数 +- 默认配置项目首次保存后切换为 `custom` +- 历史 `custom` 项目不补新增参数,且页面只展示其自身已有参数 + +### 回归测试 + +- 现有 `listAll/saveAll` 接口可继续使用 +- 页面不再引入任何千分位相关逻辑 +- 保存后页面重新加载正常,修改提示正常 + +## 验收标准 + +- 系统默认参数与 `assets/模型默认参数.csv` 完全一致 +- 全局参数页和项目参数页均根据查询接口动态展示所有模型信息 +- 默认配置项目的读取与首次保存行为正确 +- 历史 `custom` 项目不被补齐、不受新增默认参数影响 +- 前后端不存在千分位相关功能设计和实现 + +--- + +**设计日期:** 2026-03-16 +**设计人员:** Codex +**审核状态:** 已确认