扩展接入

往平台上加一个新能力的传统姿势是：建个项目、写点代码、在某个巨无霸启动类里加几行注册、祈祷没人删掉。半年后没人说得清平台里到底有哪些执行面、哪些默认实现会静默吞掉生产流量。BitzOrcas 的扩展接入反其道而行——每个新增物都走同一套可重复、失败关闭、可观测、可测试的准入契约，由模板、源生成器、架构规则、测试门禁与文档共同守卫，因此同样的步骤对每个贡献者都产出同样的结果。

能力

EXT-2 值得单独一提：给生成器喂一份不完整的模块定义，产出的不是”半成品代码碰运气”，而是零 C# 输出加一份精确到缺失项的诊断清单，且不产生任何模板回流文件——坏输入在源头即被拒绝。

全局规则

1. Application 不依赖 HttpContext、ORM、CAP、Redis、RabbitMQ 或任何具体基础设施类型。
2. Host 仅是组合根与运行时接线——不含业务规则。
3. 新扩展默认失败关闭：无生产配置时，API Shell/JobHost 以稳定的关闭语义启动或给出 fail-fast 诊断。
4. 一个新扩展至少在以下之一可见：Operations、健康/配置诊断、trace/log/audit。
5. 一个新扩展要同步更新实现 + 架构测试 + 冒烟/集成测试 + 文档。CLI 不生成扩展代码。
6. 模块/聚合与用例 CLI 只把诊断清单写入 staging；直接写源码树会失败关闭。
7. 文档/代码冲突意味着先修门禁，再修实现/文档——绝不只是改文字。

模块接入

简单黄金路径从 Contracts（或独立 Domain owner）+ Application 起步。不要预先构建空的 Infrastructure/Endpoints。Request/Handler/简短 Rule 是局部的；Handler 编排调用方/租户、聚合行为、事件注册、保存与 Result。

模块身份通过编译期标记声明——owner 项目中一个 XxxModule.cs 标记类型加各 owner-local catalog：

namespace BitzOrcas.Platform.Tracker.Contracts;

using BitzOrcas.Modularity.Governance;

// 身份三件套：显示名、稳定 Code（权限前缀 {code}.{resource}.{action}）、基础命名空间。
[AppModule("Tracker", Code = "tracker", BaseNamespace = "BitzOrcas.Platform.Tracker")]
[DependsOn("Authorization")]   // 每条依赖边显式声明，杜绝隐式传递耦合
[DependsOn("Files")]
internal sealed class TrackerModule;

// 权限归属登记在 owner-local catalog；Governance Generator 在编译期读取两者，
// 生成实现 IModuleContributionProvider 的 GeneratedModuleContribution_Tracker，
// 其集合字段按 Ordinal 排序——目录输出因此逐字节确定、可 diff、可快照审计。

运行时不扫描 assembly：治理事实全部来自生成器投影。完整的标记语义、36 个现存口径与遗留账本棘轮见模块治理。

Endpoint/DI/ORM Fluent Config 由生成器拥有；简单聚合直接使用生成的 repository。

深层模块生长路径仅在真实复杂度出现时才扩展物理表面：用于 list/filter/pagination/projection 的独立公开 ReadModelStore；用于 join/group-by/report/外部查询的专用 QueryStore + 适配器；用于外部协议/资源生命周期/提供方不对称的 Infrastructure；仅当传输源生成器无法表达需求时才添加的瘦 Endpoint/API 适配器。过早拆分物理表面是另一种过度工程——先让切片跑通再让结构生长。

适配器接入

1. 在 Application 或 Contracts 中定义端口；端口不能暴露 IQueryable/DbContext/ISqlSugarClient/CAP/Redis/RabbitMQ。
2. 显式声明默认语义：
   • InMemory*——仅 API Shell/本地开发/测试，绝不用于生产。
   • Null*——有意的静默空操作（例如禁用的事件发布器）。
   • Unavailable*——大声失败/失败关闭；调用方得到稳定错误或 Result.Failure。
3. 默认/Unavailable 适配器通过 TryAdd* 注册；生产/可选适配器显式注册，覆盖默认。这样未配置的生产环境得到的是确定的空转或响亮的失败，而不是意想不到的实现抢注。
4. ORM 适配器使用 [RegisterOrmAdapter<TPort>]；生成器生成标准的失败关闭默认端口，由提供方契约/一致性测试验证。
5. 运行时可见性流入运维适配器探针、配置诊断与健康就绪——适配器的存在感最终体现在 /api/operations 的探针矩阵里。
6. 同步 platform 适配器矩阵与 ORM 能力矩阵；两者的漂移分别由 AdapterMatrixConsistencyTests 与 OrmAdapterParityTests 把守。

后台作业接入

作业位于 src/Hosts/BitzOrcas.JobHost；API Host 不承载定时任务。一个作业实现 IJob（或等价接口），把 Execute 路由经 QuartzJobExecutionAuditor 产出 Activity/CorrelationId/BackgroundJob 审计与结构化日志，JobHost 组合显式注册 JobKey、trigger、schedule 与 options。一个缺少持久化存储/Redis/OTLP 的类生产环境会快速失败或以配置诊断失败关闭。/api/operations/jobs 描述作业名、来源、启用状态、计划与运行时可见性。作业不得直接捕获 scoped 依赖——它们创建 scope 或使用安全生命周期的构造注入。

端点接入

端点使用 [GenerateEndpoint] 或 IEndpoint；路由 handler 是瘦协议适配器。授权默认开启；匿名需要理由与测试。业务授权位于 Application 的 IAuthorizedRequest/rule 中，不在端点。所有失败经 ResultExtensions.ToHttp 或统一异常处理器走到 ProblemDetails，CorrelationId 中间件自动应用。必需测试覆盖 401、403、成功/失败关闭、ProblemDetails 形状与 API 文档冒烟。

固定验证块

# 依次执行准入使用的构建、文档、架构、应用和 API 壳层门禁。
dotnet build BitzOrcas.Modern.slnx --no-restore
scripts/build/check-xml-files.sh --no-build
scripts/build/check-xml-comments.sh --no-build
# 架构回归与行为回归分别留证，便于定位准入失败。
dotnet test BitzOrcas.Architecture.Tests --no-build
dotnet test BitzOrcas.Application.Tests --no-build
dotnet test BitzOrcas.Integration.Tests --no-build --filter ApiShell
git diff --check

触及代码生成器、JobHost、工作流作业、模板或提供方适配器的切片需运行对应的附加测试。

另见

• 模块治理
• 质量门禁
• 新增模块
• 新增适配器