docs: 添加模型参数阈值更新接口优化设计文档
This commit is contained in:
105
doc/plans/2026-02-26-model-param-save-optimization-design.md
Normal file
105
doc/plans/2026-02-26-model-param-save-optimization-design.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 模型参数阈值更新接口优化设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `ModelParamSaveDTO` 存在参数冗余问题：
|
||||
- 外层包含不必要的 `modelName` 字段
|
||||
- 内层 `ParamItem` 包含 6 个字段，但 Service 层只使用 `paramCode` 和 `paramValue`
|
||||
- 前端请求体包含大量无用字段，增加网络传输开销
|
||||
|
||||
## 2. 优化目标
|
||||
|
||||
- 简化 DTO 结构，减少冗余字段
|
||||
- 减少前端请求数据量
|
||||
- 提升代码可读性
|
||||
|
||||
## 3. 设计方案
|
||||
|
||||
### 3.1 后端 DTO 简化
|
||||
|
||||
**文件：** `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/ModelParamSaveDTO.java`
|
||||
|
||||
**改动：**
|
||||
- 移除 `modelName` 字段
|
||||
- 将内部类 `ParamItem` 重命名为 `ParamValueItem`
|
||||
- 内部类只保留 `paramCode` 和 `paramValue` 两个字段
|
||||
|
||||
**优化后结构：**
|
||||
```java
|
||||
@Data
|
||||
public class ModelParamSaveDTO {
|
||||
private Long projectId;
|
||||
|
||||
@NotBlank(message = "模型编码不能为空")
|
||||
private String modelCode;
|
||||
|
||||
@NotNull(message = "参数列表不能为空")
|
||||
private List<ParamValueItem> params;
|
||||
|
||||
@Data
|
||||
public static class ParamValueItem {
|
||||
@NotBlank(message = "参数编码不能为空")
|
||||
private String paramCode;
|
||||
|
||||
@NotBlank(message = "参数值不能为空")
|
||||
private String paramValue;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Service 层微调
|
||||
|
||||
**文件：** `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java`
|
||||
|
||||
**改动：** 更新循环中的类型引用
|
||||
```java
|
||||
// 改动前
|
||||
for (ModelParamSaveDTO.ParamItem item : saveDTO.getParams())
|
||||
|
||||
// 改动后
|
||||
for (ModelParamSaveDTO.ParamValueItem item : saveDTO.getParams())
|
||||
```
|
||||
|
||||
### 3.3 前端请求简化
|
||||
|
||||
**文件：** `ruoyi-ui/src/views/ccdi/modelParam/index.vue`
|
||||
|
||||
**改动：** 简化 `handleSave` 方法中的请求参数
|
||||
|
||||
**优化后：**
|
||||
```javascript
|
||||
const saveDTO = {
|
||||
projectId: this.queryParams.projectId,
|
||||
modelCode: this.queryParams.modelCode,
|
||||
params: modifiedParams.map((item) => ({
|
||||
paramCode: item.paramCode,
|
||||
paramValue: item.paramValue,
|
||||
})),
|
||||
};
|
||||
```
|
||||
|
||||
## 4. 改动文件清单
|
||||
|
||||
| 文件 | 改动类型 |
|
||||
|------|---------|
|
||||
| `ModelParamSaveDTO.java` | 简化字段 |
|
||||
| `CcdiModelParamServiceImpl.java` | 类型引用更新 |
|
||||
| `index.vue` | 请求参数简化 |
|
||||
|
||||
## 5. 优化效果
|
||||
|
||||
| 指标 | 优化前 | 优化后 |
|
||||
|------|--------|--------|
|
||||
| DTO 外层字段数 | 3 | 2 |
|
||||
| DTO 内层字段数 | 6 | 2 |
|
||||
| 前端请求体字段数 | 8 | 4 |
|
||||
|
||||
## 6. 风险评估
|
||||
|
||||
- **风险等级：** 低
|
||||
- **向后兼容：** 是（后端忽略多余字段）
|
||||
- **测试要求：** 验证保存功能正常
|
||||
|
||||
---
|
||||
|
||||
**创建日期：** 2026-02-26
|
||||
238
doc/plans/2026-02-26-model-param-save-optimization-plan.md
Normal file
238
doc/plans/2026-02-26-model-param-save-optimization-plan.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 模型参数阈值更新接口优化实施计划
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** 简化模型参数保存接口的 DTO 结构，减少冗余字段
|
||||
|
||||
**Architecture:** 纯重构，不改变业务逻辑。简化 DTO 字段，同步更新 Service 和前端调用
|
||||
|
||||
**Tech Stack:** Java 17, Spring Boot, Vue.js
|
||||
|
||||
---
|
||||
|
||||
## Task 1: 简化后端 DTO
|
||||
|
||||
**Files:**
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/ModelParamSaveDTO.java`
|
||||
|
||||
**Step 1: 读取当前 DTO 文件**
|
||||
|
||||
检查现有代码结构。
|
||||
|
||||
**Step 2: 重写 DTO 文件**
|
||||
|
||||
将整个文件替换为简化后的版本：
|
||||
|
||||
```java
|
||||
package com.ruoyi.ccdi.project.domain.dto;
|
||||
|
||||
import lombok.Data;
|
||||
import jakarta.validation.constraints.NotBlank;
|
||||
import jakarta.validation.constraints.NotNull;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* 模型参数保存DTO
|
||||
*/
|
||||
@Data
|
||||
public class ModelParamSaveDTO {
|
||||
|
||||
/** 项目ID */
|
||||
private Long projectId;
|
||||
|
||||
/** 模型编码 */
|
||||
@NotBlank(message = "模型编码不能为空")
|
||||
private String modelCode;
|
||||
|
||||
/** 参数列表 */
|
||||
@NotNull(message = "参数列表不能为空")
|
||||
private List<ParamValueItem> params;
|
||||
|
||||
@Data
|
||||
public static class ParamValueItem {
|
||||
|
||||
/** 参数编码 */
|
||||
@NotBlank(message = "参数编码不能为空")
|
||||
private String paramCode;
|
||||
|
||||
/** 参数值 - 唯一可修改字段 */
|
||||
@NotBlank(message = "参数值不能为空")
|
||||
private String paramValue;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: 保存文件**
|
||||
|
||||
确保文件保存成功。
|
||||
|
||||
---
|
||||
|
||||
## Task 2: 更新 Service 层类型引用
|
||||
|
||||
**Files:**
|
||||
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java`
|
||||
|
||||
**Step 1: 更新 for 循环中的类型引用**
|
||||
|
||||
找到第 105 行附近的代码，将：
|
||||
|
||||
```java
|
||||
for (ModelParamSaveDTO.ParamItem item : saveDTO.getParams()) {
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```java
|
||||
for (ModelParamSaveDTO.ParamValueItem item : saveDTO.getParams()) {
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: 简化前端请求参数
|
||||
|
||||
**Files:**
|
||||
- Modify: `ruoyi-ui/src/views/ccdi/modelParam/index.vue`
|
||||
|
||||
**Step 1: 找到 handleSave 方法中的 saveDTO 构建**
|
||||
|
||||
定位到第 119-133 行。
|
||||
|
||||
**Step 2: 简化请求参数**
|
||||
|
||||
将原有的 saveDTO 构建代码：
|
||||
|
||||
```javascript
|
||||
const saveDTO = {
|
||||
projectId: this.queryParams.projectId,
|
||||
modelCode: this.queryParams.modelCode,
|
||||
modelName: this.modelList.find(
|
||||
(m) => m.modelCode === this.queryParams.modelCode
|
||||
)?.modelName,
|
||||
params: modifiedParams.map((item) => ({
|
||||
paramCode: item.paramCode,
|
||||
paramName: item.paramName,
|
||||
paramDesc: item.paramDesc,
|
||||
paramValue: item.paramValue,
|
||||
paramUnit: item.paramUnit,
|
||||
sortOrder: item.sortOrder,
|
||||
})),
|
||||
};
|
||||
```
|
||||
|
||||
替换为简化版本：
|
||||
|
||||
```javascript
|
||||
const saveDTO = {
|
||||
projectId: this.queryParams.projectId,
|
||||
modelCode: this.queryParams.modelCode,
|
||||
params: modifiedParams.map((item) => ({
|
||||
paramCode: item.paramCode,
|
||||
paramValue: item.paramValue,
|
||||
})),
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: 编译后端验证
|
||||
|
||||
**Files:**
|
||||
- 无文件修改，仅验证
|
||||
|
||||
**Step 1: 编译后端项目**
|
||||
|
||||
```bash
|
||||
cd D:/ccdi/ccdi && mvn clean compile -DskipTests
|
||||
```
|
||||
|
||||
**Expected:** BUILD SUCCESS
|
||||
|
||||
**Step 2: 如有编译错误，检查类型引用**
|
||||
|
||||
确保所有 `ParamItem` 都已改为 `ParamValueItem`。
|
||||
|
||||
---
|
||||
|
||||
## Task 5: 功能测试验证
|
||||
|
||||
**Files:**
|
||||
- 无文件修改，仅验证
|
||||
|
||||
**Step 1: 启动后端服务**
|
||||
|
||||
```bash
|
||||
cd D:/ccdi/ccdi && mvn spring-boot:run
|
||||
```
|
||||
|
||||
等待服务启动完成。
|
||||
|
||||
**Step 2: 通过 Swagger 测试保存接口**
|
||||
|
||||
1. 访问 `http://localhost:8080/swagger-ui/index.html`
|
||||
2. 找到 `模型参数配置` 分组
|
||||
3. 测试 `/ccdi/modelParam/save` 接口
|
||||
4. 使用简化的请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"projectId": 0,
|
||||
"modelCode": "LARGE_TRANSACTION",
|
||||
"params": [
|
||||
{
|
||||
"paramCode": "SINGLE_AMOUNT",
|
||||
"paramValue": "50000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Expected:** 返回 `{"code": 200, "msg": "保存成功"}`
|
||||
|
||||
**Step 3: 验证参数已更新**
|
||||
|
||||
调用 `/ccdi/modelParam/list?projectId=0&modelCode=LARGE_TRANSACTION`
|
||||
|
||||
**Expected:** 返回的参数中 `SINGLE_AMOUNT` 的 `paramValue` 已更新为 `50000`
|
||||
|
||||
---
|
||||
|
||||
## Task 6: 提交代码
|
||||
|
||||
**Step 1: 查看变更**
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
```
|
||||
|
||||
**Step 2: 提交后端改动**
|
||||
|
||||
```bash
|
||||
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/ModelParamSaveDTO.java
|
||||
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiModelParamServiceImpl.java
|
||||
git commit -m "refactor: 简化 ModelParamSaveDTO，移除冗余字段"
|
||||
```
|
||||
|
||||
**Step 3: 提交前端改动**
|
||||
|
||||
```bash
|
||||
git add ruoyi-ui/src/views/ccdi/modelParam/index.vue
|
||||
git commit -m "refactor: 简化模型参数保存请求参数"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 改动摘要
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `ModelParamSaveDTO.java` | 移除 modelName，ParamItem 简化为 ParamValueItem（2字段） |
|
||||
| `CcdiModelParamServiceImpl.java` | 类型引用 ParamItem → ParamValueItem |
|
||||
| `index.vue` | 请求参数只保留 paramCode 和 paramValue |
|
||||
|
||||
**风险等级：** 低（向后兼容，纯简化重构）
|
||||
|
||||
---
|
||||
|
||||
**创建日期：** 2026-02-26
|
||||
Reference in New Issue
Block a user