ccdi/doc/参数配置功能/设计文档.md

# 模型参数配置功能 - 设计文档

## 1. 功能概述

### 1.1 功能定位

模型参数配置管理功能,用于配置风险监测模型的阈值参数,支持多模型参数管理,为未来的项目级自定义参数预留扩展能力。

### 1.2 核心能力

- ✅ 支持多模型参数配置(大额交易、可疑兼职、可疑外汇等)
- ✅ 参数持久化存储到数据库
- ✅ 按模型查询和修改参数
- ✅ 只允许修改阈值,其他信息只读
- ✅ 为未来项目级配置预留扩展能力

### 1.3 用户场景

1. **系统管理员** 选择需要配置的模型
2. **系统管理员** 修改模型的阈值参数
3. **系统管理员** 保存配置,参数立即生效

---

## 2. 需求分析

### 2.1 业务需求

根据需求截图,系统需要支持多个风险监测模型的参数配置:

**模型清单:**

- 大额交易模型
- 可疑兼职模型
- 可疑外汇交易模型
- (未来可能新增其他模型)

**参数特征:**

- 每个模型有固定数量的参数项(3-6个不等)
- 每个参数包含:监测项名称、描述、阈值设置、单位
- 只有阈值可以修改,其他信息只读

### 2.2 功能需求

| 需求项   | 说明                     |
|-------|------------------------|
| 数据存储  | 参数配置需要持久化存储到数据库        |
| 参数项管理 | 参数项固定,在开发时确定,后期不频繁增减   |
| 新增模型  | 需要开发介入,通过代码和数据库脚本实现    |
| 权限控制  | 统一权限控制,有菜单权限即可修改所有模型参数 |
| 修改历史  | 不需要记录修改历史,只保存当前状态      |
| 恢复默认  | 不需要开发恢复默认功能            |
| 其他功能  | 只需要基本的查询、修改、保存功能       |

### 2.3 非功能需求

| 需求项  | 说明                          |
|------|-----------------------------|
| 性能   | 单表查询,响应时间 < 500ms           |
| 安全性  | 后端只能修改阈值字段,其他字段不可修改         |
| 可扩展性 | 预留 project_id 字段,支持未来的项目级配置 |
| 易用性  | 界面简洁,操作直观                   |

---

## 3. 架构设计

### 3.1 模块架构

**新建模块:** `ccdi-project`

**模块定位:** 项目相关功能模块,包含参数配置等项目管理功能

**依赖关系:**

```
ruoyi-admin (启动模块)
    ├── ruoyi-framework
    ├── ruoyi-system
    ├── ruoyi-common
    ├── ccdi-project (新建模块) ⭐
    │   └── ruoyi-common
    └── ruoyi-info-collection
```

### 3.2 分层架构

```
前端 (Vue.js)
    ↓ HTTP请求
Controller (CcdiModelParamController)
    ↓ 调用
Service (ICcdiModelParamService)
    ↓ 调用
Mapper (CcdiModelParamMapper)
    ↓ SQL
Database (ccdi_model_param)
```

---

## 4. 数据库设计

### 4.1 表结构

**表名:** `ccdi_model_param`

```sql
CREATE TABLE `ccdi_model_param` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `project_id` bigint DEFAULT 0 COMMENT '项目ID(0表示默认参数,其他值为具体项目ID)',
  `model_code` varchar(100) NOT NULL COMMENT '模型编码',
  `model_name` varchar(100) NOT NULL COMMENT '模型名称',
  `param_code` varchar(100) NOT NULL COMMENT '参数编码',
  `param_name` varchar(100) NOT NULL COMMENT '监测项名称',
  `param_desc` varchar(500) DEFAULT NULL COMMENT '参数描述',
  `param_value` varchar(200) NOT NULL COMMENT '参数值',
  `param_unit` varchar(50) DEFAULT NULL COMMENT '参数单位',
  `sort_order` int DEFAULT 0 COMMENT '排序号(参数展示顺序)',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_project_model_param` (`project_id`, `model_code`, `param_code`) COMMENT '同一项目下模型参数唯一',
  KEY `idx_project_id` (`project_id`) COMMENT '项目ID索引',
  KEY `idx_model_code` (`model_code`) COMMENT '模型编码索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='模型参数配置表';
```

### 4.2 字段说明

| 字段名             | 类型           | 说明          | 是否可修改       |
|-----------------|--------------|-------------|-------------|
| id              | bigint       | 主键ID        | ❌           |
| project_id      | bigint       | 项目ID(0=默认)  | ❌           |
| model_code      | varchar(100) | 模型编码        | ❌           |
| model_name      | varchar(100) | 模型名称        | ❌           |
| param_code      | varchar(100) | 参数编码        | ❌           |
| param_name      | varchar(100) | 监测项名称       | ❌           |
| param_desc      | varchar(500) | 参数描述        | ❌           |
| **param_value** | varchar(200) | **参数值(阈值)** | ✅ **唯一可修改** |
| param_unit      | varchar(50)  | 参数单位        | ❌           |
| sort_order      | int          | 排序号         | ❌           |
| create_by       | varchar(64)  | 创建者         | ❌           |
| create_time     | datetime     | 创建时间        | ❌           |
| update_by       | varchar(64)  | 更新者         | 自动          |
| update_time     | datetime     | 更新时间        | 自动          |
| remark          | varchar(500) | 备注          | ❌           |

### 4.3 索引设计

| 索引名                    | 索引类型 | 字段                                 | 用途      |
|------------------------|------|------------------------------------|---------|
| PRIMARY                | 主键   | id                                 | 主键索引    |
| uk_project_model_param | 唯一索引 | project_id, model_code, param_code | 保证参数唯一性 |
| idx_project_id         | 普通索引 | project_id                         | 加速项目查询  |
| idx_model_code         | 普通索引 | model_code                         | 加速模型查询  |

### 4.4 初始化数据

参见开发计划文档中的数据初始化脚本。

---

## 5. 后端设计

### 5.1 模块结构

```
ccdi-project/
├── pom.xml
└── src/main/
    ├── java/com/ruoyi/ccdi/project/
    │   ├── controller/
    │   │   └── CcdiModelParamController.java
    │   ├── service/
    │   │   ├── ICcdiModelParamService.java
    │   │   └── impl/
    │   │       └── CcdiModelParamServiceImpl.java
    │   ├── mapper/
    │   │   └── CcdiModelParamMapper.java
    │   └── domain/
    │       ├── CcdiModelParam.java
    │       ├── dto/
    │       │   ├── ModelParamQueryDTO.java
    │       │   └── ModelParamSaveDTO.java
    │       └── vo/
    │           ├── ModelParamVO.java
    │           └── ModelListVO.java
    └── resources/
        └── mapper/ccdi/project/
            └── CcdiModelParamMapper.xml
```

### 5.2 核心接口

| 接口路径                       | 方法   | 说明            |
|----------------------------|------|---------------|
| /ccdi/modelParam/modelList | GET  | 查询模型列表        |
| /ccdi/modelParam/list      | GET  | 查询指定模型的参数列表   |
| /ccdi/modelParam/save      | POST | 保存参数配置(只更新阈值) |

### 5.3 安全保障

**三层防护确保只能修改阈值:**

1. **Mapper XML 层**
   ```xml
   <update id="batchUpdateParamValues">
       update ccdi_model_param
       set param_value = #{item.paramValue},  <!-- 只更新这个字段 -->
           update_by = #{item.updateBy},
           update_time = sysdate()
       where id = #{item.id}
   </update>
   ```

2. **Service 层**
   ```java
   // 只设置需要更新的字段
   updateParam.setParamValue(item.getParamValue());
   updateParam.setUpdateBy(username);
   updateParam.setUpdateTime(now);
   // 其他字段不设置
   ```

3. **前端层**
   ```vue
   <!-- 表格只有"阈值设置"列使用 el-input -->
   <el-table-column label="阈值设置" width="200">
     <template #default="{ row }">
       <el-input v-model="row.paramValue" />
     </template>
   </el-table-column>
   ```

---

## 6. 前端设计

### 6.1 页面布局

```
┌─────────────────────────────────────┐
│ 模型参数管理        ← 返回项目管理  │
├─────────────────────────────────────┤
│ 模型名称: [下拉选择]  [查询]       │
├─────────────────────────────────────┤
│ 阈值参数配置                        │
│ ┌─────┬──────┬────────┬────┐      │
│ │监测项│ 描述 │阈值设置 │单位│      │
│ ├─────┼──────┼────────┼────┤      │
│ │单笔 │单笔超│[输入框] │ 元 │      │
│ │交易额│该金额│        │    │      │
│ └─────┴──────┴────────┴────┘      │
├─────────────────────────────────────┤
│ [保存配置]                          │
└─────────────────────────────────────┘
```

### 6.2 交互流程

1. 用户选择模型 → 点击"查询"
2. 系统加载该模型的参数列表
3. 用户修改阈值(只有这一列可编辑)
4. 用户点击"保存配置"
5. 系统提交修改的参数值
6. 保存成功后显示提示

### 6.3 用户体验优化

- 修改跟踪:只提交变更的参数
- 防重复提交:保存中禁用按钮
- 成功提示:保存成功后清空修改标记

---

## 7. 实施计划

本功能拆分为以下3个子任务,每个子任务有独立的开发计划:

1. **数据库设计与后端实体类创建** - 参见 `01-数据库设计与后端实体类创建.md`
2. **后端业务逻辑开发** - 参见 `02-后端业务逻辑开发.md`
3. **后端功能测试** - 参见 `03-后端功能测试.md`
4. **前端代码开发** - 参见 `04-前端代码开发.md`

---

## 8. 风险与应对

| 风险        | 影响 | 应对措施                |
|-----------|----|---------------------|
| 参数值格式不统一  | 中  | 前端验证输入格式,后端也做校验     |
| 并发修改冲突    | 低  | 使用乐观锁或最后修改覆盖策略      |
| 新增模型需要改代码 | 低  | 符合设计预期,通过数据库脚本和代码发布 |

---

## 9. 未来扩展

### 9.1 项目级参数配置

通过 `project_id` 字段预留了扩展能力:

- `project_id = 0`: 系统默认参数
- `project_id > 0`: 具体项目的自定义参数

**扩展步骤:**

1. 添加项目管理界面
2. 允许用户为具体项目复制默认参数
3. 修改参数时指定 `project_id`

### 9.2 参数修改历史

如需添加审计功能:

1. 创建 `ccdi_model_param_history` 表
2. 在更新参数前先插入历史记录
3. 提供历史查询界面

---

## 10. 附录

### 10.1 参考文档

- 若依框架官方文档
- 项目 CLAUDE.md 规范文档
- 需求截图(见 doc/参数配置功能/ 目录)

### 10.2 术语说明

| 术语         | 说明                      |
|------------|-------------------------|
| 模型         | 风险监测模型,如大额交易模型、可疑兼职模型等  |
| 参数         | 模型的阈值配置项,如单笔交易额、累计交易额等  |
| 阈值         | 参数的具体数值,是唯一可修改的字段       |
| project_id | 项目ID,用于区分系统默认参数和项目自定义参数 |

---

**文档版本:** v1.0
**创建日期:** 2026-02-26
**创建人:** Claude Code