ccdi/docs/plans/backend/2026-03-16-model-param-csv-alignment-backend-implementation.md

Model Param CSV Alignment Backend Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Align system default model parameters with assets/模型默认参数.csv on the backend and database side without changing the existing listAll/saveAll API contract.

Architecture: Keep ccdi_model_param as the single source of truth for model metadata and default values. Update initialization SQL, add an upgrade SQL for existing environments, and make a small service/mapper cleanup so query ordering and default-project copy behavior remain stable while historical custom projects stay untouched.

Tech Stack: Java 21, Spring Boot 3, MyBatis Plus, MySQL, Maven

---

Task 1: 固化 CSV 对应的系统默认参数清单

Files:

• Reference: assets/模型默认参数.csv
• Modify: sql/ccdi_model_param.sql

Step 1: 对照 CSV 列出最终参数集合

确认最终系统默认参数为 5 个模型、16 个参数：

• LARGE_TRANSACTION
• SUSPICIOUS_PART_TIME
• SUSPICIOUS_FOREIGN_EXCHANGE
• ABNORMAL_BEHAVIOR
• SUSPICIOUS_GAMBLING

并确认每条记录的 model_code、model_name、param_code、param_name、param_desc、param_value、param_unit、sort_order。

Step 2: 写一个失败前检查

运行：

Get-Content -Raw 'sql/ccdi_model_param.sql'

预期：可以看到旧参数定义仍与 CSV 不完全一致，包含已废弃参数或缺失模型。

Step 3: 更新初始化 SQL

将 sql/ccdi_model_param.sql 中 project_id = 0 的初始化数据改为与 CSV 一致，要求：

• 删除旧的废弃参数
• 新增 ABNORMAL_BEHAVIOR、SUSPICIOUS_GAMBLING
• 保证 sort_order 从 1 开始递增
• 不引入任何千分位格式数据

Step 4: 做静态自检

运行：

Get-Content -Raw 'sql/ccdi_model_param.sql'

预期：SQL 中只剩 CSV 对应的 16 条系统默认参数记录。

Step 5: 提交

git add sql/ccdi_model_param.sql
git commit -m "feat: 对齐模型默认参数初始化脚本"

Task 2: 为已有环境补充默认参数覆盖脚本

Files:

• Create or Modify: sql/2026-03-16-update-ccdi-model-param-defaults.sql

Step 1: 写覆盖脚本骨架

脚本要求：

• 以事务包裹
• 只处理 project_id = 0
• 先删除旧的系统默认参数
• 再插入与 CSV 一致的 16 条新默认参数

Step 2: 写失败前检查

运行：

Test-Path 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'
Get-Content -Raw 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'

预期：若文件已存在，内容可能未完全符合最终参数集合；若不存在，则本步骤补齐。

Step 3: 写最小正确实现

确保脚本满足：

• START TRANSACTION;
• DELETE FROM ccdi_model_param WHERE project_id = 0;
• 插入 16 条目标数据
• COMMIT;

Step 4: 自检

运行：

Get-Content -Raw 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'

预期：脚本与初始化 SQL 的系统默认参数集合完全一致。

Step 5: 提交

git add sql/2026-03-16-update-ccdi-model-param-defaults.sql
git commit -m "feat: 新增模型默认参数升级脚本"

Task 3: 稳定后端查询顺序

Files:

• Modify: ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml

Step 1: 先查看当前 SQL

运行：

Get-Content -Raw 'ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml'

预期：selectByProjectId 已存在，但排序可能仅依赖 model_code, sort_order。

Step 2: 写一个小改动

将 selectByProjectId 的排序改为稳定排序：

ORDER BY model_code, sort_order, id

如有必要，也检查 selectByProjectAndModel 是否需要补 id 兜底排序。

Step 3: 静态验证

运行：

Get-Content -Raw 'ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml'

预期：查询排序稳定，不依赖数据库默认返回顺序。

Step 4: 提交

git add ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml
git commit -m "fix: 稳定模型参数查询顺序"

Task 4: 清理服务层的 CSV 对齐边界

Files:

• Modify: ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java

Step 1: 查看当前实现

运行：

Get-Content -Raw 'ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java'

预期：当前已经支持 listAll/saveAll，但需要确认注释、排序依赖和默认项目复制逻辑是否与本次设计一致。

Step 2: 写最小修正

仅做与本次设计直接相关的修正：

• 保持 projectId=0/default/custom 的现有读取规则
• 保持默认项目首次保存时复制系统默认参数全集
• 不增加任何历史 custom 项目补齐逻辑
• 不引入任何千分位处理逻辑
• 如有重复或无效的局部变量，顺手清理为更直接的实现

Step 3: 写失败前验证

运行：

mvn -pl ccdi-project -am -DskipTests compile

预期：若存在语法或导入问题，本步先暴露出来。

Step 4: 调整到编译通过

修正编译问题后再次运行：

mvn -pl ccdi-project -am -DskipTests compile

预期：BUILD SUCCESS。

Step 5: 提交

git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java
git commit -m "refactor: 收敛模型参数服务对齐逻辑"

Task 5: 验证新旧环境脚本产物一致

Files:

• Reference: sql/ccdi_model_param.sql
• Reference: sql/2026-03-16-update-ccdi-model-param-defaults.sql
• Optional Record: docs/tests/records/model-param-backend-alignment-test.md

Step 1: 准备校验项

至少检查：

• 模型总数是否为 5
• 参数总数是否为 16
• 每个 model_code + param_code 唯一
• 所有 param_value 为原始字符串，不含千分位逗号

Step 2: 执行静态比对

运行：

Get-Content -Raw 'sql/ccdi_model_param.sql'
Get-Content -Raw 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'

预期：两个脚本中的系统默认参数集合一致。

Step 3: 如本地有数据库，执行 SQL 验证

示例：

SELECT model_code, COUNT(*) AS cnt
FROM ccdi_model_param
WHERE project_id = 0
GROUP BY model_code
ORDER BY model_code;

SELECT model_code, param_code, param_value
FROM ccdi_model_param
WHERE project_id = 0
ORDER BY model_code, sort_order, id;

预期：返回结果与 CSV 一致。

Step 4: 记录结果

将验证过程写入：

docs/tests/records/model-param-backend-alignment-test.md

Step 5: 提交

git add docs/tests/records/model-param-backend-alignment-test.md
git commit -m "test: 记录模型默认参数后端对齐验证"

Task 6: 验证接口行为不变

Files:

• Reference: ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiModelParamController.java
• Reference: ruoyi-ui/src/api/ccdi/modelParam.js

Step 1: 启动后端

运行：

mvn -pl ruoyi-admin -am spring-boot:run

Step 2: 验证查询接口

使用 Swagger 或 HTTP 工具请求：

GET /ccdi/modelParam/listAll?projectId=0

预期：

• 返回 models 数组
• 包含 5 个模型
• 各模型参数与 CSV 一致

Step 3: 验证默认项目查询

对一个 configType=default 项目请求：

GET /ccdi/modelParam/listAll?projectId=<default项目ID>

预期：返回系统默认参数全集。

Step 4: 验证默认项目首次保存

调用：

POST /ccdi/modelParam/saveAll

请求体示例：

{
  "projectId": 123,
  "models": [
    {
      "modelCode": "LARGE_TRANSACTION",
      "params": [
        {
          "paramCode": "SINGLE_TRANSACTION_AMOUNT",
          "paramValue": "2222"
        }
      ]
    }
  ]
}

预期：

• 保存成功
• 该项目 config_type 变为 custom
• 项目参数表中只复制当前系统默认参数全集，不补历史 custom 项目

Step 5: 停止后端进程并提交

测试结束后关闭 mvn spring-boot:run 启动的进程，再提交测试记录：

git add docs/tests/records/model-param-backend-alignment-test.md
git commit -m "test: 完成模型参数后端接口回归验证"

---

Plan complete and saved to docs/plans/backend/2026-03-16-model-param-csv-alignment-backend-implementation.md.