本页介绍 BitzOrcas 事件系统背后的抽象层。实际的 CAP 基础设施位于事件——这里记录使系统可测试且独立于基础设施的契约和端口。

领域事件

领域事件是 Mediator 管道中 DomainEventDispatchPipelineBehavior 分发的进程内事件：

// 定义在 BitzOrcas.Domain
public abstract record DomainEvent;

// 示例：Sandbox 模块
public record NoteCreatedDomainEvent(Guid NoteId, string Title) : DomainEvent;

生命周期

聚合在命令执行期间调用 AddDomainEvent(event)
DomainEventDispatchPipelineBehavior 在处理器执行后收集事件
事件在事务提交之后分发
处理器在同一请求范围内处理事件

与集成事件的关键区别

方面	领域事件	集成事件
范围	进程内（同一请求）	跨进程（通过消息代理）
传输	Mediator 管道	CAP + RabbitMQ
契约位置	`BitzOrcas.Domain`	`BitzOrcas.SaaS.Contracts`
事务性	同一数据库事务	CAP Outbox（最终一致性）
处理器特性	无（自动发现）	`[CapSubscribe]`

集成事件契约

BitzOrcas.SaaS.Contracts 是包含所有跨模块事件定义的共享程序集：

BitzOrcas.SaaS.Contracts/
├── Auditing/           → 审计跟踪事件
├── Catalog/            → 计划/订阅目录事件
├── Chat/               → 频道/消息/成员事件
├── Files/              → 文件上传/删除事件
├── Notifications/      → 通知投递请求
├── PlatformBilling/    → 发票/订阅/用量事件
├── Tickets/            → 工单生命周期事件
└── Webhooks/           → Webhook 事件信封 + 签名辅助

契约是纯 DTO——无行为、无基础设施依赖。API 宿主和 JobHost 都引用此程序集。

INotificationPublisher 端口

public interface INotificationPublisher
{
    Task PublishAsync<T>(T @event, CancellationToken ct = default)
        where T : notnull;
}

实现

实现	模式	行为
`NullNotificationPublisher`	默认（无数据库）	空操作 — 事件静默丢弃
`CapNotificationPublisher`	生产（有 CAP）	发布到 CAP Outbox 由 RabbitMQ 投递

Null 模式支持API Shell 模式——整个应用无需 RabbitMQ 即可启动，适用于单元测试和本地开发。

其他事件相关端口

端口	用途
`IFileEventPublisher`	文件上传/删除事件
`ICatalogEventPublisher`	目录计划变更
`IChatEventPublisher`	聊天消息事件
`ITicketEventPublisher`	工单生命周期事件
`IPlatformBillingEventPublisher`	计费/订阅事件

每个都遵循相同的 Null/Production 模式——在 CoreRuntime 中注册空操作默认值，在 PersistenceAdapters 中由基于 CAP 的实现覆盖。

Webhook 事件类型注册表

public interface IWebhookEventTypeRegistry
{
    IReadOnlySet<string> RegisteredTypes { get; }
    bool IsRegistered(string eventType);
}

默认：InMemoryWebhookEventTypeRegistry — 静态配置的事件类型
WebhookEventTypes 中的事件定义可用的订阅目标

事件命名约定

所有集成事件遵循 {module}.{entity}.{action} 模式：

ticket.created          — 新工单创建
ticket.assigned         — 工单分配给代理
ticket.commented       — 添加评论
ticket.status_changed  — 状态转换
chat.message_sent      — 新聊天消息
file.uploaded          — 文件资源创建
billing.invoice_paid   — 发票付款收到

事件抽象层