配置管理 PRD

文档信息

项目	内容
产品名称	PMForge - 配置管理
文档版本	v2.0
创建日期	2026-09-17
最后更新	2026-09-24
文档状态	评审中
优先级	P0

---

一、功能概述

1.1 功能定位

配置管理是 PMForge 平台基础设施层的核心模块，相当于整个系统的"控制面板"——所有运行时的可变参数都在这里集中管理，无需修改代码或重启服务就能调整系统行为。

模块包含两大子功能：

• 参数配置管理：管理平台运行过程中需要的各种"开关"和"数值"，比如用户注册是否开放、初始密码是什么、监控地址在哪里等。就像家里的遥控器，随时可以调整空调温度、切换频道，而不需要拆开机壳改线路。
• 数据源配置管理：管理平台连接的多个数据库。当业务需要读写分离、多库查询时，运维人员可以在这里动态添加新的数据库连接，系统会自动验证连接是否通畅，密码则自动加密保管。

1.2 目标用户

用户类型	使用场景	核心诉求
系统管理员	维护系统参数的增删改查、分类管理、缓存刷新	参数改了立刻生效，不用重启服务
运维工程师	管理多数据源配置、测试数据库连接、切换数据源	新数据库接上去之前能先验证通不通
应用开发者	通过 API 获取参数值、动态使用多数据源	代码里不用写死参数值，通过 key 就能拿到
安全审计员	审查敏感参数可见性设置、数据源密码加密存储情况	密码类参数前端看不到，数据源密码加密存储

1.3 业务价值

• 告别硬编码：所有参数集中管理，修改参数值不需要改代码、不需要重启服务，运营策略调整秒级生效
• 内置参数保护：系统初始化就带有的关键参数（如初始密码）标记为"系统内置"，不允许误删，保障系统稳定运行
• 敏感信息防泄漏：参数可设置"不可见"属性，前端接口查不到敏感值；数据源密码自动加密存储，即使数据库被拖库也看不到明文
• 高性能读取：参数值缓存到 Redis，前端获取参数值的响应时间从数据库查询的 200ms 降到 50ms 以内
• 数据源热插拔：新增数据库连接时系统自动测试连通性，不通就阻止保存，避免配了一个"假"数据源导致业务报错
• 配置导出审计：支持将参数列表导出 Excel，方便安全审计和配置核查

1.4 功能范围

功能分类	优先级	说明
参数配置 CRUD	P0	系统参数的创建、查询、编辑、删除
参数配置批量删除	P1	批量删除自定义参数
按参数键名查询参数值	P0	前端通过 key 获取参数值，不可见参数禁止返回
参数配置分页查询	P0	支持按名称、键名、类型、创建时间筛选
参数配置导出 Excel	P1	导出参数配置列表
参数配置缓存管理	P0	参数变更后自动刷新 Redis 缓存
数据源配置 CRUD	P0	数据源的创建、查询、编辑、删除
数据源配置批量删除	P1	批量删除数据源
数据源连接测试	P0	创建/更新数据源时自动校验连接可用性
数据源配置列表	P0	获取所有数据源列表（含 Master）
数据源密码加密	P0	密码字段使用 EncryptTypeHandler 加密存储

---

二、用户场景

2.1 用户角色

角色	描述	核心诉求
系统管理员老周	后台管理人员	维护系统参数配置，管理平台运行参数
运维工程师小吴	基础设施运维人员	管理多数据源配置，确保数据源连接正常
后端开发小韩	后端开发人员	通过 Service/API 获取参数值与数据源
安全审计员小赵	安全管理人员	审查参数可见性、密码加密等安全配置

2.2 使用场景

场景1：管理员新增"验证码有效期"参数

• 用户：系统管理员老周
• 场景：产品需求评审后，确定验证码有效期从 5 分钟改为 3 分钟 → 老周登录后台 → 进入"参数配置"页面 → 点击"新增" → 填写参数名称"验证码有效期"、参数分类"default"、参数键名"system.captcha.expire-time"、参数键值"180"、可见性"是"、备注"单位：秒" → 点击保存
• 期望：参数创建成功，参数值自动缓存到 Redis，前端验证码组件通过 key 即可获取到最新值"180"，下次用户请求验证码时生效
• 异常处理：如果参数键名已存在，提示"参数键名已存在，请修改"；如果参数键名为空，提示"参数键名不能为空"

场景2：管理员修改用户初始密码

• 用户：系统管理员老周
• 场景：安全合规检查发现默认初始密码"123456"太弱 → 老周进入参数配置 → 搜索"init-password" → 找到"system.user.init-password" → 点击编辑 → 将参数键值改为"Abc@1234" → 保存
• 期望：参数值更新成功，Redis 缓存自动刷新，后续新建的用户都使用新初始密码"Abc@1234"
• 异常处理：如果老周试图删除这个系统内置参数，系统提示"系统内置参数不允许删除"

场景3：前端通过 key 获取注册开关

• 用户：前端应用（自动调用）
• 场景：用户打开注册页面 → 前端自动调用"根据参数键名查询参数值"接口 → 传入 key="system.user.register-enabled" → 获取返回值"true" → 页面展示注册表单；如果返回"false"则隐藏注册入口
• 期望：接口在 50ms 内返回参数值（命中缓存），运营可随时在后台关闭注册而不需要前端发版
• 异常处理：如果参数不可见（visible=false），接口返回错误"该参数为不可见参数，不允许获取"，防止敏感信息泄露

场景4：运维工程师接入读写分离从库

• 用户：运维工程师小吴
• 场景：业务量增长，需要增加一个从库做读写分离 → 小吴进入"数据源配置"页面 → 点击"新增" → 填写数据源名称"slave-01"、连接地址"jdbc:mysql://192.168.1.100:3306/pmforge"、用户名"read_user"、密码"xxxxx" → 系统自动测试连接 → 连接成功后保存
• 期望：数据源创建成功，连接信息加密存储到数据库，应用代码可通过数据源名称"slave-01"动态切换到从库查询
• 异常处理：如果连接测试失败（如 IP 不通、密码错误），系统阻止保存并提示"数据源连接配置不正确"，小吴可根据错误信息排查网络或账号问题

场景5：运维工程师修改数据源连接信息

• 用户：运维工程师小吴
• 场景：数据库迁移到新服务器 → 小吴进入数据源配置 → 编辑目标数据源 → 修改连接地址、用户名、密码 → 系统自动验证新连接 → 验证通过后保存
• 期望：连接验证通过则更新成功，验证失败则阻止保存并提示错误原因，避免"改了配置但连不上"的情况
• 异常处理：如果新连接测试失败，系统保留旧配置不变，提示错误原因让小吴重新检查

场景6：安全审计员审查配置安全

• 用户：安全审计员小赵
• 场景：季度安全审计 → 小赵进入参数配置列表 → 筛选"不可见"参数 → 确认密码类参数（如初始密码、密钥）都设置了 visible=false → 进入数据源配置列表 → 确认密码字段显示为"****"脱敏 → 导出参数配置 Excel → 存档备查
• 期望：敏感参数前端接口无法获取，数据源密码加密存储且不在界面展示，审计结论合格

场景7：管理员批量清理废弃参数

• 用户：系统管理员老周
• 场景：年底系统清理 → 老周在参数配置列表勾选多个已废弃的自定义参数 → 点击"批量删除" → 二次确认 → 系统校验全部为自定义参数 → 删除成功
• 期望：批量删除成功，缓存自动刷新；如果列表中混入了系统内置参数，系统整体拒绝删除并提示"包含系统内置参数，不允许删除"

2.3 用户故事

编号	用户故事	验收标准	优先级
US-01	作为系统管理员，我希望能创建和管理参数配置，以便动态控制系统运行行为	① 创建参数后前端通过 key 可立即获取新值 ② 修改参数值后无需重启服务即生效 ③ 参数键名重复时阻止创建并提示	P0
US-02	作为系统管理员，我希望能按分类、名称、键名、类型检索参数，以便快速定位目标配置	① 输入关键词 500ms 内返回搜索结果 ② 支持按名称/键名模糊搜索 ③ 支持按类型（系统内置/自定义）筛选	P0
US-03	作为系统管理员，我希望能设置参数可见性，以便控制敏感参数不暴露给前端	① visible=false 的参数通过 get-value-by-key 接口返回错误 ② visible=true 的参数正常返回值 ③ 编辑可见性后立即生效	P0
US-04	作为系统管理员，我希望系统内置参数不可删除，以便保障系统稳定运行	① 单个删除系统内置参数时阻止并提示 ② 批量删除包含系统内置参数时整体拒绝 ③ 系统内置参数在列表中有明确标识	P0
US-05	作为前端开发者，我希望能通过参数键名直接获取参数值，以便在业务逻辑中使用	① 接口响应时间 < 50ms（命中缓存） ② 参数不存在时返回 null 不报错 ③ 不可见参数返回错误码	P0
US-06	作为运维工程师，我希望能管理多个数据源配置，以便支持多库、读写分离等场景	① 创建数据源后应用可立即使用 ② 列表包含 Master 数据源且固定在首位 ③ Master 数据源不可编辑/删除	P0
US-07	作为运维工程师，我希望创建/修改数据源时自动测试连接，以便确保配置的正确性	① 连接测试在 5s 内完成 ② 测试失败阻止保存 ③ 错误信息包含失败原因	P0
US-08	作为运维工程师，我希望能查看 Master 数据源信息，以便了解主库连接状态	① 列表中展示 Master 数据源（id=0） ② Master 数据源信息来自应用配置文件 ③ Master 不可编辑/删除	P0
US-09	作为系统，我需要在参数变更后自动刷新 Redis 缓存，以便保证数据一致性与高性能	① 创建/更新/删除后缓存同步刷新 ② 缓存刷新在接口返回前完成 ③ Redis 不可用时降级查库	P0
US-10	作为系统管理员，我希望能导出参数配置 Excel，以便进行配置核查与审计	① 导出当前筛选条件下的全部数据 ② 参数类型和可见性字段显示中文 ③ 1000 条以内 3s 内完成导出	P1
US-11	作为系统管理员，我希望能批量删除自定义参数，以便高效清理废弃配置	① 勾选多个参数一键删除 ② 包含系统内置参数时整体拒绝 ③ 删除后缓存自动刷新	P1
US-12	作为安全审计员，我希望数据源密码加密存储，以便防止凭据泄露	① 密码使用 EncryptTypeHandler 加密 ② 接口响应不返回密码字段 ③ 数据库中密码字段为密文	P0

---

三、功能需求

3.1 后台管理端 - 参数配置管理

3.1.1 功能清单

功能	优先级	权限标识	说明
参数配置列表（分页）	P0	infra:config:query	分页展示参数配置，支持搜索筛选
参数配置详情	P0	infra:config:query	查看参数配置详细信息
创建参数配置	P0	infra:config:create	创建新的参数配置
编辑参数配置	P0	infra:config:update	修改参数配置信息
删除参数配置	P0	infra:config:delete	删除自定义参数配置（内置参数不可删）
批量删除参数配置	P1	infra:config:delete	批量删除自定义参数配置
导出参数配置 Excel	P1	infra:config:export	导出参数配置列表 Excel
按参数键名查询参数值	P0	免鉴权（业务接口需要）	通过 key 获取参数值，不可见参数禁止返回

3.1.2 参数配置列表（分页查询）

页面描述：

业务规则：

规则编号	规则描述	为什么这样设计
R-01	默认按创建时间倒序排列	新创建的参数排在前面，方便管理员确认刚创建的配置
R-02	支持按参数名称模糊搜索	管理员可能只记得"初始密码"几个字，模糊搜索快速定位
R-03	支持按参数键名模糊搜索	开发者通常知道 key 的一部分，如"captcha"
R-04	支持按参数类型筛选（系统内置 1 / 自定义 2）	审计时可能需要只看自定义参数，或只看系统参数
R-05	支持按创建时间范围筛选	配合定期审计需求，查看某段时间新增的配置
R-06	参数键名（config_key）全局唯一，创建/编辑时校验唯一性	保证每个参数有唯一标识，避免 key 冲突导致取值错误
R-07	系统内置参数（type=1）在列表中通过标识列区分展示	让管理员一眼区分哪些是系统自带的、哪些是自定义的

数据字段：

字段名	类型	说明
id	Long	参数配置编号
category	String	参数分类
name	String	参数名称
key	String	参数键名
value	String	参数键值
type	Integer	参数类型（1-系统内置 2-自定义）
visible	Boolean	是否可见
remark	String	备注
createTime	LocalDateTime	创建时间

接口设计：

接口名称	请求方式	接口路径	说明
获取参数配置分页	GET	/admin-api/infra/config/page	获取参数配置分页列表
获取参数配置详情	GET	/admin-api/infra/config/get	获取参数配置详细信息

请求参数（分页查询）：

参数名	类型	必填	说明
name	String	否	参数名称（模糊匹配）
key	String	否	参数键名（模糊匹配）
type	Integer	否	参数类型（1-系统内置 2-自定义）
createTime	DateTime[]	否	创建时间范围
pageNo	Integer	是	页码
pageSize	Integer	是	每页条数

返回结果（分页）：

字段名	类型	说明
list[]	ConfigRespVO	参数配置列表
total	Long	总记录数

返回结果（详情）：

字段名	类型	说明
id	Long	参数配置编号
category	String	参数分类
name	String	参数名称
key	String	参数键名
value	String	参数键值
type	Integer	参数类型
visible	Boolean	是否可见
remark	String	备注
createTime	LocalDateTime	创建时间

3.1.3 创建参数配置

页面描述：

表单字段：

字段	类型	必填	校验规则	说明
参数分类	输入框	是	不能为空，最大50字符	参数所属分类标识，如"default""biz""url"
参数名称	输入框	是	不能为空，最大100字符	参数的显示名称，如"用户管理-账号初始密码"
参数键名	输入框	是	不能为空，最大100字符，全局唯一	参数的唯一标识键，如"system.user.init-password"
参数键值	输入框	是	不能为空，最大500字符	参数的实际值
是否可见	开关	是	-	可见参数允许前端通过 key 查询获取值；不可见参数为敏感参数，前端禁止获取
备注	文本域	否	-	参数配置的说明备注

业务规则：

规则编号	规则描述	为什么这样设计
R-01	参数键名全局唯一，创建时校验是否已存在，重复则报错	避免 key 冲突导致取值混乱，一个 key 只能对应一个值
R-02	新建参数自动设置为"自定义"类型（type=2）	系统内置参数仅通过初始化脚本写入，管理员手动创建的都是自定义参数
R-03	创建成功后自动刷新 Redis 参数缓存	保证前端立即能获取到新参数的值，不需要等待缓存过期
R-04	参数键名建议使用"模块.业务.字段"的点分隔命名规范	如 system.user.init-password，层级清晰，避免命名冲突
R-05	不可见参数（visible=false）通常为敏感参数	如密码、密钥等，设为不可见后前端接口无法获取，防止泄露

接口设计：

接口名称	请求方式	接口路径	说明
创建参数配置	POST	/admin-api/infra/config/create	创建参数配置

请求参数：

参数名	类型	必填	说明
category	String	是	参数分类，最大50字符
name	String	是	参数名称，最大100字符
key	String	是	参数键名，最大100字符
value	String	是	参数键值，最大500字符
visible	Boolean	是	是否可见
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Long	新创建的参数配置编号

3.1.4 编辑参数配置

页面描述：

• 弹窗/抽屉形式，预填现有数据
• 系统内置参数编辑时，参数键名字段为只读状态（不可修改）

表单字段：

字段	类型	必填	说明
参数分类	输入框	是	参数分类
参数名称	输入框	是	参数名称
参数键名	输入框	是	参数键名（系统内置参数不可修改键名）
参数键值	输入框	是	参数键值
是否可见	开关	是	是否可见
备注	文本域	否	备注

业务规则：

规则编号	规则描述	为什么这样设计
R-01	参数键名不可与其他参数重复（排除自身）	保证全局唯一性
R-02	编辑完成后自动刷新 Redis 参数缓存	修改的值立即生效，前端下次请求就能拿到新值
R-03	系统内置参数（type=1）允许编辑参数值，但不允许修改参数键名	键名是代码中引用的标识，改了键名代码就找不到了；但值可以按需调整
R-04	将可见参数改为不可见后，前端将无法再通过 key 获取该参数值	这是一个安全控制手段，管理员需要知晓此影响

接口设计：

接口名称	请求方式	接口路径	说明
更新参数配置	PUT	/admin-api/infra/config/update	更新参数配置

请求参数：

参数名	类型	必填	说明
id	Long	是	参数配置编号
category	String	是	参数分类
name	String	是	参数名称
key	String	是	参数键名
value	String	是	参数键值
visible	Boolean	是	是否可见
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Boolean	是否成功

3.1.5 删除参数配置

业务规则：

规则编号	规则描述	为什么这样设计
R-01	逻辑删除，不物理删除	保留数据可追溯，支持误删恢复
R-02	删除前需二次确认	防止误操作
R-03	系统内置参数（type=1）不允许删除	系统运行依赖这些参数，删了可能导致功能异常
R-04	批量删除时，若列表中包含系统内置参数，整体拒绝删除并提示	避免批量操作中混入系统参数被误删
R-05	删除后自动刷新 Redis 参数缓存	保证缓存与数据库一致

接口设计：

接口名称	请求方式	接口路径	说明
删除参数配置	DELETE	/admin-api/infra/config/delete	删除单个参数配置
批量删除参数配置	DELETE	/admin-api/infra/config/delete-list	批量删除参数配置

请求参数（删除）：

参数名	类型	必填	说明
id	Long	是	参数配置编号

请求参数（批量删除）：

参数名	类型	必填	说明
ids	List<Long>	是	参数配置编号列表

3.1.6 参数配置导出

业务规则：

规则编号	规则描述
R-01	支持 xls 格式
R-02	导出当前筛选条件下的全部参数配置
R-03	导出字段包含：参数配置序号、参数分类、参数名称、参数键名、参数键值、参数类型、是否可见、备注、创建时间
R-04	参数类型与是否可见字段使用字典转换显示（如 1->系统内置，true->是）

接口设计：

接口名称	请求方式	接口路径	说明
导出参数配置 Excel	GET	/admin-api/infra/config/export-excel	导出参数配置列表

请求参数：

参数名	类型	必填	说明
name	String	否	参数名称筛选
key	String	否	参数键名筛选
type	Integer	否	参数类型筛选
createTime	DateTime[]	否	创建时间范围

3.1.7 按参数键名查询参数值

业务规则：

规则编号	规则描述	为什么这样设计
R-01	通过参数键名（key）查询对应参数值（value）	前端通过 key 动态获取系统配置，不需要硬编码
R-02	仅可见参数（visible=true）允许返回给前端；不可见参数返回错误提示	保护敏感参数不暴露给前端
R-03	参数不存在时返回 null，不报错	前端可根据 null 值做默认处理，不会因为参数缺失而页面报错
R-04	优先从 Redis 缓存读取，缓存未命中时查库	高性能读取，响应时间 < 50ms
R-05	该接口用于前端动态获取系统配置	如注册开关、验证码有效期等，运营可随时调整

接口设计：

接口名称	请求方式	接口路径	说明
根据参数键名查询参数值	GET	/admin-api/infra/config/get-value-by-key	通过 key 获取参数值

请求参数：

参数名	类型	必填	说明
key	String	是	参数键名，如"system.user.init-password"

返回结果：

字段名	类型	说明
data	String	参数键值；参数不存在时返回 null

错误码：

错误码	说明
CONFIG_GET_VALUE_ERROR_IF_VISIBLE	该参数为不可见参数，不允许获取

---

3.2 后台管理端 - 数据源配置管理

3.2.1 功能清单

功能	优先级	权限标识	说明
数据源配置列表	P0	infra:data-source-config:query	展示所有数据源（含 Master）
数据源配置详情	P0	infra:data-source-config:query	查看数据源详细信息（密码脱敏）
创建数据源配置	P0	infra:data-source-config:create	创建新的数据源，自动测试连接
编辑数据源配置	P0	infra:data-source-config:update	修改数据源信息，自动测试连接
删除数据源配置	P0	infra:data-source-config:delete	删除数据源配置
批量删除数据源配置	P1	infra:data-source-config:delete	批量删除数据源

3.2.2 数据源配置列表

页面描述：

业务规则：

规则编号	规则描述	为什么这样设计
R-01	列表自动包含 Master 数据源（id=0），Master 数据源从应用配置文件中读取	Master 是系统启动就确定的主数据库，需要在界面上可见
R-02	Master 数据源固定在列表首位，名称显示为"主数据源"标识	让运维人员一眼看到主库信息，排在最前面符合重要性优先级
R-03	密码字段不在响应中返回，防止凭据泄露	即使管理员账号被盗，也看不到数据库密码
R-04	Master 数据源（id=0）不可编辑、不可删除	Master 信息来自 application.yml 配置文件，通过界面修改会导致配置文件与数据库不一致

数据字段：

字段名	类型	说明
id	Long	数据源编号（Master 为 0）
name	String	数据源名称
url	String	数据源连接地址
username	String	用户名
createTime	LocalDateTime	创建时间

接口设计：

接口名称	请求方式	接口路径	说明
获得数据源配置列表	GET	/admin-api/infra/data-source-config/list	获取所有数据源配置列表
获得数据源配置详情	GET	/admin-api/infra/data-source-config/get	获取单个数据源配置详情

请求参数（详情）：

参数名	类型	必填	说明
id	Long	是	数据源编号

返回结果（列表）：

字段名	类型	说明
data[]	DataSourceConfigRespVO	数据源配置列表（首条为 Master）

返回结果（详情）：

字段名	类型	说明
id	Long	数据源编号
name	String	数据源名称
url	String	数据源连接地址
username	String	用户名
createTime	LocalDateTime	创建时间

3.2.3 创建数据源配置

页面描述：

表单字段：

字段	类型	必填	校验规则	说明
数据源名称	输入框	是	不能为空	数据源的显示名称，如"slave-01"
数据源连接	输入框	是	不能为空	JDBC 连接字符串，如"jdbc:mysql://127.0.0.1:3306/pmforge"
用户名	输入框	是	不能为空	数据库用户名
密码	密码框	是	不能为空	数据库密码，提交后加密存储

业务规则：

规则编号	规则描述	为什么这样设计
R-01	创建时自动测试数据库连接可用性（通过 JdbcUtils.isConnectionOK 校验）	避免配了一个连不上的数据源，后续业务使用时才报错
R-02	连接测试失败时阻止创建，返回错误提示"数据源连接配置不正确"	不通的连接没有保存的意义，提前拦截减少运维排查成本
R-03	密码使用 EncryptTypeHandler 加密后存储到数据库	即使数据库被非法访问，密码也是密文，保障安全
R-04	数据源名称建议使用英文标识	如 slave-01、report-db 等，代码中通过名称引用数据源
R-05	支持的数据库类型包括 MySQL、PostgreSQL、Oracle、SQL Server 等	平台支持 10 种数据库，数据源配置同样兼容

接口设计：

接口名称	请求方式	接口路径	说明
创建数据源配置	POST	/admin-api/infra/data-source-config/create	创建数据源配置

请求参数：

参数名	类型	必填	说明
name	String	是	数据源名称
url	String	是	数据源连接地址
username	String	是	数据库用户名
password	String	是	数据库密码

返回结果：

字段名	类型	说明
data	Long	新创建的数据源编号

错误码：

错误码	说明
DATA_SOURCE_CONFIG_NOT_OK	数据源连接配置不正确，连接测试失败

3.2.4 编辑数据源配置

页面描述：

• 弹窗/抽屉形式，预填现有数据
• 密码字段显示为占位符，需重新输入才更新

表单字段：

字段	类型	必填	说明
数据源名称	输入框	是	数据源名称
数据源连接	输入框	是	JDBC 连接字符串
用户名	输入框	是	数据库用户名
密码	密码框	是	数据库密码

业务规则：

规则编号	规则描述	为什么这样设计
R-01	编辑时同样自动测试数据库连接可用性	修改后的连接信息必须验证通过才能保存
R-02	连接测试失败时阻止更新	避免保存无效配置
R-03	密码重新加密存储	保证数据库中始终存储密文
R-04	Master 数据源（id=0）不允许通过此接口修改	Master 信息需通过修改 application.yml 并重启服务来更新

接口设计：

接口名称	请求方式	接口路径	说明
更新数据源配置	PUT	/admin-api/infra/data-source-config/update	更新数据源配置

请求参数：

参数名	类型	必填	说明
id	Long	是	数据源编号
name	String	是	数据源名称
url	String	是	数据源连接地址
username	String	是	数据库用户名
password	String	是	数据库密码

返回结果：

字段名	类型	说明
data	Boolean	是否成功

3.2.5 删除数据源配置

业务规则：

规则编号	规则描述	为什么这样设计
R-01	逻辑删除，不物理删除	保留数据可追溯
R-02	删除前需二次确认	防止误操作
R-03	Master 数据源（id=0）不允许删除	主数据源是系统运行的基础，不可删除
R-04	删除前建议检查是否有业务模块正在使用该数据源	正在使用的数据源被删会导致业务异常
R-05	批量删除时同样校验是否包含 Master 数据源	批量操作也要保护主数据源

接口设计：

接口名称	请求方式	接口路径	说明
删除数据源配置	DELETE	/admin-api/infra/data-source-config/delete	删除单个数据源配置
批量删除数据源配置	DELETE	/admin-api/infra/data-source-config/delete-list	批量删除数据源配置

请求参数（删除）：

参数名	类型	必填	说明
id	Long	是	数据源编号

请求参数（批量删除）：

参数名	类型	必填	说明
ids	List<Long>	是	数据源编号列表

错误码：

错误码	说明
DATA_SOURCE_CONFIG_NOT_EXISTS	数据源配置不存在

---

3.3 后台管理端 - 参数配置缓存管理

3.3.1 功能说明

参数配置缓存管理机制是确保参数读取高性能的核心支撑。通过 Redis 缓存，避免每次参数读取都访问数据库，大幅提升系统响应速度。

缓存策略：

策略项	说明
缓存介质	Redis
缓存粒度	按参数键名（config_key）缓存对应的参数值
缓存写入时机	服务启动时预加载全部参数到 Redis
缓存失效策略	主动失效（参数创建/更新/删除时清除缓存）
缓存穿透防护	缓存未命中时回源数据库查询

缓存刷新流程：

参数配置变更（创建/更新/删除）
    -> 执行数据库操作
    -> 清除 Redis 中对应参数键名的缓存
    -> 下次请求时自动从数据库重新加载并写入缓存

服务启动
    -> 从数据库加载全部参数配置
    -> 批量写入 Redis 缓存

业务规则：

规则编号	规则描述	为什么这样设计
R-01	服务启动时自动预加载全部参数配置到 Redis 缓存	避免服务刚启动时大量请求穿透到数据库
R-02	参数配置的创建/更新/删除操作完成后，自动刷新对应 key 的缓存	保证前端获取到最新值，不会出现"改了但没生效"的情况
R-03	缓存刷新为同步操作，保证接口返回时缓存已更新	接口返回成功后前端立即可以读到新值
R-04	如果 Redis 不可用，应降级为直接查询数据库，不影响业务	Redis 是加速手段而非必须，不能因为 Redis 挂了系统就不能用
R-05	参数配置表标注 @TenantIgnore，不参与租户隔离，缓存数据为全局共享	参数配置是系统级配置，不分租户

---

3.4 配置管理最佳实践

3.4.1 参数命名规范

规范	说明	示例
点分隔层级命名	使用"层级.模块.属性"格式	system.user.init-password
层级分类	第一级表示所属系统域	system.（系统级）、biz.（业务级）、url.（链接类）
全小写+连字符	参数键名使用全小写，单词间用连字符	system.user.register-enabled
参数分类规范	category 使用简短英文标识	default、biz、url

3.4.2 参数分类建议

分类	用途	典型参数
default	通用系统参数	用户初始密码、注册开关
biz	业务参数	业务规则阈值、功能开关
url	外部链接/地址参数	监控地址、文档地址
security	安全相关参数（不可见）	密钥、Token 有效期

3.4.3 数据源管理最佳实践

实践项	说明
命名规范	数据源名称使用"角色-序号"格式，如 master、slave-01、report-db
连接池配置	建议通过应用配置文件统一管理连接池参数，数据源配置仅管理连接信息
密码安全	密码字段使用 EncryptTypeHandler 加密存储，前端不展示密码
连接测试	创建/修改数据源时必须通过连接测试，避免配置无效数据源
Master 保护	Master 数据源（id=0）从应用配置文件读取，不可通过后台修改或删除
最小权限原则	为不同数据源分配最小必要权限的数据库账号
定期巡检	定期检查各数据源连接状态，及时发现并处理异常

3.4.4 安全建议

建议项	说明
敏感参数不可见	涉及密码、密钥、Token 等敏感参数的 visible 设为 false
操作审计	参数配置与数据源配置的增删改操作应记录操作日志
权限最小化	参数管理与数据源管理权限仅授予必要人员
变更审批	重要参数变更建议经过审批流程，避免误操作
备份机制	定期备份参数配置数据，防止误删导致系统异常

---

四、非功能需求

4.1 性能要求

指标	要求	说明
参数配置分页查询响应时间	< 200ms	常规列表查询
按参数键名查询参数值（命中缓存）	< 50ms	Redis 缓存命中场景
按参数键名查询参数值（未命中缓存）	< 200ms	回源数据库查询
数据源配置列表响应时间	< 200ms	数据源数量通常不多
数据源连接测试耗时	< 5s	包含网络连通性检测
参数配置导出耗时（1000条以内）	< 3s	Excel 文件生成
服务启动时参数预加载耗时	< 2s（1000条以内数据）	启动时全量加载到 Redis
参数缓存刷新耗时	< 100ms	单个 key 的缓存清除

4.2 安全要求

要求	说明	实现方式
权限控制	参数配置与数据源配置接口严格按权限标识控制访问	RBAC 权限校验
敏感参数保护	不可见参数（visible=false）禁止通过接口返回给前端	get-value-by-key 接口校验 visible 字段
密码加密存储	数据源密码使用 EncryptTypeHandler 加密存储到数据库	MyBatis-Plus TypeHandler 自动加解密
密码脱敏展示	数据源配置响应中不返回密码字段	VO 层不包含 password 字段
操作日志	所有配置管理操作记录操作日志	操作日志切面自动记录
参数校验	所有输入参数进行合法性校验，防止 SQL 注入与 XSS 攻击	参数校验注解 + 过滤器
连接测试	数据源创建/更新时必须通过连接测试	JdbcUtils.isConnectionOK 校验
数据一致性	参数配置变更与缓存刷新保证最终一致性	同步刷新缓存，接口返回前完成

4.3 兼容性要求

端	要求
PC 浏览器	Chrome 80+、Firefox 75+、Safari 13+
数据库	MySQL 5.7+、PostgreSQL 12+、Oracle 12c+、SQL Server 2017+、Kingbase、DM8
Redis	Redis 5.0+

---

五、数据设计

5.1 数据模型

5.1.1 参数配置表（infra_config）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	参数主键
category	VARCHAR(50)	NOT NULL	参数分类
type	TINYINT	NOT NULL	参数类型（1-系统内置 2-自定义）
name	VARCHAR(100)	NOT NULL, DEFAULT ''	参数名称
config_key	VARCHAR(100)	NOT NULL, DEFAULT ''	参数键名
value	VARCHAR(500)	NOT NULL, DEFAULT ''	参数键值
visible	BIT(1)	NOT NULL	是否可见
remark	VARCHAR(500)	-	备注
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记（0-未删除 1-已删除）

注意：该表标注 @TenantIgnore，不进行租户隔离，参数配置为全局共享。

索引设计：

索引名	字段	类型	说明
idx_config_key	config_key	NORMAL	按参数键名查询，加速 key 查找

业务约束（代码层）：

约束	说明
config_key 唯一	代码层校验参数键名全局唯一（非数据库唯一约束，因逻辑删除场景需要兼容）

5.1.2 数据源配置表（infra_data_source_config）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	主键编号
name	VARCHAR(100)	NOT NULL, DEFAULT ''	数据源名称
url	VARCHAR(1024)	NOT NULL	数据源连接地址
username	VARCHAR(255)	NOT NULL	数据库用户名
password	VARCHAR(255)	NOT NULL, DEFAULT ''	数据库密码（加密存储）
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记（0-未删除 1-已删除）

注意：该表标注 @TenantIgnore，不进行租户隔离，数据源配置为全局共享。

索引设计：

索引名	字段	类型	说明
PRIMARY	id	CLUSTERED	主键索引

加密字段说明：

字段	加密方式	说明
password	EncryptTypeHandler	MyBatis-Plus 类型处理器，写入时自动加密，读取时自动解密。对业务代码透明，开发者像操作普通字符串一样操作密码字段

5.1.3 数据模型 ER 关系

说明：两张表均为独立实体表，不存在外键关联关系。参数配置管理运行时参数，数据源配置管理数据库连接。

5.2 数据字典

5.2.1 参数类型枚举（infra_config_type）

类型值	类型名称	说明
1	系统内置（SYSTEM）	系统初始化时通过脚本写入的参数，不可删除
2	自定义（CUSTOM）	管理员通过后台创建的参数，可增删改

5.2.2 系统初始参数配置示例

参数分类	参数名称	参数键名	参数键值	可见	类型
biz	用户管理-账号初始密码	system.user.init-password	123456	否	系统内置
url	MySQL 监控的地址	url.druid	(空)	是	自定义
url	SkyWalking 监控的地址	url.skywalking	(空)	是	自定义
url	Spring Boot Admin 监控的地址	url.spring-boot-admin	(空)	是	自定义
biz	用户注册是否开启	system.user.register-enabled	true	是	系统内置

5.3 数据流转关系

操作	涉及的表	数据流转
创建参数配置	infra_config	校验 key 唯一 -> 插入记录（type=CUSTOM） -> 刷新 Redis 缓存
编辑参数配置	infra_config	校验存在 -> 校验 key 唯一（排除自身） -> 更新记录 -> 刷新 Redis 缓存
删除参数配置	infra_config	校验存在 -> 校验非 SYSTEM 类型 -> 逻辑删除 -> 刷新 Redis 缓存
批量删除参数配置	infra_config	批量校验非 SYSTEM 类型 -> 批量逻辑删除 -> 刷新 Redis 缓存
按 key 查询参数值	infra_config / Redis	优先读 Redis 缓存 -> 未命中则查库 -> 校验 visible -> 返回 value
创建数据源配置	infra_data_source_config	测试连接 -> 加密密码 -> 插入记录
编辑数据源配置	infra_data_source_config	校验存在 -> 测试连接 -> 加密密码 -> 更新记录
删除数据源配置	infra_data_source_config	校验存在 -> 逻辑删除
获取数据源列表	infra_data_source_config + 应用配置	查询 DB 列表 -> 在首位插入 Master 数据源（从应用配置读取）
获取数据源详情	infra_data_source_config / 应用配置	id=0 则返回 Master 信息 -> 否则从 DB 读取

---

六、跨模块联动

6.1 联动模块总览

配置管理作为基础设施模块，为多个业务模块提供底层支撑：

联动模块	联动方式	说明
用户管理	参数配置提供初始密码	创建用户时读取 system.user.init-password 作为初始密码
认证授权	参数配置控制注册开关	登录/注册页面读取 system.user.register-enabled 决定是否开放注册
监控运维	参数配置提供监控地址	监控页面读取 url.druid、url.skywalking 等跳转地址
数据权限	数据源配置提供多库支持	多数据源场景下，不同业务可切换到不同数据源查询
日志审计	操作日志记录配置变更	参数和数据源的增删改操作记录到操作日志
租户管理	配置全局共享	参数和数据源配置标注 @TenantIgnore，不分租户

6.2 关键联动流程

6.2.1 用户创建时的参数读取流程

6.2.2 数据源切换流程

6.3 数据一致性要求

场景	一致性要求	实现方式
参数值修改后前端获取	强一致性	同步刷新 Redis 缓存，接口返回前缓存已更新
数据源创建后业务使用	最终一致性	数据源创建成功后注册到 DynamicDataSource，可能有短暂延迟
参数删除后前端获取	强一致性	删除操作同步清除缓存，前端再次获取时返回 null

---

七、附录

7.1 名词解释

术语	英文	解释	类比
参数配置	Config	系统运行过程中需要的各种"开关"和"数值"，可以在后台随时修改	就像电视遥控器上的各种设置——亮度、音量、频道，随时可以调
参数键名	Config Key	每个参数的唯一标识符，代码通过它来读取参数值	就像门牌号，通过门牌号找到对应的住户
参数键值	Config Value	参数的实际值，如"true""123456""300"	门牌号对应的住户名字
参数可见性	Visible	控制参数是否允许前端获取。不可见的参数通常是密码、密钥等敏感信息	就像有些房间挂了"请勿进入"的牌子，前台访问时被拦住
系统内置参数	System Config	系统初始化时就存在的参数，不允许删除，但可以修改值	就像房子的承重墙，不能拆掉但可以重新粉刷
自定义参数	Custom Config	管理员在后台手动创建的参数，可以自由增删改	就像自己添置的家具，想搬进来就搬进来，想扔就扔
数据源	Data Source	一个数据库连接的配置信息，包含地址、用户名、密码等	就像一根水管，连接到不同的水源（数据库）
Master 数据源	Master DataSource	主数据源，系统启动时从配置文件读取，id=0，不可通过界面修改	就像家里的总水阀，是主要供水来源，不能随便关
连接测试	Connection Test	创建/修改数据源时，系统自动尝试连接数据库，验证配置是否正确	就像新装水管后先开水试试漏不漏水
密码加密存储	Password Encryption	数据源密码在数据库中存储为密文，读取时自动解密	就像把贵重物品放进保险箱，用的时候再打开
Redis 缓存	Redis Cache	将参数值暂存在 Redis 中，避免每次都查数据库，大幅提升读取速度	就像把常用工具放在手边，不用每次去工具箱翻
缓存刷新	Cache Refresh	参数修改后清除 Redis 中的旧值，下次读取时从数据库重新加载	就像改了电话号码后把通讯录里的旧号码删掉，下次联系时重新存
@TenantIgnore	Tenant Ignore	标注该数据不参与租户隔离，所有租户共享同一份数据	就像大楼的总电闸，所有租户共用，不属于任何一户
EncryptTypeHandler	Encrypt Type Handler	MyBatis-Plus 的类型处理器，写入数据库时自动加密，读取时自动解密，对业务代码透明	就像一个自动上锁的抽屉，放进去自动锁上，拿出来自动解锁
JDBC 连接字符串	JDBC URL	数据库连接地址，包含协议、主机、端口、数据库名等信息	就像快递地址——"XX省XX市XX路XX号"，告诉系统去哪里找数据库
逻辑删除	Logical Delete	不真正从数据库中删除数据，而是标记 deleted=1，查询时自动过滤	就像把文件放进"回收站"，看起来没了但还能恢复

7.2 接口汇总

模块	接口名称	方式	路径
参数配置	获取参数配置分页	GET	/admin-api/infra/config/page
参数配置	获取参数配置详情	GET	/admin-api/infra/config/get
参数配置	创建参数配置	POST	/admin-api/infra/config/create
参数配置	更新参数配置	PUT	/admin-api/infra/config/update
参数配置	删除参数配置	DELETE	/admin-api/infra/config/delete
参数配置	批量删除参数配置	DELETE	/admin-api/infra/config/delete-list
参数配置	导出参数配置 Excel	GET	/admin-api/infra/config/export-excel
参数配置	按参数键名查询参数值	GET	/admin-api/infra/config/get-value-by-key
数据源配置	获得数据源配置列表	GET	/admin-api/infra/data-source-config/list
数据源配置	获得数据源配置详情	GET	/admin-api/infra/data-source-config/get
数据源配置	创建数据源配置	POST	/admin-api/infra/data-source-config/create
数据源配置	更新数据源配置	PUT	/admin-api/infra/data-source-config/update
数据源配置	删除数据源配置	DELETE	/admin-api/infra/data-source-config/delete
数据源配置	批量删除数据源配置	DELETE	/admin-api/infra/data-source-config/delete-list

7.3 错误码汇总

错误码	说明	触发场景
CONFIG_NOT_EXISTS	参数配置不存在	编辑/删除时 ID 对应的记录不存在
CONFIG_KEY_DUPLICATE	参数键名重复	创建/编辑时 config_key 已存在
CONFIG_CAN_NOT_DELETE_SYSTEM_TYPE	系统内置参数不允许删除	尝试删除 type=1 的参数
CONFIG_GET_VALUE_ERROR_IF_VISIBLE	该参数为不可见参数，不允许获取	查询不可见参数的值
DATA_SOURCE_CONFIG_NOT_EXISTS	数据源配置不存在	编辑/删除时 ID 对应的记录不存在
DATA_SOURCE_CONFIG_NOT_OK	数据源连接配置不正确	创建/编辑时连接测试失败

7.4 权限配置

权限标识	说明	关联操作
infra:config:query	查看参数配置	查看列表、详情、按 key 查值
infra:config:create	创建参数配置	创建参数
infra:config:update	修改参数配置	编辑参数
infra:config:delete	删除参数配置	删除参数、批量删除
infra:config:export	导出参数配置	导出 Excel
infra:data-source-config:query	查看数据源配置	查看列表、详情
infra:data-source-config:create	创建数据源配置	创建数据源
infra:data-source-config:update	修改数据源配置	编辑数据源
infra:data-source-config:delete	删除数据源配置	删除数据源、批量删除

7.5 变更记录

版本	日期	变更内容
v1.0	2026-09-26	初稿
v2.0	2026-09-19	全面重写：增强用户场景（7个命名角色场景）、用户故事验收标准（12条）、ASCII 页面线框图（3张）、业务规则增加设计理由、缓存架构流程图、跨模块联动（6个模块）、名词解释（16项）、数据流转关系表、错误码汇总