用途:为 Latitude LLM 项目提供后台任务、领域事件与副作用的实现规范,适用于队列与 worker、领域事件发布、异步通知或投影,以及避免在 HTTP 处理器内直接执行这些工作。
主要能力与规则:领域代码通过领域级发布者抽象(端口)发出领域事件,而非在用例中直接调用邮件、HTTP 或 Slack。Worker 异步处理通知、集成与投影等 I/O。事件按聚合已发生的事实命名(如 ScoreCreated、ScoreStatusChanged),而非按消费者需求命名;每个状态转换只发一个规范事件,消费者自行过滤,去重键需包含生命周期区分符,载荷携带事实而非路由提示。
用法要点:任务载荷放 ID 或不透明存储键,worker 内重新获取权威状态,并显式处理过期或已删除实体。事务性领域事件通过 OutboxEventWriter 写入;高吞吐或非事务生产者可直接经 createEventsPublisher(queuePublisher) 发布。领域事件消费者应作为调度器,发布下游主题任务或启动工作流,不在事件处理器内联执行业务逻辑。复用现有异步轨道:BullMQ 队列 worker 位于 apps/workers,持久多步工作流位于 Temporal 支持的 apps/workflows。
延迟合并:PublishOptions 提供互斥的 debounceMs 与 throttleMs,均按 dedupeKey 合并重复发布。debounceMs 在静默 N 毫秒后触发,每次发布推迟触发时间并替换待发载荷;throttleMs 每个窗口最多触发一次,首次发布即排定时间,窗口内后续发布被丢弃,需 dedupeKey。若需求是“每 X 最多一次”,应使用 throttleMs,否则会静默饥饿。常量命名需与语义一致。
限制与注意:修改可能仍有在途运行的 Temporal 工作流属于版本化事件,重排、插入或删除活动会破坏重放并导致非确定性错误,需用 patched("<descriptive-id>") 或固定到新的 Worker Deployment Version。可靠性异步契约默认在领域事件载荷、主题/任务载荷与工作流输入中包含 organizationId 与 projectId,部分邮件与删除相关事件除外。新增外部系统时在 packages/platform/*-<provider> 添加具体提供者包,并在应用组合根按环境配置接线。其余细节暂未提供。