架构内容与架构仓库：让决策成为可组合、可追踪的资产

一个架构项目结束后留下 200 页方案文档。半年后，新团队想确认库存平台为什么拥有预占责任，却只能在多个版本中搜索“库存”；想复用订单事件规范，又无法判断它是否仍然有效；想修改门店自提，却不知道会影响哪些能力、数据和应用。

问题不在于文档不够多，而在于架构决策没有被拆成可识别的工件、构建块和关系，也没有经过版本、适用范围和状态管理。架构内容框架负责定义“表达什么”，架构仓库负责管理“放在哪里、谁能复用、何时失效”。

先区分交付物、工件和构建块

概念	含义	零售案例
Deliverable 交付物	对干系人正式提交、评审和版本管理的工作成果	架构定义、迁移计划、合规评估
Artifact 工件	用特定视角表达架构的一张表、一幅图或一个模型	能力热力图、数据责任矩阵、应用交互图
Building Block 构建块	满足一组需求、可组合和复用的能力单元	库存承诺能力、事件发布能力、身份认证组件

一个交付物可以包含多个工件，一个工件可以描述多个构建块，同一个构建块也会出现在不同视角中。把三者混成“架构文档”，会失去复用和追踪能力。

Catalog、Matrix 和 Diagram 各有职责

架构工件常见三种表达：

工件类型	适合回答	示例
Catalog 目录	有哪些对象，它们的属性是什么	应用目录、数据对象目录、标准目录
Matrix 矩阵	两类对象之间是什么关系	能力-应用矩阵、应用-数据矩阵、角色-权限矩阵
Diagram 图示	对象如何组合、流动或随时间变化	数据流、应用交互、迁移状态、价值流

如果想判断“订单管理和库存平台分别能写什么数据”，应用目录不够，需要应用-数据矩阵。如果想解释支付完成后状态如何传播，矩阵不够，需要交互或事件流程图。工件形式应由关注点决定。

架构视图来自视角规则

视角定义建模规则，视图是针对具体架构实例生成的结果。例如“应用协作视角”规定要展示应用、接口、事件和依赖；“全渠道目标应用视图”则展示商城、订单、库存、支付和履约的具体关系。

同一个构建块可以出现在多个视图中：

• 库存平台在能力视图中承载库存承诺。
• 在数据视图中拥有锁定和释放事实。
• 在应用视图中提供预占接口和库存事件。
• 在技术视图中具有容量、分区和恢复要求。
• 在迁移视图中从影子计算逐步接管写入责任。

这些视图必须指向同一个架构对象，而不是分别复制一段文字。对象关系一致，修改影响才可追踪。

架构内容元模型连接不同架构域

内容元模型定义架构对象及其关系。针对零售案例，可以建立一条最小关系链：

业务驱动 DRV-02
  -> 业务结果 OUT-INV-01
  -> 业务能力 CAP-INVENTORY-COMMITMENT
  -> 数据对象 DATA-RESERVATION
  -> 应用组件 APP-INVENTORY
  -> 技术服务 TECH-EVENT-PLATFORM
  -> Gap GAP-INV-03
  -> 工作包 WP-INVENTORY-COMMITMENT
  -> 运行证据 EVD-OVERSELL-RATE

元模型的价值不是追求完整，而是确保关键决策可以跨域追踪。某个应用准备下线时，可以找到它承载的能力、拥有的数据、依赖的技术和关联的工作包，而不需要依赖个人记忆。

架构构建块与解决方案构建块

架构构建块（ABB）描述需要什么能力和行为，不绑定具体实现；解决方案构建块（SBB）描述使用什么产品、组件或部署实现。

层次	库存案例
ABB：库存承诺	对可售库存作出预占、释放和确认，保证同一范围不超额承诺
ABB：事件发布	事实提交后可靠发布，可重放、可追踪、兼容演进
SBB：库存服务	订单预占 API、库存状态机和分区存储实现
SBB：事件平台	具体消息集群、Schema Registry、Outbox 和监控实现

如果架构直接写成“使用 Kafka”，后续很难判断替换产品是否改变架构。如果先定义事件发布 ABB，再选择具体 SBB，就能把稳定需求与可替换实现分开。

构建块要有契约而不只是名称

一个可复用构建块至少应记录：

• 提供的能力和不提供的能力。
• 输入、输出、事件和依赖。
• 质量属性、容量和安全约束。
• 负责团队、生命周期和支持等级。
• 适用场景、禁止场景和已知取舍。
• 版本、兼容性和替换关系。
• 关联标准、示例和运行证据。

“统一认证组件”如果没有租户范围、身份类型、可用性和故障语义，就无法判断新项目能否复用。

架构仓库不是共享文件夹

架构仓库需要按内容性质组织，而不是按项目目录无限增长。可以包含：

仓库区域	保存内容	使用方式
架构元模型	对象、关系、命名和建模规则	保证跨项目表达一致
架构景观	Baseline、Target、过渡状态和应用组合	了解当前和计划状态
参考资料库	参考架构、模式、ABB 和 SBB	新项目复用已验证方案
标准信息库	技术标准、数据标准、生命周期和例外	方案选型与自动检查
治理日志	ADR、评审、例外、债务和一致性证据	理解决策与偏差
需求与追踪	驱动、要求、Gap、工作包和证据	跨阶段追踪影响

每个对象还要有 Owner、状态、版本、适用范围、最近验证时间和替代对象。没有生命周期信息的仓库会迅速变成历史资料堆积。

用 Enterprise Continuum 组织复用层次

Enterprise Continuum 可以理解为一种分类视角：从通用基础能力逐步走向组织和行业特定能力。

层次	示例
通用能力	身份认证、日志、消息、关系存储
通用系统模式	事件发布、主数据、可观测性、灾备
行业能力	零售商品、库存、订单、门店履约
企业特定能力	本企业会员等级、渠道配额、门店例外规则

越通用的构建块越容易复用，但业务含义越弱；越具体的构建块越贴近企业差异，但复用范围越小。分类能防止团队把企业特有规则硬塞进通用平台，也防止重复建设已有基础能力。

一个库存决策如何进入仓库

以“库存平台拥有预占最终裁决权”为例：

1. ADR 记录背景、候选方案、取舍和复审条件。
2. 数据责任矩阵标明库存锁定的业务 Owner 和权威应用。
3. 应用视图展示订单管理通过同步接口请求预占。
4. 事件目录定义 InventoryReserved、InventoryReleased 等事实。
5. 质量属性记录并发、幂等、恢复和审计要求。
6. 过渡视图描述新旧系统在每个迁移范围内的写入责任。
7. 标准目录登记接口、事件和数据库权限检查规则。
8. 运行证据关联超卖率、锁定超时和旧入口流量。

以后修改预占策略时，团队可以从 ADR 找到决策原因，从关系模型找到受影响对象，再决定是否修改原则、接口、事件、迁移计划或指标。

资产生命周期

架构资产也有生命周期：

草拟 -> 评审中 -> 已批准 -> 采用中 -> 已验证 -> 已弃用 -> 已归档

状态应有明确含义：

• 已批准表示决策通过，不代表已经落地。
• 采用中表示项目开始使用，需要收集实现反馈。
• 已验证表示有运行证据支持适用性。
• 已弃用表示不再推荐新项目使用，但存量仍可能存在。
• 已归档表示只保留历史和审计价值。

如果新团队只看到“最终版”文件，无法知道它是目标、正在采用还是已经失效。

仓库如何进入日常工程

仓库必须能被搜索、引用和自动检查：

• 项目模板引用当前有效的原则、标准和构建块。
• ADR 使用稳定 ID 关联能力、数据、应用和工作包。
• API 与事件 Schema 进入版本管理和兼容检查。
• 应用目录从部署或 CMDB 获取实际运行状态。
• 旧入口流量、数据质量和 SLO 回写架构状态。
• 标准废弃时能够找到所有采用者并生成迁移范围。

仓库内容如果完全依赖架构师手工维护，实际状态很快会与模型分离。稳定对象由人负责语义，运行事实尽量由工具采集。

最小交付物

• 适合当前范围的内容元模型和命名规则。
• 交付物、工件、ABB 和 SBB 的区分。
• 关键 Catalog、Matrix、Diagram 及其使用者。
• 资产 Owner、状态、版本、范围和替代关系。
• ADR、原则、标准、例外和运行证据的关联。
• 仓库更新、验证、弃用和归档流程。

常见失效方式

• 把完整性等同于文档长度，产物无法被查询和组合。
• 同一应用在多张图中使用不同名称和边界。
• ABB 与产品选型混在一起，稳定需求被具体工具绑死。
• 仓库只有“最终版”，没有采用、验证和弃用状态。
• 参考架构没有适用条件，项目机械复用。
• 所有模型手工维护，运行状态与架构景观长期漂移。
• 只保存设计，不保存取舍、例外和运行证据。

能力验证

• 能区分交付物、工件、ABB 和 SBB。
• 能根据关注点选择 Catalog、Matrix 或 Diagram。
• 能用最小内容元模型连接业务、数据、应用、技术和迁移。
• 能描述一个构建块的能力、契约、质量属性和生命周期。
• 能按适用范围和抽象层次组织参考资产。
• 能让架构仓库连接项目模板、契约检查和运行证据。

总结

架构内容框架让企业用一致对象和关系表达决策，架构仓库让这些决策具有版本、状态、适用范围和复用入口。它们的目标不是积累文档，而是让团队能够回答“为什么这样设计、谁正在使用、修改会影响什么、这个资产是否仍然有效”。当架构资产能够进入日常工程和运行反馈，组织才真正拥有可复用的架构能力。