架构决策记录（ADR）捕捉做出某项选择的原因、拒绝了哪些替代方案、哪些已被取代。它们是代码背后持久的推理；代码才是实现。当文档、测试与实现不一致时，以最新的 Accepted ADR 为准。

ADR 分类法

每个 ADR 属于五个层级之一。

层级	是什么	如何被保护
Constitution	长期不变量（Native AOT、模块边界、双 ORM 一致性、显式管线）	架构测试 / verify gate
Strategy	当前主路径策略（repository/store、统一聚合、Mapperly、深层模块）	保护意图，而非可替换的实现
Migration	迁移期机制（兼容适配器、遗留白名单、assembly 映射规格）	必须声明 owner、过期时间与删除条件
Historical	仅作为背景保留的被取代决策	无当前约束力
Reference	使用手册/playbook	不是 ADR——位于 `docs/guides` 或 `docs/architecture`

编号与生命周期

编号按类别分段：Governance 00xx、Foundation 01xx、Modularity 02xx、Persistence 03xx、Cross-cutting 04xx、Security 05xx、Operations 06xx、Capabilities 07xx、Superseded/Historical 99xx。文件名为 <category>-<kebab-title>.md。每个类别目录是规范位置；ADR 根只放索引。

核心原则：架构测试保护不变量，而非实现。强制某种文件形状（*Entity.cs、手写 Search*Query）或把兼容适配器/白名单当作成功状态的测试会被删除或降级。Migration 层规则必须是可删除的——每条都声明 owner、范围、过期时间、删除条件、当前阻塞，以及其测试是棘轮还是永久门禁。

核心架构决策全景溯源矩阵

此处公布与系统交付、安全合规、多租户运维与模块化设计最核心的九大架构决策及其工程映射关系：

ADR 编号	核心决策意图	层级	源码落地目录	守护门禁 / 测试套件
0001——架构规则生命周期	架构规则分级分类与迁移棘轮治理	Constitution	`tests/ArchitectureTests/`	`ArchUnitExtensions` 永久门禁
0002——生产就绪门禁	阻断假代码、死锁与未处理异常的发布红线	Constitution	`scripts/deploy/`	`verify-gates.sh` / 错误预算
0102——Native AOT 约束	极致冷启动性能、低内存消耗与剪裁兼容	Constitution	`src/Framework/`	`<PublishAot>true</PublishAot>` 编译检验
0103——源生成器替代反射	编译期元数据分析彻底替代运行时反射	Strategy	`src/Framework/*.SourceGenerator`	零反射动态加载断言测试
0203——物理目录结构	Framework 底座与 Modules 业务域物理单向隔离	Constitution	`src/Modules/Sandbox`	`ModuleDependencyTests` 跨层物理拦截
0205——商业包扩展模型	商业私有包原子发布与客户无侵入二次开发	Strategy	`src/Profiles/`	`ConsumerContractTests` 独立隔离测试
0503——签名商业许可	ES256 非对称加密与物理硬件指纹绑定授权	Constitution	`src/Framework/BitzOrcas.Licensing.Runtime`	硬件机器码哈希比对与不可篡改审计
0504——社区许可策略	30人以内内建社区权益的计量与软硬期限管理	Strategy	`src/Framework/BitzOrcas.Licensing.Contracts`	席位计量与超限优雅降级
0605——私有 NuGet 供应链	凭据自动轮换、包签名验证与 SBOM 软件物料清单	Strategy	`scripts/ci/`	NuGet 签名与包篡改检测

完整目录与决策溯源

源代码仓库在九个类别下持有 31 个 ADR。此处尚未发布的类别（持久化 03xx、横切 04xx、除 0605 外的运维 06xx、能力 07xx、被取代 99xx）可在源仓库的 docs/adr/ 树中查阅。

ADR 分类法

编号与生命周期

核心架构决策全景溯源矩阵

完整目录与决策溯源

相关实战推荐 (Related Deep Dives)

另见