0028 领域事件经任务队列投递,审计记录与变更同事务
- 状态:已接受(2026-10-30)
- 相关:设计文档 04 §4、05 §4.4;03(A01、A02、A08);ADR 0006、0015、0024、0027
背景
2026-10-30 的全量审查发现两处架构与设计文档不一致:
- Hook 总线只有
settings.changed一个事件。 M1–M3 的模块都没有声明领域 Hook,也没有 outbox。04 §1 把"插件平台的地基在 v1 就位"列为第一阶段目标,Event.Emit的注释也写着"durable at-least-once delivery through the outbox table arrives with the job queue in M1",实际没有做。等插件运行时(第二阶段)再往每个服务里补,成本会高得多,也难保证"同一事件两处参数一致"(BS C18)。 - 管理操作的审计写在事务外。
/api/v1与兼容 BS 的管理接口共用的辅助函数(ADR 0024)先调用服务、再写审计,写审计失败只打一条日志。管理员同时改名和转移角色是两个事务,可能只成功一半。这和 03 A01"handler → service 是唯一业务入口"不一致。
决策
- 领域事件经任务队列投递(outbox):
hook.Event[P].Publish(ctx, bus, tx, payload)在变更所在的事务里往jobs表写一条hook.event任务(载荷是事件名@版本、投递键与 JSON)。事件和变更同时提交或同时回滚。- 任务执行器
Bus.Deliver按当时注册的处理器依次调用;任何一个失败,整条任务按队列的退避重试(1、5、15、60 分钟),所有处理器再收到一次。处理器用hook.DeliveryKey(ctx)识别重复投递,同一事件每次投递的键相同。第 5 次仍失败的事件标记为 failed,留在jobs表里供排查,不再投递。所以"至少一次"指的是重试期内。事件之间不保证顺序。 - 发布时没有处理器就不写任务,所以现在没有插件时不增加任何写入。
Emit只用于进程内的通知(settings.changed,各节点自己重载)。 - 事件最长约 5 秒后投递(队列的轮询间隔),没有专门唤醒执行器。
- 事件目录(
internal/hook/catalog.go,名称取自 05 §4.4,都是@1):- 用户:
user.registered(method:password / setup / social:提供方)、user.banned、user.deleted。 - 角色:
player.created、player.renamed(带oldName)、player.updated(穿戴变化或换了主人;包括因材质删除、移出衣柜、改为私有而被脱下)、player.deleted。 - 材质:
texture.uploaded、texture.updated、texture.deleted。 - 衣柜:
closet.added、closet.removed。 - 举报:
report.submitted、report.resolved。 - 载荷只放 id 和监听者判断要不要处理所需的少量字段(例如 CDN 刷新需要角色名),其它信息监听者自己通过服务读取。字段可以增加;改名、删除或改变含义要升版本并写 ADR(CONTRIBUTING)。
- 暂不发布:
user.loggedIn、user.updated、score.changed、yggdrasil.joined。它们在热路径上,等有插件需要时再加。Guard 与 Filter 随插件运行时(第二阶段)一起加,到时再定调用点和拒绝时的 HTTP 映射。
- 用户:
- 审计记录与变更同事务:
- 新包
internal/audit(Entry、Write)。账号服务原有的审计写入改为调用它。 - 做管理操作的服务方法接收
*audit.Entry,在自己的事务里写入,并补上只有事务里才知道的信息(举报涉及的上传者、退还的积分、新通知的 id、改名前后的名字)。用户自己的操作传nil。 - 覆盖:后台与兼容接口的角色改名/转移、换材质、删除,衣柜放入/取出,材质的管理员编辑与删除(只有改的是别人的材质时才写),处理举报,发通知/公告,保存设置(命令行的
settings set也记录,meta.via = "cli")。 - 管理员同时改名和转移角色改为
player.Service.Edit一个事务完成。
- 新包
备选方案
- 发布事件时直接
Emit(进程内、尽力而为):进程崩溃或事务回滚都会丢失事件,或发出没发生过的事件。 - 单独建
outbox表:jobs已经有租约、退避、清理,再建一张只是重复。 - 通过 context 隐式携带审计记录、由统一的事务助手写入:调用方看不出一个操作会写什么,和"显式的领域服务 + 事务"(03 A08)相悖。
影响
- 服务构造函数不变,事件总线通过
SetHooks注入(app.Core里设置),测试里不注入就不发布。 - 审计参数让若干服务方法多了一个参数(列表见 ADR 0027)。
- 文档站的插件开发页面在第二阶段由这份目录生成 Hook 参考。
- 第二阶段上线插件之前要解决:
- 事件与邮件共用一个按顺序执行的任务执行器,一个慢的处理器(每个最多 30 秒)会让验证邮件、重置邮件排在它后面。要给事件单独的执行器或并发度。
texture.*事件的载荷含私有材质的 hash(凭 hash 能取到文件),订阅它的插件需要相应的权限声明(05 §8)。