3、联动配置基础：联动配置的总体架构、配置项与配置参数、配置文件的组织方式
联动配置是“审查意见 → 传递单 → 变更记录”自动化流转的骨架。只有将配置项、配置参数与文件组织方式三者统一设计，才能实现传递单与变更记录之间的字段映射、状态同步与版本追溯。本节从总体架构出发，逐层拆解配置要素与文件结构。
3.1 联动配置的总体架构
联动配置采用三层分离架构，将业务逻辑、数据映射与文件存储解耦，便于在不同项目间复用配置模板。
架构层次说明：
- 业务层（Business Layer）：定义审查意见类型、传递单流转阶段、变更记录状态机等业务规则。
- 映射层（Mapping Layer）：建立传递单字段与变更记录字段之间的转换规则，包括字段映射、默认值、校验逻辑。
- 持久层（Persistence Layer）：管理配置文件的存储路径、版本号、依赖关系与加载顺序。
架构设计要点： 三层之间通过配置上下文（ConfigContext）传递数据，避免层间直接耦合。业务层变更时，只需调整映射规则，无需修改持久层文件结构。
3.2 配置项与配置参数
配置项是联动配置的最小单元，每个配置项包含一组配置参数。根据作用范围，配置项分为全局配置项、项目配置项和实例配置项三级。
| 配置项类型 | 作用范围 | 典型参数 | 优先级 |
|---|---|---|---|
| 全局配置项 | 所有项目共享 | 系统编码、日期格式、默认审批人 | 低（可被覆盖） |
| 项目配置项 | 单个项目内有效 | 项目编号、传递单模板、变更记录类型 | 中 |
| 实例配置项 | 单次传递单/变更记录 | 审查意见ID、关联变更单号、紧急程度 | 高（覆盖全局和项目） |
每个配置项由以下核心参数构成：
- key：配置项唯一标识，采用点分命名空间，如
mapping.transfer.change.status。 - value：配置值，支持字符串、数字、布尔、数组、对象等类型。
- scope：作用域标识，取值为
global、project、instance。 - version：配置项版本号，用于追踪变更历史。
- description：配置项说明，便于维护人员理解用途。
- dependencies：依赖的其他配置项列表，用于控制加载顺序。
配置参数示例（YAML 格式）：
mapping:
transfer:
change:
status:
key: "mapping.transfer.change.status"
value:
"已提交": "待处理"
"审批中": "处理中"
"已关闭": "已完成"
scope: "project"
version: "2.1.0"
description: "传递单状态到变更记录状态的映射表"
dependencies: ["system.status.base"]3.3 配置文件的组织方式
配置文件采用分层目录 + 命名空间的组织方式，确保配置文件的查找效率与可维护性。标准目录结构如下：
配置文件命名遵循 {命名空间}-{类型}.yaml 规范，便于按功能快速定位：
| 文件名 | 命名空间 | 内容说明 |
|---|---|---|
system.yaml |
system | 系统级参数，如编码、时区、日志级别 |
status-base.yaml |
status | 状态机基础定义，包括状态列表与转换规则 |
transfer-mapping.yaml |
transfer | 传递单字段与变更记录字段的映射关系 |
change-template.yaml |
change | 变更记录模板，定义必填字段与默认值 |
review-link.yaml |
review | 审查意见与传递单的关联规则 |
配置文件组织避坑指南：
- 禁止将不同项目的配置混放在同一目录下，必须按项目 ID 隔离。
- 全局配置中不要包含项目特定字段，否则会导致配置污染。
- 版本号建议采用 语义化版本（SemVer），如
2.1.0，便于判断兼容性。 - 依赖关系必须显式声明，避免隐式依赖导致加载顺序错误。
3.4 配置加载与合并策略
联动配置引擎在启动时按照全局 → 项目 → 实例的顺序加载配置文件，并采用深度合并（Deep Merge）策略将相同 key 的配置项合并。合并规则如下：
- 加载全局配置，作为基础配置上下文。
- 加载项目配置，与全局配置合并：项目配置中的 key 覆盖全局配置中的同名 key。
- 加载实例配置（运行时传入），与项目配置合并：实例配置优先级最高。
- 合并时，数组类型采用替换策略，对象类型采用递归合并策略。
合并示例（简化 JSON 表示）：
// 全局配置
{ "status.mapping": { "已提交": "待处理" }, "system.timeout": 30 }
// 项目配置
{ "status.mapping": { "已提交": "新建", "审批中": "处理中" }, "project.code": "PRJ-001" }
// 合并结果
{ "status.mapping": { "已提交": "新建", "审批中": "处理中" }, "system.timeout": 30, "project.code": "PRJ-001" }