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