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

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 层

   <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 层

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

3. 前端层

   <!-- 表格只有"阈值设置"列使用 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