Macro teams crate 团队事件生产者与 teammate-dm 消费者实战指南

原创2026-10-30 13:45:141,733 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

Macro teams crate 团队事件生产者与 teammate-dm 消费者实战指南

Macro 的 teams crate 同时承担两件事:维护团队模型、持久化端口、服务策略与 HTTP 适配层,以及把成功的团队变更翻译成可被下游消费的 Kafka 事件。本文以该 crate 的说明文档为骨架,结合源码逐层拆解 macro.teams 主题的事件契约、投递语义、teammate-dms 消费者的实现细节与 backfill_teammate_dms 运维命令,帮助你在不破坏兼容性的前提下接入或排查这条事件链。

读完本文你将掌握:如何正确解读十种团队事件的载荷与字段含义;生产端为什么是"至多一次"而消费端是"至少一次";以及当 teammate DM 缺失时如何安全地做幂等回填。

crate 的职责边界与代码分层

teams crate 采用清晰的 domain / inbound / outbound 分层结构:

Cargo feature 划分了编译面:crates/teams/Cargo.toml 中 default = ["ai_tools", "axum", "inbound", "outbound", "ports"],而 backfill_binary 是一个独立 feature,它把 channels/outbound、database_env_vars、macro_entrypoint 等依赖引入,只为回填二进制服务:

[[bin]]
name = "backfill_teammate_dms"
path = "src/bin/backfill_teammate_dms.rs"
required-features = ["backfill_binary"]

这意味着普通的 cargo test 不会构建回填工具,避免把 channels 的写路径拖进团队 crate 的默认构建。

事件契约:主题、Key 与信封

所有事件发布到 macro.teams 主题。主题名在 crates/macro_event_topics/src/lib.rs 中集中声明:

/// Team lifecycle, invite, and membership events.
MacroTeamsTopic => "macro.teams",

该文件被注释说明"也被基础设施代码程序化抓取,以确保所有 Kafka topic 都被创建"——这正是后文上线顺序要求"先部署 Kafka-cluster 栈"的根源。

Key 是团队裸 UUID

每条记录的 Kafka key 是团队裸 UUID 字符串,不带任何前缀,例如 3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90。这一约定在构造器中被强制实现:

fn new(team_id: Uuid, event: TeamTopicEvent) -> Self {
    Self::with_event(team_id.to_string(), Event::new(event))
}

Key 不属于 JSON 信封的一部分,只参与分区与压缩。因此同一团队的事件落在同一分区、按团队内顺序投递;不同团队之间的顺序未被定义。测试 constructors_use_teams_topic_bare_uuid_key_and_schema_version_one 同时断言了三件事:key 等于团队 UUID、key 不以 team| 开头、schema_version 恒为 1。

信封结构

信封由 crates/macro_event_broker/src/domain/models.rs 定义:

pub struct Event<E> {
    pub event_id: Uuid,
    pub schema_version: u8,
    #[serde(flatten)]
    pub event: E,
}

event_id 由 Uuid::now_v7() 生成(时间有序),schema_version 取自 TopicEvent::SCHEMA_VERSION,event 被 flatten 展开,最终线上形状是 event_id、schema_version、event_type、metadata 四个顶层字段。TeamTopicEvent 使用 #[serde(tag = "event_type", content = "metadata")] 完成这一展开:

pub enum TeamTopicEvent {
    #[serde(rename = "team.created")]
    Created(TeamCreatedMetadata),
    // ...
}

impl TopicEvent for TeamTopicEvent 中 const SCHEMA_VERSION: u8 = 1;,即当前契约所有事件都用版本 1。

十种团队事件与触发时机

原文档给出的表格是这条契约的权威说明,下表在其基础上补充了对应的 Rust 元数据结构:

事件名 触发时机 Metadata 源码结构
team.created 团队创建且所有可回滚的创建副作用成功 team_id, name, slug, owner, enterprise, paid, auto_join_domain TeamCreatedMetadata
team.updated 含 name 或 slug 的团队 PATCH 已持久化 team_id, actor_user_id, 请求的 name, 请求的 slug TeamUpdatedMetadata
team.deleted 团队删除成功 team_id, actor_user_id, member_user_ids(源码另含 bot_ids、owned_entities) TeamDeletedMetadata
team.invite_created 新邀请持久化;每个新受邀的小写邮箱产生一条事件 team_id, invite_id, email, invited_by, team_name TeamInviteCreatedMetadata
team.invite_rejected 受邀人成功拒绝并删除邀请 team_id, invite_id, email, actor_user_id TeamInviteRejectedMetadata
team.invite_revoked 管理员成功删除邀请 team_id, invite_id, email, actor_user_id TeamInviteRevokedMetadata
team.member_joined 邀请加入、域名自动加入或邀请链接加入,且所有可回滚副作用成功 team_id, member_id, teammate_ids, role, join_method TeamMemberJoinedMetadata
team.member_removed 成员移除且所有可回滚副作用成功 team_id, member_id, removed_by, role TeamMemberRemovedMetadata
team.member_role_changed 每一次单独的成员角色更新成功 team_id, actor_user_id, member_id, role, previous_role TeamMemberRoleChangedMetadata
team.auto_join_domain_toggled 显式切换自动加入域成功 team_id, actor_user_id, auto_join_domain TeamAutoJoinDomainToggledMetadata

注意 teams crate 的 README 表格是契约的稳定面,而源码近期为 team.deleted 扩了 bot_ids 与 owned_entities 两个字段(见 crates/teams/src/domain/events.rs 中 TeamDeletedMetadata 的注释与 #[serde(default)] 标注)。这属于增量字段,老消费者可以忽略。

角色取值与可空语义

role 一律小写,来自 TeamRole 的 #<a href="https://link.gitcode.com/i/1809d3549174c04b36049992f20687cf" target="_blank">serde(rename_all = "lowercase")],取值为 member、admin、owner,源码注释还说明其从"最少权限到最多权限"自上而下排序([crates/teams/src/domain/model.rs)。

可选 metadata 序列化为 null:

  • team.updated 上的可变字段描述的是请求的 PATCH,null 表示该字段被省略,而不是"值未变化"。
  • team_name 是尽力而为的邀请时查询结果,取不到即 null。
  • previous_role 是已知的 PATCH 前快照中的角色。
  • auto_join_domain 是操作后的结果域,关闭时为 null。

一个容易误读的点:团队删除只产生一条事件,member_user_ids 列出删除前存在的成员,不会为每个成员再补一条移除事件。而在成员自助退出场景中,removed_by 等于 member_id。

PATCH 的三种输出组合

patch_team 的实现决定了事件组合(crates/teams/src/domain/team_service.rs):

  1. 仅角色变更:逐个成员更新角色,每次成功立刻发布 team.member_role_changed;由于 req.name 与 req.slug 均为 None,不发布 team.updated。
  2. 仅名称/别名变更:不产生角色事件,发布一条 team.updated。
  3. 两者同时变更:先按请求顺序产生若干角色事件,再产生一条 team.updated。

角色更新按请求顺序提交:如果后续某个更新失败,之前已成功更新及其事件保持已提交状态,失败的那次不产生事件。发布点位于 patch_team_user_role 成功之后:

for update in user_role_updates {
    let previous_role = team.members.iter()
        .find(|member| member.user_id == update.team_user_id)
        .map(|member| member.role);
    self.team_repository
        .patch_team_user_role(&team_id, &update.team_user_id, update.role)
        .await?;
    self.publish_team_event(&TeamMacroEvent::member_role_changed(...));
}

代码同时拒绝两类非法操作:分配 Owner 角色、降级团队所有者。这也是为什么 team.member_role_changed 实际只会出现 member/admin 两种新值。

创建事件中的 auto_join_domain 例外

团队创建时会尝试为公司域名默认开启自动加入:若所有者邮箱是通用邮箱域(is_generic_email_domain),则 auto_join_domain 为 None;否则调用 toggle_auto_join_domain 并取回结果。该步骤是尽力而为的——失败只记录日志,创建仍然成功。

关键区别在于:创建期间的自动开启只体现在 team.created 的 auto_join_domain 字段上,不额外产生 toggle 事件;只有显式的设置操作才产生 team.auto_join_domain_toggled。

join_method:带标签的联合类型

join_method 是 tagged union,由 #[serde(tag = "type", rename_all = "snake_case")] 决定线格式:

pub enum TeamJoinMethod {
    InviteAccepted { invite_id: Uuid, invited_by: MacroUserIdStr<'static> },
    DomainAutoJoin,
    InviteLink,
}

三种形态分别对应:接受邀请(携带邀请 UUID 与邀请人)、邮箱域名自动加入(编码为 {"type":"domain_auto_join"})、通过团队可分享邀请链接加入({"type":"invite_link"})。源码中的调用点与之一一对应:域名加入在 try_join_team_by_domain 中传入 TeamJoinMethod::DomainAutoJoin,邀请链接加入在 crates/teams/src/domain/team_service/invite_link.rs 中传入 TeamJoinMethod::InviteLink。

消费者应当忽略不认识的 join method,以保证未来新增加入方式时不破坏解码。

完整的 member_joined 信封示例

{
  "event_id": "01998a30-1a2b-7c3d-9e4f-5a6b7c8d9e0f",
  "schema_version": 1,
  "event_type": "team.member_joined",
  "metadata": {
    "team_id": "3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90",
    "member_id": "macro|joiner@acme.com",
    "teammate_ids": [
      "macro|admin@acme.com",
      "macro|owner@acme.com"
    ],
    "role": "member",
    "join_method": {
      "type": "invite_accepted",
      "invite_id": "0197f776-6e7b-7c69-a251-780ae754d3e4",
      "invited_by": "macro|admin@acme.com"
    }
  }
}

teammate_ids 的定义值得单独说明:它是加入时刻其他现任队友的排序去重集合(所有者 + 成员,排除加入者本人)。当名单无法加载或团队没有其他成员时为空数组。该字段带 #[serde(default)],因此历史上未包含该字段的旧事件仍可解码为空数组。测试 member_joined_defaults_missing_teammate_ids 验证了这条兼容性路径。

生成逻辑在 teammate_ids_except:把 owner_id 与所有成员的 user_id 链接去重、过滤掉加入者、再按字符串排序。这份"排序去重"不是风格问题,而是让 DM 创建的请求集合稳定可比较,从而支持幂等重放。

脱敏与不产生事件的流程

事件载荷刻意排除 Stripe 订阅 ID、客户 ID、支付状态以及其他计费标识。唯一的计费派生值是创建事件上的 paid: bool——源码注释直接写道"不暴露计费标识的前提下说明团队是否为付费订阅"。

以下流程不发布团队事件:

  • 计费流程,包括 Stripe webhook 驱动的订阅与支付状态变更、付费角色(premium)的撤销与恢复;
  • CRM 设置变更与 patch_team_crm_settings;
  • 读/列表操作;
  • 邀请重发及其 mark_invites_sent 更新;
  • 通知结果。

此外,提交后进行的尽力而为的 CRM、联系人、通知工作不会抑制对应事件:这些后续步骤失败只记录日志(例如 enqueue_populate_crm_for_user 失败时的 tracing::error!),不会回滚已提交的变更,也不会吞掉事件。

一个实现细节印证了"每个新受邀邮箱一条事件":invite_to_team 只对 new_invite_emails 集合内的邀请发布事件,因此重复邀请同一邮箱不会重复产生 team.invite_created。

投递语义:生产至多一次,消费至少一次

生产侧:提交后 fire-and-forget

publish_team_event 的实现是整个契约的关键:

fn publish_team_event(&self, event: &TeamMacroEvent) {
    drop(self.event_broker.send_event(event).inspect_err(|error| {
        tracing::error!(error = ?error, "failed to schedule team event");
    }));
}

send_event 只做序列化并把发布任务交给 spawner,返回 JoinHandle;调用方立即 drop 掉句柄,因此 API 不会等待 Kafka 投递,也不检查投递结果。发布任务内部有超时保护:macro_event_broker 的 PUBLISH_TIMEOUT 为 6 秒,超时返回 EventBrokerError::PublishTimeout 并记录错误日志。

由此产生的语义是:没有事务、没有 outbox、没有重试把数据库持久化与发布绑定在一起。相对于团队变更,投递是"至多一次"——一次已提交的变更可以完全没有对应事件。这也是为什么"事件缺失"在排查时不能直接判定为消费者 bug。

消费侧:提交 offset 前必须处理完

teammate DM 消费者是"至少一次"。它仅在处理成功或永久失败后才提交 offset,瞬时失败会在进程内重试;若重试仍失败,消费者直接退出且不提交 offset,由监管进程重启后重投该事件。

teammate-dms 消费者的实现解剖

消费者代码位于 channels crate:crates/channels/src/inbound/teammate_dms_consumer.rs。它不依赖 teams crate,而是定义了自己的通道视角视图,只解码 member_id 与 teammate_ids 两个字段:

pub(crate) struct TeammateDmsJoinedMetadata {
    pub member_id: MacroUserIdStr<'static>,
    #[serde(default)]
    pub teammate_ids: Vec<MacroUserIdStr<'static>>,
}

TeamsTopicForDms 采用 #[serde(untagged)] 的双臂设计:MemberJoined(MemberJoinedEnvelope) 命中 event_type = "team.member_joined",其余一切落入 Other(IgnoredTeamEvent) 并被标记为成功、直接提交 offset。这样新增的团队事件类型不会卡住分区。

消费组名固定:

impl GroupName for TeammateDmsConsumerGroup {
    const GROUP_NAME: &'static str = "teammate-dms";
}

处理逻辑由 handle_team_event 完成:join 事件调用 ensure_joined_member_dms,其他事件返回 Ok(())。重试策略为最多 5 次尝试,指数退避从 1 秒起每次翻倍:

const MAX_ATTEMPTS: u32 = 5;
const RETRY_BASE_DELAY: Duration = Duration::from_secs(1);

TeammateDmError::is_transient() 目前恒返回 true,即所有错误都按瞬时错误处理;handle_with_retry 中"非瞬时错误直接丢弃并提交"的分支是为将来分类错误预留的。批次出现部分失败时,TeammateDmError::Partial 会携带 created/existing/failed 计数,触发重试以保证最终一致。

无法解码的消息会被记录 topic、partition、offset 后跳过,不会卡住分区。

服务侧的接线方式

消费者由文档存储服务托管启动(services/document_storage_service/src/server.rs):它在 consumer_tracker 中循环调用 run_teammate_dms_consumer,正常退出或报错都以 tracing::error! 记录,并在 5 秒后重启,直到取消令牌触发。

生产端则接在认证服务上(services/authentication_service/src/server.rs):先构建 MacroEventBrokerService::new(KafkaEventPublisher::new(config.kafka_brokers.as_ref())?, ...),再通过 .with_event_broker(macro_event_broker.clone()) 注入 TeamServiceImpl。注意默认构造使用 NoopMacroEventBroker,如果忘记注入,事件会被静默丢弃而不会报错——这是排查"完全没有事件"时的第一个检查点。

DM 的构造方式

消费者最终调用 ensure_joined_member_dms,它把加入者与队友列表转成 EnsureDms 批次:

pub fn ensure_dms_for_joining_member(
    joiner: MacroUserIdStr<'static>,
    roster: impl IntoIterator<Item = MacroUserIdStr<'static>>,
) -> EnsureDms

DmPair::new 会规范化两端顺序(按字符串比较把小的放 lo),因此 (a, b) 与 (b, a) 是同一个 DM,重复事件重放不会产生重复频道;两端相同则返回 SelfDm 错误。这就是消费端能做到幂等的结构性原因。

回填:backfill_teammate_dms

一次漏掉的发布会让某个团队在一段时间内没有 DM,直到回填运行。命令由 crates/teams/justfile 提供:

just crates/teams/backfill_teammate_dms_local
just crates/teams/backfill_teammate_dms_dev
just crates/teams/backfill_teammate_dms_prod

三个入口的差异体现在数据库来源与确认方式:

  • local:直接使用 DATABASE_URL 环境变量,ENVIRONMENT=local,无二次确认。
  • dev:rds_database_url.sh 拼出 MacroDB URL,aws 导出临时凭证;运行前需输入 y 确认。
  • prod:必须逐字输入 prod backfill 才会执行,否则打印 Production backfill cancelled. 并退出。

这个二进制(crates/teams/src/bin/backfill_teammate_dms.rs)的实现要点:

  • 分页扫描全部团队,PAGE_SIZE = 100,用 list_team_ids_after(cursor, PAGE_SIZE) 做游标分页;只有当整页取满时才推进游标,否则结束。
  • 对每个团队加载完整名单,把所有者与成员合并进 HashSet,再用 ensure_dms_for_roster 构造完整队友 DM 团(clique)——这与消费端只建"加入者与队友之间"的边不同,回填会补齐团队内所有两两组合。
  • 每处理完一个团队打印一行 team=... created=... existing=... failed=...,结束时打印汇总。
  • 只要有任意失败,最终 anyhow::bail! 以非零码退出,便于 CI/运维判定。

因为 ensure_dms 语义是"确保存在",整条链路幂等:重复运行只会增加 existing 计数,不会产生重复频道。

兼容性约束与上线顺序

面向未来演进,契约要求:

  1. 容忍未知 event_type:新事件变体不应导致消费者崩溃——TeamsTopicForDms 的 Other 分支正是这一原则的实现。
  2. 容忍未知 metadata 字段:新增加性字段必须可被老消费者忽略。
  3. 缺字段要能解码:teammate_ids、bot_ids、owned_entities 都使用 #[serde(default)],老事件仍可读出(空数组)。
  4. 按 schema_version 解释已知事件:当前所有事件都是版本 1。

部署顺序上,必须先创建 macro.teams 主题,再上线生产者:

  1. 部署 Kafka-cluster 栈(主题集合由 macro_event_topics 的声明驱动);
  2. 在 Doppler 中为认证服务(生产者)和文档存储服务(teammate-DM 消费者)配置 KAFKA_BROKERS;
  3. 最后部署这两个服务。

如果生产者先于主题上线,团队变更依然成功,但在"至多一次"契约下事件会丢失——只能靠回填补偿。

本地验证

teams crate 的 justfile 把常用校验命令固化下来,并开启了严格告警:

just crates/teams/check      # cargo check
just crates/teams/test       # cargo test
just crates/teams/clippy     # cargo clippy(RUSTFLAGS=-Dwarnings)
just crates/teams/fmt-check  # cargo fmt --check

与事件契约直接相关的测试集中在两处:crates/teams/src/domain/events/test.rs 覆盖每个变体的 JSON 线格式、key 与 schema version、以及缺失字段的默认值;crates/channels/src/inbound/teammate_dms_consumer/test.rs 覆盖信封解码与 join 事件处理。此外 crates/teams/src/domain/team_service/test.rs 中的 invite_join_does_not_create_teammate_dms_inline 与 domain_join_does_not_create_teammate_dms_inline 断言了"加入流程本身不内联创建 DM,只发布带 teammate_ids 的事件",防止两条路径被悄然合并而破坏异步语义。

当你需要判断某个字段是否属于稳定契约时,一个可靠的做法是:以 README 表格为基线,再对照 events.rs 中是否有 #[serde(default)]——带默认值的字段属于增量扩展,不带默认值的字段才是所有消费者必须处理的硬要求。

登录后查看全文
macro