zd_product_document/40-平台与架构/基础平台/功能模块/08-基础配置管理.md

5.8 基础配置管理

本文档从《基础平台产品设计》第 5 章拆分而来，用于独立描述基础平台功能模块的业务需求、规则和验收标准。

上级文档：基础平台产品设计

5.8.1 功能说明

基础配置管理用于维护基础平台运行所需的平台级参数、客户级差异化参数、应用级接入参数和基础开关。

基础配置不承载业务系统的复杂业务规则。业务规则、业务流程、业务单据规则应放在对应业务系统中维护，例如对账规则放在连锁业务对账系统，分账规则放在分账系统，支付渠道规则放在聚合支付系统。

基础配置 1.0 重点解决：

• 配置可查询。
• 配置可新增和修改。
• 配置可启用和停用。
• 配置变更可记录。
• 配置值可结构化维护。
• 配置版本冲突可识别和回滚。

5.8.2 功能范围

• 查询配置列表
• 查看配置详情
• 新增配置
• 编辑配置
• 启用 / 停用配置
• 维护配置值
• 查看配置版本
• 回滚配置版本
• 查看配置操作记录

5.8.3 配置项目目录

基础配置管理按配置场景拆分为独立文档。总览文档只保留模块边界、通用规则、入口结构、使用导航和统一验收标准；各配置项目的字段、控件和页面规则详见子文档。

配置项目目录：基础配置

编号	配置项目	独立文档
5.8.3.1	平台运行配置	01-平台运行配置.md
5.8.3.2	登录与安全配置	02-登录与安全配置.md
5.8.3.3	门户与应用容器配置	03-门户与应用容器配置.md
5.8.3.4	客户级配置	04-客户级配置.md
5.8.3.5	应用级接入配置	05-应用级接入配置.md
5.8.3.6	消息与通知配置	06-消息与通知配置.md
5.8.3.7	对象存储配置	07-对象存储配置.md
5.8.3.8	短信发送配置	08-短信发送配置.md
5.8.3.9	审计与日志配置	09-审计与日志配置.md
5.8.3.10	基础开关配置	10-基础开关配置.md
5.8.3.11	配置项管理	11-配置项管理.md
5.8.3.12	配置版本记录	12-配置版本记录.md

5.8.4 不建议纳入基础配置的内容

以下内容不建议放入基础配置管理，避免基础配置变成业务系统规则中心：

• 对账规则、差异处理规则、账单生成规则。
• 分账规则、结算周期、清分规则、出款规则。
• 支付通道费率、支付路由、退款规则。
• 门店选址模型参数、评分权重。
• 客服工单流转规则、补偿规则、客诉处理 SLA。
• 商品、菜单、价格、库存、营销活动规则。
• 组织架构、用户、角色、菜单本身的主数据。

上述内容应分别进入对应业务系统或对应基础模块维护。基础配置只维护基础平台运行所需的通用参数和开关。

5.8.5 字段要求

配置项基础信息至少包括：

字段	说明	是否必填
配置名称	配置项展示名称	是
配置编码	配置项唯一编码	是
配置分类	平台运行、登录安全、门户容器、客户配置、应用配置、消息通知、对象存储、短信发送、审计日志、业务开关	是
配置层级	平台级、客户级、应用级	是
所属客户	客户级配置所属客户	条件必填
所属应用	应用级配置所属应用	条件必填
配置值类型	JSON、文本、数字、布尔、枚举	是
配置值	配置实际内容	是
配置值预览	列表页展示的配置值摘要	否
版本	配置当前版本号	是
启用状态	启用、停用	是
备注	配置说明	否
创建时间	配置创建时间	是
更新时间	配置最近更新时间	是

5.8.5.1 配置编码规则

配置编码用于系统读取配置、版本管理和操作日志追踪。

编码规则：

• 配置编码在同一配置层级和归属范围内唯一。
• 平台级配置编码全局唯一。
• 客户级配置编码在同一客户下唯一。
• 应用级配置编码在同一应用下唯一。
• 配置编码创建后原则上不允许修改。
• 配置编码建议采用大写英文字母、数字和下划线组合。

编码示例：

配置分类	编码示例
登录安全	TOKEN_EXPIRE_MINUTES
登录安全	PASSWORD_COMPLEXITY_RULE
门户容器	MAX_OPEN_TAB_COUNT
对象存储	OBJECT_STORAGE_PROVIDER
短信发送	SMS_PROVIDER
审计日志	OPERATION_LOG_RETENTION_DAYS
基础开关	ENABLE_THIRD_PARTY_LOGIN

5.8.6 业务规则

• 平台级配置仅平台管理员维护。
• 客户级配置仅影响当前客户。
• 应用级配置仅影响对应应用。
• 配置编码保存时必须校验唯一性。
• 配置值保存前必须通过类型校验。
• JSON 类型配置保存前必须是合法 JSON。
• 配置启用后，业务功能读取启用状态配置。
• 配置停用后，系统应按默认值或上级配置执行；没有默认值时，需要提示配置不可用。
• 配置变更需要生成新版本。
• 配置保存时需要校验当前版本，避免多人同时编辑导致覆盖。
• 配置回滚时，需要生成新的配置版本，不直接覆盖历史版本。
• 配置变更、启用、停用、回滚需要记录操作日志。

5.8.7 界面入口与访问权限

基础配置管理作为基础平台管理功能，建议放置在基础平台左侧菜单，并按配置场景拆分页面：

基础平台
└── 基础配置管理
    ├── 平台运行配置
    ├── 登录与安全配置
    ├── 门户与应用容器配置
    ├── 客户级配置
    ├── 应用级接入配置
    ├── 消息与通知配置
    ├── 对象存储配置
    ├── 短信发送配置
    ├── 审计与日志配置
    ├── 基础开关配置
    └── 配置项管理

页面访问规则：

• 平台超级管理员可维护全部配置页面。
• 实施人员可按授权范围维护客户级配置和应用级接入配置。
• 客户管理员是否可维护客户级配置，由客户配置开关控制。
• 产品管理员可按授权范围维护其负责应用的应用级接入配置。
• 普通业务用户不可访问基础配置管理页面。
• 无基础配置管理权限的用户不展示基础配置管理菜单。

设计原则：

• 场景化配置页面面向实施、运维、客户管理员，使用业务化表单，不直接暴露 JSON。
• 配置项管理面向平台管理员和研发支持人员，作为底层配置项兜底维护页面。
• 常用配置应优先进入场景化页面，不应要求使用者记忆配置编码。
• 复杂结构化配置可在配置项管理中维护，但需要控制权限和操作审计。

5.8.8 使用导航

5.8.8.1 维护场景化配置

操作路径：

基础平台 > 基础配置管理 > 对应配置页面

操作步骤：

1. 进入基础配置管理。
2. 选择平台运行配置、登录与安全配置、门户与应用容器配置、客户级配置、应用级接入配置、消息与通知配置、对象存储配置、短信发送配置、审计与日志配置或基础开关配置。
3. 按页面表单维护对应配置。
4. 点击保存。
5. 系统校验配置值、版本号和权限范围。
6. 系统生成新版本并记录操作日志。

5.8.8.2 查询配置项

操作路径：

基础平台 > 基础配置管理 > 配置项管理

操作步骤：

1. 进入配置项管理页。
2. 按配置名称、配置编码、配置分类、配置层级、所属客户、所属应用或启用状态查询。
3. 在配置项列表中查看配置。

5.8.8.3 新增配置项

操作路径：

基础平台 > 基础配置管理 > 配置项管理 > 新增配置

操作步骤：

1. 进入配置项管理页。
2. 点击新增配置。
3. 系统打开配置新增 / 编辑抽屉。
4. 填写配置名称、配置编码、配置分类、配置层级。
5. 如为客户级配置，选择所属客户。
6. 如为应用级配置，选择所属应用。
7. 选择配置值类型并填写配置值。
8. 设置启用状态和备注。
9. 保存配置。
10. 系统创建配置、生成初始版本并记录操作日志。

5.8.8.4 编辑配置项

操作路径：

基础平台 > 基础配置管理 > 配置项管理 > 编辑

操作步骤：

1. 进入配置项管理页。
2. 查询目标配置。
3. 点击编辑。
4. 系统打开配置新增 / 编辑抽屉。
5. 修改配置名称、配置值、启用状态或备注。
6. 保存配置。
7. 系统校验配置值格式和版本号。
8. 系统生成新版本并记录操作日志。

5.8.8.5 启用 / 停用配置

操作路径：

基础平台 > 基础配置管理 > 配置项管理 > 启用 / 停用

操作步骤：

1. 进入配置项管理页。
2. 查询目标配置。
3. 点击启用或停用。
4. 停用配置时，系统提示配置停用影响。
5. 确认操作。
6. 系统更新配置状态、生成新版本并记录操作日志。

5.8.8.6 回滚配置版本

操作路径：

基础平台 > 基础配置管理 > 配置项管理 > 版本记录 > 回滚

操作步骤：

1. 进入配置项管理页或场景化配置页面。
2. 查询目标配置或打开当前配置的版本记录。
3. 查看配置历史版本。
4. 选择需要回滚的历史版本。
5. 点击回滚。
6. 系统二次确认回滚操作。
7. 系统生成新版本并记录操作日志。

5.8.9 验收标准

• 基础配置管理按配置场景拆分页面展示。
• 可维护平台运行配置、登录与安全配置、门户与应用容器配置、客户级配置、应用级接入配置、消息与通知配置、对象存储配置、短信发送配置、审计与日志配置、基础开关配置。
• 对象存储配置支持阿里云 OSS、腾讯云 COS、华为云 COS/OBS、MinIO、RustFS。
• 对象存储启用前必须完成连接测试。
• 对象存储 SecretKey 等敏感字段不得明文回显。
• 短信发送配置支持阿里云、腾讯云、华为云。
• 短信发送配置支持按模板场景维护短信模板。
• 同一短信模板场景同一时间只能启用一个模板。
• 短信发送 SecretKey、验证码等敏感信息不得写入操作日志。
• 场景化配置页面采用业务化表单，不要求用户直接编辑 JSON。
• 配置项管理可查询平台级、客户级、应用级配置。
• 配置项管理可新增、编辑、启用、停用配置。
• 配置编码按配置层级和归属范围校验唯一性。
• 配置值保存前按配置值类型完成格式校验。
• JSON 类型配置保存前必须校验为合法 JSON。
• 配置列表可展示配置值预览。
• 配置变更后生成新版本。
• 多人同时编辑同一配置时，系统可识别版本冲突。
• 可查看配置历史版本。
• 可回滚配置历史版本，回滚后生成新版本。
• 停用配置时能够提示配置影响。
• 平台级配置、客户级配置、应用级配置的维护权限正确。
• 配置新增、编辑、启用、停用、回滚均生成操作日志。