wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e6419c116079bd3f202f303b0bc799b6731f070
ccdi/docs/design/2026-03-16-model-param-csv-alignment-design.md

7.4 KiB
Raw Blame History

模型默认参数 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 审核状态： 已确认

Reference in New Issue View Git Blame Copy Permalink