200 lines
7.4 KiB
Markdown
200 lines
7.4 KiB
Markdown
# 模型默认参数 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
|
||
**审核状态：** 已确认
|