358 lines
8.4 KiB
Markdown
358 lines
8.4 KiB
Markdown
# 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: 写一个失败前检查**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
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: 做静态自检**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
Get-Content -Raw 'sql/ccdi_model_param.sql'
|
||
```
|
||
|
||
预期：SQL 中只剩 CSV 对应的 16 条系统默认参数记录。
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
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: 写失败前检查**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
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: 自检**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
Get-Content -Raw 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'
|
||
```
|
||
|
||
预期：脚本与初始化 SQL 的系统默认参数集合完全一致。
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
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**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
Get-Content -Raw 'ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml'
|
||
```
|
||
|
||
预期：`selectByProjectId` 已存在，但排序可能仅依赖 `model_code, sort_order`。
|
||
|
||
**Step 2: 写一个小改动**
|
||
|
||
将 `selectByProjectId` 的排序改为稳定排序：
|
||
|
||
```xml
|
||
ORDER BY model_code, sort_order, id
|
||
```
|
||
|
||
如有必要，也检查 `selectByProjectAndModel` 是否需要补 `id` 兜底排序。
|
||
|
||
**Step 3: 静态验证**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
Get-Content -Raw 'ccdi-project/src/main/resources/mapper/ccdi/project/CcdiModelParamMapper.xml'
|
||
```
|
||
|
||
预期：查询排序稳定，不依赖数据库默认返回顺序。
|
||
|
||
**Step 4: 提交**
|
||
|
||
```bash
|
||
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: 查看当前实现**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
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: 写失败前验证**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
mvn -pl ccdi-project -am -DskipTests compile
|
||
```
|
||
|
||
预期：若存在语法或导入问题，本步先暴露出来。
|
||
|
||
**Step 4: 调整到编译通过**
|
||
|
||
修正编译问题后再次运行：
|
||
|
||
```bash
|
||
mvn -pl ccdi-project -am -DskipTests compile
|
||
```
|
||
|
||
预期：BUILD SUCCESS。
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
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: 执行静态比对**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
Get-Content -Raw 'sql/ccdi_model_param.sql'
|
||
Get-Content -Raw 'sql/2026-03-16-update-ccdi-model-param-defaults.sql'
|
||
```
|
||
|
||
预期：两个脚本中的系统默认参数集合一致。
|
||
|
||
**Step 3: 如本地有数据库，执行 SQL 验证**
|
||
|
||
示例：
|
||
|
||
```sql
|
||
SELECT model_code, COUNT(*) AS cnt
|
||
FROM ccdi_model_param
|
||
WHERE project_id = 0
|
||
GROUP BY model_code
|
||
ORDER BY model_code;
|
||
```
|
||
|
||
```sql
|
||
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: 记录结果**
|
||
|
||
将验证过程写入：
|
||
|
||
```text
|
||
docs/tests/records/model-param-backend-alignment-test.md
|
||
```
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
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: 启动后端**
|
||
|
||
运行：
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am spring-boot:run
|
||
```
|
||
|
||
**Step 2: 验证查询接口**
|
||
|
||
使用 Swagger 或 HTTP 工具请求：
|
||
|
||
```http
|
||
GET /ccdi/modelParam/listAll?projectId=0
|
||
```
|
||
|
||
预期：
|
||
|
||
- 返回 `models` 数组
|
||
- 包含 5 个模型
|
||
- 各模型参数与 CSV 一致
|
||
|
||
**Step 3: 验证默认项目查询**
|
||
|
||
对一个 `configType=default` 项目请求：
|
||
|
||
```http
|
||
GET /ccdi/modelParam/listAll?projectId=<default项目ID>
|
||
```
|
||
|
||
预期：返回系统默认参数全集。
|
||
|
||
**Step 4: 验证默认项目首次保存**
|
||
|
||
调用：
|
||
|
||
```http
|
||
POST /ccdi/modelParam/saveAll
|
||
```
|
||
|
||
请求体示例：
|
||
|
||
```json
|
||
{
|
||
"projectId": 123,
|
||
"models": [
|
||
{
|
||
"modelCode": "LARGE_TRANSACTION",
|
||
"params": [
|
||
{
|
||
"paramCode": "SINGLE_TRANSACTION_AMOUNT",
|
||
"paramValue": "2222"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
预期：
|
||
|
||
- 保存成功
|
||
- 该项目 `config_type` 变为 `custom`
|
||
- 项目参数表中只复制当前系统默认参数全集，不补历史 `custom` 项目
|
||
|
||
**Step 5: 停止后端进程并提交**
|
||
|
||
测试结束后关闭 `mvn spring-boot:run` 启动的进程，再提交测试记录：
|
||
|
||
```bash
|
||
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`.
|