Macro teams crate 架构与工程实践指南:团队生命周期、邀请链路与 macro.teams 事件契约
Macro teams crate 架构与工程实践指南:团队生命周期、邀请链路与 macro.teams 事件契约
本文以 Macro 单仓(monorepo)中的 teams crate 为主线,系统梳理团队(Team)这一账户/工作空间核心聚合的领域服务、邀请与加入路径、删除副作用、HTTP 与 AI 工具出口,以及它向 macro.teams Kafka 主题发布的生命周期事件契约。读完后你能掌握:如何在该 crate 中安全地新增一个团队变更、如何理解事件投递语义与幂等性边界、如何排查"漏发的队友 DM"与"重复提醒邮件",以及提交前需要跑哪些校验命令。
一、crate 定位:它拥有什么,不拥有什么
teams 是账户/工作空间管理的一部分,负责团队席位成员关系、邀请、角色、CRM 与分析设置,并作为 macro.teams 生命周期事件的生产者(消费方如计费、CRM 再各自订阅)。crate 采用六边形架构(ports-and-adapters),lib.rs 的模块划分非常直白:
domain:领域模型、端口 trait(TeamRepository、CustomerRepository、ChannelService等)与TeamServiceImpl实现;outbound:外部依赖适配器(PostgreSQL、Stripe、SQS、analytics 等);inbound:入站适配器(Axum handler、AI toolset、提醒 worker)。
对应代码:crates/teams/src/lib.rs。
职责边界需要严格区分,这是阅读该 crate 时最容易"越界"的地方:
| 归属 | 内容 | 落点 |
|---|---|---|
| 本 crate 拥有 | "Team" 表的生命周期、成员关系、邀请、macro.teams Kafka 生产者 |
crates/teams/src/domain/team_service.rs |
| 不在这里 | 计费/席位定价逻辑 | crates/ai_billing(消费本 crate) |
| 不在这里 | CRM 公司/联系人同步 | crates/crm(本 crate 只负责入队) |
依赖方向同样明确:下游依赖 entity_access、channels(backfill_binary feature)、analytics_client、ai_toolset(ai_tools feature);上层调用方包括 services/authentication_service、services/document_storage_service、services/calendar_service、services/agent_harness_service、crates/scheduled_action、crates/ai_tools、crates/ai_billing、crates/calendar_scheduling。
这些 feature 并非装饰,而是编译期切面,见 crates/teams/Cargo.toml:default 打开 ai_tools + axum + inbound + outbound + ports;backfill_binary 才引入 channels/outbound、macro_entrypoint 和 database_env_vars,并注册独立的二进制 backfill_teammate_dms。因此"只要 domain 逻辑"的调用方可以只开 ports,避免把 Axum 与 SQLx 拖进依赖图。
二、从这里开始:核心文件阅读顺序
原文档给出了一条经过验证的入口链路,按此顺序读可以最快建立心智模型:
src/domain/team_service.rs:主服务——创建、邀请、成员关系、角色变更、域名自动加入开关;团队级设置(默认链接分享default_link_share、界面语言language)是PatchTeamRequest上的字段。src/domain/team_service/invite_link.rs:团队可分享邀请链接(TeamInviteLinkService)——谁能看、创建、重置、关闭,以及通过它加入(走与域名自动加入相同的 direct-join 路径)。src/domain/team_service/invite_reminders.rs+src/inbound/invite_reminder_worker.rs:未应答邀请的提醒邮件,在authentication_service中按小时扫;仓储层先"认领"到期邀请并计数,再发信,因此多副本不会重复发送,发送失败会丢弃这一次提醒而不是重试。src/domain/owned_entity_cleanup.rs+open_seat_release.rs:账号/团队删除的副作用(所有权实体转移清理、席位释放)。src/inbound/axum_router.rs/src/inbound/toolset.rs:HTTP 路由与 AI 工具面。src/outbound/team_repo.rs:Postgres 仓储;读操作使用调用方传入的连接池。src/domain/team_repo.rs:查看者所属团队复用get_user_teams,团队完整成员(含 owner)复用get_all_team_members。
三、TeamServiceImpl:12 个泛型端口拼出的领域服务
TeamServiceImpl 是一个高度参数化的结构体,每个字段都是一个端口,默认值全部是 no-op 实现,这让测试和不同服务的装配可以各取所需(crates/teams/src/domain/team_service.rs):
| 端口 | 作用 | 默认实现 |
|---|---|---|
TeamRepository |
团队表、成员、邀请、席位计划的持久化 | 必填 |
CustomerRepository |
Stripe 客户/订阅、席位增减、计费锁 | 必填 |
ChannelService |
团队成员频道/DM 的加入与退出 | 必填 |
UserRolesAndPermissionsService |
角色授予/回收(TeamSubscriber 与档位角色) |
必填 |
NotificationIngress |
邀请通知、提醒邮件 | 必填(Arc) |
CrmEnqueuer |
CRM populate/depopulate 回填入队 | 必填 |
TeamCrmSettingsRepository |
team_crm_settings 行与批量 CRM 拆除 |
必填 |
TeamAnalytics |
生命周期分析事件(best-effort) | NoOpTeamAnalytics |
ContactsEnqueuer |
成员关系衍生的联系人连接 | NoOpContactsEnqueuer |
MacroEventBroker |
macro.teams 事件发布 |
NoopMacroEventBroker |
OpenSeatRelease |
离队/换档时释放或迁移席位 | NoOpOpenSeatRelease |
OwnedEntityCleanup |
删除团队前清空其所有内容 | UnwiredOwnedEntityCleanup |
默认实现里的两个"故意失败"值得单独强调:
UnwiredOwnedEntityCleanup的每个方法都返回OwnedEntityCleanupUnwired,注释明确写着"没有接线清理能力的服务拒绝删除团队,而不是删掉 team 行把内容变成孤儿"(crates/teams/src/domain/owned_entity_cleanup.rs)。这是一个把"安全的默认值"写进类型系统的例子。NoOpOpenSeatRelease、NoopMacroEventBroker则让"不关心该副作用"的调用方保持零成本。
装配用链式 with_* 方法完成:with_contacts_enqueuer、with_event_broker、with_open_seat_release、with_owned_entity_cleanup(team_service.rs)。真实装配点在认证服务里,可以看到它一次把四个可选端口全部接上:
let teams_service_impl = TeamServiceImpl::new_with_analytics(
teams_repo_impl.clone(),
customer_repo_impl,
channel_service.clone(),
user_roles_and_permissions_service.clone(),
notification_ingress_service.clone(),
crm_enqueuer,
team_crm_settings_repo_impl,
team_analytics,
)
.with_contacts_enqueuer(contacts_enqueuer)
.with_event_broker(macro_event_broker.clone())
.with_open_seat_release((*ai_billing_service).clone())
.with_owned_entity_cleanup(team_owned_entity_cleanup);
见 services/authentication_service/src/server.rs。注意 with_open_seat_release 直接复用 ai_billing 的服务实现——团队 crate 不重写计费,只依赖 OpenSeatRelease 这个端口。
四、macro.teams 事件契约:10 个事件、同一分区、至多一次
事件模型在 crates/teams/src/domain/events.rs,enum 以 #<a href="https://link.gitcode.com/i/8efff45245155f2b9dc2dde59535291a" target="_blank">serde(tag = "event_type", content = "metadata")] 扁平化,TopicEvent::SCHEMA_VERSION = 1,主题由 macro_event_topics 的 MacroTeamsTopic => "macro.teams" 定义([crates/macro_event_topics/src/lib.rs)。
4.1 事件一览
| 事件名 | 触发时机(成功后) | metadata |
|---|---|---|
team.created |
团队创建及所有可回滚创建副作用成功 | team_id、name、slug、owner、enterprise、paid、auto_join_domain |
team.updated |
含 name 或 slug 的 PATCH 已落库 |
team_id、actor_user_id、请求中的 name、slug |
team.deleted |
团队删除成功 | team_id、actor_user_id、member_user_ids(+ 新增的 bot_ids、owned_entities) |
team.invite_created |
新邀请落库;每个新邀请的小写邮箱产生一条 | team_id、invite_id、email、invited_by、team_name |
team.invite_rejected |
被邀请人成功拒绝并删除邀请 | team_id、invite_id、email、actor_user_id |
team.invite_revoked |
管理员成功删除邀请 | team_id、invite_id、email、actor_user_id |
team.member_joined |
邀请加入、域名自动加入或邀请链接加入及其可回滚副作用成功 | team_id、member_id、teammate_ids、role、join_method |
team.member_removed |
成员移除及可回滚副作用成功 | team_id、member_id、removed_by、role |
team.member_role_changed |
每一次单个成员角色更新成功 | team_id、actor_user_id、member_id、role、previous_role |
team.auto_join_domain_toggled |
显式切换自动加入域名成功 | team_id、actor_user_id、auto_join_domain |
4.2 分区键与信封
每条记录的 Kafka key 是主体团队的裸 UUID 字符串(例如 3f6f8b0a-...,没有 team| 前缀),key 不在 JSON 信封内:
fn new(team_id: Uuid, event: TeamTopicEvent) -> Self {
Self::with_event(team_id.to_string(), Event::new(event))
}
见 events.rs。同一团队的事件因此落在同一分区并保留团队内顺序,跨团队顺序未定义——消费方不应假设全局有序。
信封本身由 macro_event_broker 的 Event<E> 生成,字段为 event_id(UUIDv7)、schema_version、以及被 flatten 的 event_type / metadata(crates/macro_event_broker/src/domain/models.rs)。一个完整的"接受邀请后加入"信封如下:
{
"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"
}
}
}
4.3 字段语义中的"坑"
- 角色序列化为小写
member/admin/owner(TeamRole的Display与 serde 命名一致,见 crates/teams/src/domain/model.rs)。 - 可选 metadata 序列化为
null:team.updated上的可变字段描述的是请求的 PATCH,null表示该字段被省略,而非"清空"。 team_name是邀请时尽力查询的结果,可能缺失。previous_role来自 PATCH 前的团队快照,未知时为null。auto_join_domain为null表示已关闭。- 删除团队只产生一条事件,
member_user_ids是删除前的成员集合,不会为每个成员补发移除事件。 - 自助退出时
removed_by == member_id。 teammate_ids是加入时刻"其他当前队友"的排序去重集合(owner + members,排除本人);名单加载失败或团队没有其他人时为空。该字段在旧事件中不存在,所以类型上标注了#[serde(default)],消费方必须把缺失视为[]。join_method是 tagged union:{"type":"invite_accepted","invite_id":...,"invited_by":...}、{"type":"domain_auto_join"}、{"type":"invite_link"};消费方应忽略不认识的方法。team.deleted的bot_ids与owned_entities同样是后加字段,均带#<a href="https://link.gitcode.com/i/54967c26e7dbe118f2991a33f14b30d6" target="_blank">serde(default)]([events.rs)。
4.4 明确不产生事件的动作
事件契约只覆盖"成功的团队变更"。以下流程不发布 macro.teams 事件:
- Stripe webhook 的订阅与支付状态变更、premium 角色的回收/恢复;
- CRM 设置变更(
set_team_crm_enabled)、所有读取/列表操作; - 邀请重发及其
mark_invites_sent更新、通知结果。
同时,create_team 时自动执行的域名开关不会额外产生 toggle 事件,它只体现在 team.created 的 auto_join_domain 字段上;只有显式设置操作才产生 team.auto_join_domain_toggled。纯角色 PATCH 只产生角色变更事件,不产生 team.updated。
角色更新按请求顺序提交:某次失败时,之前成功的更新及其事件已提交,失败的那次不产生事件(team_service.rs 的循环实现正是逐条 patch_team_user_role 后立即 publish_team_event)。
4.5 脱敏边界
载荷排除 Stripe 订阅 ID、客户 ID、支付状态以及所有其他计费标识;唯一来源于计费的字段是创建事件上的 paid: bool。这一约束在模块文档里被显式声明(events.rs)。
五、投递语义:为什么"少一条事件"是允许的
发布发生在相关变更提交之后,且是 fire-and-forget:
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");
}));
}
见 team_service.rs。要点:
- API 不等待 Kafka 投递;调度或发布失败只记日志,不回滚、不让请求失败。
- 没有事务、没有 outbox、没有重试把数据库持久化与发布耦合起来。
- 相对团队变更是至多一次:已提交的变更可能没有对应事件。
- 例外:队友 DM 的消费是至少一次——消费方只有在成功或永久性结果后才提交 offset,瞬时失败会重试。
- 因此一次漏发可能让某个团队缺少 DM,直到
backfill_teammate_dms运行。
这套取舍要求消费方做到两条:容忍未知 event_type 与未知 metadata 字段(保证前向兼容),并在解释已知事件时读取 schema_version(当前全为 1)。
六、加入团队的三条路径,一个 direct-join 内核
src/domain/team_service/invite_link.rs 与 join_team_directly 共同解释了"邀请加入 / 域名自动加入 / 邀请链接加入"为何行为一致:后两者都复用 direct-join,前者在 accept_team_invite 之后执行同构的副作用序列。
6.1 direct-join 的副作用顺序与回滚
join_team_directly(team_service.rs)的执行顺序值得逐条记住,因为每一步失败都会逆向回滚:
add_user_to_team;若插入发现已是成员,直接返回Ok(None)(并发下由唯一约束兜底)。- 企业团队跳过订阅;否则查支付状态,
subscription_id存在但不付费则返回TeamNotPaying;无订阅时尝试 legacy 订阅回填。 - 有订阅则
increment_seat_count。 - 企业或付费团队授予角色:
TeamSubscriber+ 该席位SeatPlan的档位角色;失败时先撤销席位再回滚成员关系。 channel_service.auto_join_by_team_id;失败时撤销角色、撤销席位、回滚成员。- 之后的 CRM populate 入队、联系人入队、事件发布都是 best-effort,失败只记日志。
一个容易误读的细节:direct-join 不产生 TeamJoined 分析事件,因为该分析事件与"被接受的邀请"绑定,而直接加入没有邀请(源码里有明确注释)。
6.2 邀请链接的权限模型
TeamInviteLinkService 的四类操作适用不同规则(invite_link.rs):
| 操作 | 权限要求 |
|---|---|
get_team_invite_link |
与邮件邀请同一规则:能邀请即可见 |
create_team_invite_link |
能邀请即可创建;但已存在链接时只有 admin/owner 能重置,否则返回 ResetRequiresAdmin |
delete_team_invite_link |
需要 AdminTeamRole 收据 |
join_team_by_invite_link |
任意登录用户;已在本团队返回 AlreadyMember,已在其他团队返回 AlreadyInAnotherTeam |
"能邀请"本身是两段逻辑:是 admin/owner 直接通过;否则读 allow_non_admin_invites,关闭时返回 NonAdminInvitesDisabled。令牌是 v4 UUID,注释解释了这个选择——v4 携带 122 位随机性,而 v7 会泄露创建时间且随机位更少;Debug 实现被刻意重写成 TeamInviteLinkToken(<redacted>),避免令牌随日志或错误信息进入遥测(crates/teams/src/domain/model/invite_link.rs)。HTTP 层还把令牌放在请求体而非路径里,理由是"记录 path 的 span 与访问日志永远不会看到它"。
join_team_by_invite_link 在 double-check 上也做了处理:若 direct-join 返回 None(插入发现已存在成员),会重新查询用户团队,区分"并发的同团队加入"与"并发的其他团队加入"。
6.3 邀请邮件与每日上限
invite_users_to_team 在发信前做三件事:
- 计算
invitee_plan(企业 → Premium;付费中且有订阅 → Premium;无订阅 → 尝试 legacy 回填;订阅存在但未付费 →TeamNotPaying直接报错),并把结果写入 tracing span 便于排查"邮件承诺了什么套餐"。 - 非 admin 邀请且团队关闭了
allow_non_admin_invites→NonAdminInvitesDisabled。 - 非企业团队做 24 小时滚动窗口限流:
MAX_TEAM_INVITES_PER_DAY = 50,超出返回TooManyEmails。
随后只对"新邮箱"发布 team.invite_created 与分析事件,并用 mark_invites_sent 记录真正发出的邀请;mark_invites_sent 失败也不影响请求成功。
七、邀请提醒:按小时扫,先认领再发信
提醒策略写在 crates/teams/src/domain/team_service/invite_reminders.rs:每个邀请最多两封提醒,第一封在最后一封邮件的 3 天后,第二封再隔 4 天。
7.1 认领式 SQL 是防重复的关键
真正的并发保证在仓储层(crates/teams/src/outbound/team_repo.rs):
WITH due AS (
SELECT ti.id
FROM team_invite ti
JOIN team t ON t.id = ti.team_id
WHERE ti.created_at > NOW() - INTERVAL '14 days'
AND (
(ti.reminders_sent = 0 AND ti.last_sent_at <= NOW() - INTERVAL '3 days')
OR (ti.reminders_sent = 1 AND ti.last_sent_at <= NOW() - INTERVAL '4 days')
)
AND (t.enterprise OR t.paying OR t.subscription_id IS NULL)
AND EXISTS (SELECT 1 FROM team_user tu
WHERE tu.team_id = ti.team_id AND tu.user_id = ti.invited_by)
AND NOT EXISTS (SELECT 1 FROM team_user tu
WHERE tu.team_id = ti.team_id AND tu.user_id = 'macro|' || ti.email)
ORDER BY ti.created_at
LIMIT $1
FOR UPDATE OF ti SKIP LOCKED
)
UPDATE team_invite ti
SET reminders_sent = ti.reminders_sent + 1,
last_sent_at = NOW()
FROM due, team t
WHERE ti.id = due.id AND t.id = ti.team_id
RETURNING ...
过滤条件每一条都对应一个真实问题:
created_at > NOW() - INTERVAL '14 days':超过 14 天的邀请不再提醒,避免部署后给很久以前的邀请群发邮件;(enterprise OR paying OR subscription_id IS NULL):邀请人已无法接受(团队停止付费)时跳过;EXISTS (... invited_by ...):发信人已离队则跳过,因为邮件是以发信人名义写的;NOT EXISTS (... 'macro|' || email ...):已是成员的不再提醒;FOR UPDATE ... SKIP LOCKED:多副本并行时各认领互不重叠的邀请。
认领即计数,所以 send_invite_reminder 失败时这一封提醒被永久丢弃,而不是重试——这是"绝不重复,宁可少一封"的明确取舍,InviteReminderReport 里 failed 字段的注释写得很直白。
7.2 worker 的调度节奏
run_invite_reminder_sweep(crates/teams/src/inbound/invite_reminder_worker.rs)的参数与行为:
| 常量 | 值 | 含义 |
|---|---|---|
INVITE_REMINDER_SWEEP_INITIAL_DELAY |
5 分钟 | 启动后延迟首扫,避开部署滚动重启 |
INVITE_REMINDER_SWEEP_INTERVAL |
1 小时 | 后续扫描间隔(提醒以天计,晚一小时无成本) |
INVITE_REMINDER_BATCH |
100 | 单次最多认领数 |
一批被占满时会立刻再扫(返回 Duration::ZERO),否则等一个间隔。shutdown 只在两次扫描之间检查,不会中断一次扫描——因为认领已经计数,中途停止会丢掉剩余提醒。该 worker 由 authentication_service 在启动时 spawn,并受 TaskTracker + CancellationToken 管理(services/authentication_service/src/server.rs)。
提醒通知使用确定性 ID 保证幂等:reminder_notification_id 用 Uuid::new_v5(invite_id, "team-invite-reminder-{n}"),同一邀请的同一封提醒重复投递只会产生一个通知。提醒只发邮件(.with_email()),因为首次邀请已经写过站内通知。
八、删除与退出:所有权清理 + 席位释放
8.1 团队删除的顺序是有讲究的
delete_team_as(team_service.rs)执行:
get_all_team_members快照成员(用于事件里的member_user_ids);clear_team(&owned_entity_cleanup, team_id)清空团队与其所有 bot 拥有的内容;- 若存在订阅则
cancel_subscription; delete_team(&cleared)—— 参数类型是ClearedTeam,只有清理成功才能构造,从类型上禁止"先删 team 行导致内容孤儿";- 发布
team.deleted(带bot_ids与purged的owned_entities); - 对已不在任何团队的成员回收
TeamSubscriber角色。
清理失败会在第 2 步就中止,账单与 team 行都不动,因此重试会从上次停下的地方继续。clear_team 的细节(owned_entity_cleanup.rs):
- 每轮先
team_bots(含软删除的 bot,按 id 排序去重),再对 team 与每个 bot 调owned_by(含回收站实体); - 列表为空即结束并返回
ClearedTeam; - 否则按
purge_rank排序逐个purge:ScheduledAction(0) →AgentSession(1) →Chat/ExternalChat(2) →Document(3) →Project(4)。生产者先于产物被清除,避免运行中的会话或定时任务在清理背后继续写入;Project 最后,因为它的树形清理会删除任意 owner 的嵌套项; - 最多
MAX_DISCOVERY_PASSES = 4轮;仍有余量则返回StillOwned; - 若某个 owner 的列表里出现不属于它的实体,返回
OwnerMismatch,一个都不删。
注意:原文档"Gotchas"里那句 "Registered external chats are human-owned" 的落地含义是——外部聊天注册的是人类所有权,因此所有权清理把它们的依赖顺序当作其他会话处理,而不是作为团队或 bot 拥有的内容批量删除。
8.2 成员移除与席位
remove_member(team_service.rs)先取团队计费锁 lock_team_billing,再按"删除成员关系 → 取消待生效降级 + 减席位 → 退出频道 → 回收角色 → 释放席位"推进,任一步失败都回滚前面已完成的部分(包括恢复成员行与待生效的席位降级)。owner 不可被移除(CannotRemoveOwner);UserNotInTeam 的分支会先尝试释放空席位再返回错误。
8.3 账号删除
账号删除时,认证服务先调用 TeamService::remove_user_from_all_teams 把用户从所有团队剥离,再删除 profile(team_service.rs):用户拥有的团队产生 team.deleted(actor_user_id 为被删用户),用户仅作为成员的团队产生 team.member_removed(removed_by == member_id)。删除过程中"成员关系已消失"被视为已完成,不报错。
九、入站适配器:HTTP 路由与 AI 工具
teams_router 返回完整的路由表,在认证服务中以 /team 前缀挂载(crates/teams/src/inbound/axum_router.rs、services/authentication_service/src/api.rs):
| 方法 | 相对路径 | 处理模块 |
|---|---|---|
| POST | / |
create_team |
| GET / PATCH / DELETE | / |
get_team / patch_team / delete_team |
| GET | /user |
get_user_teams |
| GET | /user/invites |
get_user_invites |
| GET | /invites |
get_team_invites |
| POST | /invite |
invite_to_team |
| GET | /join/{team_invite_id} |
join_team |
| DELETE | /join/{team_invite_id} |
reject_invitation |
| DELETE | /invite/{team_invite_id} |
delete_team_invite |
| DELETE | /remove/{remove_user_id} |
remove_user_from_team |
| PATCH | /members/{member_user_id}/plan |
patch_team_member_plan |
| PATCH | /crm |
patch_team_crm_settings |
| POST | /auto-join-domain/toggle |
toggle_auto_join_domain |
| POST | /non-admin-invites/toggle |
toggle_non_admin_invites |
| GET / POST / DELETE | /invite-link |
invite_link(查看 / 创建或重置 / 关闭) |
| POST | /invite-link/team |
打开链接前查看目标团队 |
| POST | /invite-link/join |
通过链接加入 |
错误到状态码的映射是排障的第一手资料:
| 错误 | 状态码 | 消息 |
|---|---|---|
TeamError::TeamDoesNotExist / TeamMemberNotFound / TeamInviteDoesNotExist |
404 | 对应实体不存在 |
TeamError::BadRequest |
400 | 具体原因(如 cannot downgrade the team owner's role) |
CreateTeamError::InvalidTeamName |
400 | invalid team name |
InviteUsersToTeamError::TooManyEmails |
400 | too many invites today; try again tomorrow |
InviteUsersToTeamError::NonAdminInvitesDisabled |
403 | only team admins may invite users to this team |
ManageTeamInviteLinkError::{NonAdminInvitesDisabled, ResetRequiresAdmin} |
403 | 对应策略拒绝 |
JoinTeamByInviteLinkError::LinkNotFound |
404 | 链接不存在 |
JoinTeamByInviteLinkError::AlreadyInAnotherTeam |
409 | 已在其他团队 |
SetTeamMemberPlanError::TeamNotPaying |
402 | the team has no active subscription |
SetTeamMemberPlanError::CustomerError(PlanUnavailable(p)) |
400 | the {p} plan is not available |
DeleteTeamError::OwnedEntityCleanup(_) |
500 | unable to delete the team's content; the team was not deleted |
RemoveUserFromTeamError::CannotRemoveOwner |
400 | cannot remove owner |
RemoveUserFromTeamError::UserNotInTeam |
404 | user not in team |
AI 工具面只有一处,但设计上很克制:team_toolset 仅注册 ListTeamMembers,上下文 TeamToolContext 由 TeamMembersService 与 EntityAccessService 组成(crates/teams/src/inbound/toolset.rs)。工具描述里有一句必须被 Agent 遵守的约束:返回的 owner/admin/member 是应用权限级别,不是职位,不得据此推断某人是创始人、高管或公司所有者(list_team_members.rs)。
十、存储层约定:复用两个查询,别自己写
TeamRepository trait 有 40 余个方法(crates/teams/src/domain/team_repo.rs),但原文档特别点名了两个必须复用的读路径:
get_user_teams:查看者可见的团队列表,SQL 里JOIN team_user并LEFT JOIN team_crm_settings取crm_enabled(team_repo.rs)。注意它只返回team_user中有行的团队——owner 也必须在team_user里有一行才能被列出。get_all_team_members:团队完整成员(含 owner),用于删除快照、席位对账与成员列表;返回TeamMember { user_id, role, plan, team_id }(team_repo.rs)。
另一条约定是"读操作使用传入的连接池":TeamRepositoryImpl 的方法都通过 &self.pool 执行,调用方可以传主池或只读池,仓储本身不做路由决策。TeamMembersService 是独立的小 trait(只有 list_team_members),让 AI 工具面可以只依赖读能力(team_repo.rs)。
toggle_auto_join_domain 的实现展示了并发安全写法:先 SELECT ... FOR UPDATE 锁住 team 行,读当前 auto_join_domain 后取反;开启时从 owner 邮箱取域名,若命中通用邮箱域名(is_generic_email_domain,来自 generic_email_domains)则返回 GenericDomainNotAllowed,HTTP 层映射为 400(team_repo.rs、axum_router.rs)。创建团队时也会自动开启(通用域名除外),但那是 best-effort——失败不阻塞创建,只体现在 team.created 的 auto_join_domain 上。
十一、扩展配方:新增一个团队变更的标准四步
原文档给出的路径顺序是必须遵守的,因为它对应四个独立关注点:
- 领域逻辑:在
src/domain/team_service.rs增加方法(新副作用时同步扩展TeamServiceImpl的泛型参数与with_*builder); - 事件:如果变更需要对外可见,在
src/domain/events.rs增加TeamTopicEvent变体、metadata 结构体、TeamMacroEvent构造函数,并补events/test.rs的序列化断言;记得给后加字段加#[serde(default)],且不要改动SCHEMA_VERSION(除非是破坏性变更——当前全仓约定为 1); - 持久化:在
src/outbound/team_repo.rs实现 SQL,并在src/domain/team_repo.rs的 trait 上声明; - 入站:在
src/inbound/axum_router.rs增加子模块、路由与错误IntoResponse映射。
发布时机必须放在"变更提交之后、可回滚副作用全部成功之后",并把发布本身当作 best-effort(参考 publish_team_event)。如果需要多步原子性,做法是像 remove_member / join_team_directly 那样显式写回滚链,而不是假设事务覆盖了 Kafka。
十二、运维配方:修复漏发的队友 DM
team.member_joined 的唯一消费方是文档存储服务,消费者组 teammate-dms,实际消费实现在 channels crate:它按 teammate_ids 为 member_id 与每个队友建立 DM,不会加载团队花名册。因此一旦某条事件漏发(至多一次语义下的正常结果),该团队的 DM 就会缺失,直到回填运行。
回填是一个独立的二进制,按 PAGE_SIZE = 100 游标分页遍历每个团队,把 owner 与 members 合成 HashSet 后调用 channels.ensure_dms(ensure_dms_for_roster(roster)),逐团队打印 created/existing/failed,最后汇总;只要有任何失败就以非零退出(crates/teams/src/bin/backfill_teammate_dms.rs)。它是幂等的,可以反复跑。
三个入口(crates/teams/justfile):
just crates/teams/backfill_teammate_dms_local
just crates/teams/backfill_teammate_dms_dev
just crates/teams/backfill_teammate_dms_prod
行为差异很重要:dev 只要求输入 y 确认;prod 要求完整输入 prod backfill 才写库;二者都通过 tooling/scripts/rds_database_url.sh + aws configure export-credentials 临时取连接串。本地目标则直接用 DATABASE_URL 并 cargo run -p teams --features backfill_binary --bin backfill_teammate_dms。
webhook Kafka 消费方与投递流水线不消费也不投递这些团队事件,所以排查 webhook 问题不要往 macro.teams 上找。
十三、上线顺序:先有主题,再部署生产者
README 的部署顺序是可执行的操作约束:
- 先部署 Kafka 集群栈;
- 在 Doppler 为生产者(
authentication_service)与队友 DM 消费者(document_storage_service)配置KAFKA_BROKERS; - 再部署这两个服务。
若生产者先于主题就绪上线,团队变更仍然成功,但事件会按至多一次契约丢失——此时只能靠 backfill_teammate_dms 补齐 DM。
十四、唯一的"业务陷阱":试用期与第一个 Max 席位
原文档把它列为 Gotcha,实现位于计费适配器:处于 trialing 的订阅获得第一个 Max 席位时,试用立即结束、并立刻开始新的计费周期;除这一种情况外,其他任何席位变更都保留试用(包括"已经在 Max 上试用"的订阅),因此其已排定的降级仍按试用结束时间生效。
代码证据(crates/teams/src/outbound/customer_repo.rs):
let end_trial = subscription.status == stripe::SubscriptionStatus::Trialing
&& self.adds_first_max_seat(&subscription, &items)?;
...
if end_trial {
// A trial has no paid remainder to prorate. Reset the cycle so Max
// bills a full period today instead of inheriting the trial end.
update_params.trial_end = Some(stripe::Scheduled::now());
update_params.billing_cycle_anchor = Some(stripe::SubscriptionBillingCycleAnchor::Now);
}
adds_first_max_seat 会先统计订阅现有 Max 条目数量,再按本次更新中新增/修改/删除的 price 与 quantity 推算最终 Max 数量,只有"原本为 0、变更后大于 0"才返回 true;因此"在 Max 上继续加席位"不会误触发结束试用。另外,upgrade_personal_plan 的 end_trial 参数语义也如此:注释写明"Max 升级会在订阅仍试用时设置它,使试用不能迁移到 Max 价格上"(crates/teams/src/domain/customer_repo.rs)。
十五、校验与开发流程
提交前的最小闭环:
cargo test -p teams # 注意:SQLX_OFFLINE 必须未设置
这条命令依赖真实数据库(crate 的 dev-dependencies 里有 macro_db_migrator、wiremock、tower),所以 SQLX_OFFLINE 一旦被环境变量打开,编译期查询校验会与测试的运行时校验冲突。
改动任何 SQL 之后,必须在仓库根目录、在 Nix 环境内重建离线查询缓存:
nix develop --command just prepare_db
它对应 crates/teams/justfile 的 prepare_db: just sqlx::prepare_db {{ DATABASE_URL }}。此外该 justfile 还设定了 RUSTFLAGS=-Dwarnings 与 RUSTDOCFLAGS=-Dwarnings,意味着文档注释缺失会直接编译失败——这与 lib.rs 顶部的 #![deny(missing_docs)] 一致,也是本 crate 里几乎每个公开项都有 /// 注释的原因。
本地快速验证相关能力时,仓库根部的 justfile 还提供 just local-e2e-seed(重建并填充确定性 E2E 数据)与 just seed-scenario apply --file seed/scenarios/team-perms.json(应用团队/权限/实体场景),适用于需要"干净的团队世界"的联调。
十六、约束清单(可当作 Code Review Checklist)
- 团队变更必须在提交之后发布事件,且发布失败不得影响请求结果;不要引入隐式重试伪装成"可靠投递"。
- 新增 metadata 字段一律
#[serde(default)],消费方把缺失当默认值;新增事件变体时消费方必须能忽略未知event_type。 - 事件载荷不得包含 Stripe 订阅/客户/支付标识;计费信息只能以
paid: bool这种粗粒度形式出现。 - 删除团队只能走
clear_team→ClearedTeam→delete_team的顺序;不要在未清理的情况下删 team 行。 - 邀请相关权限统一走"admin/owner 或
allow_non_admin_invites"这条判定,不要在 handler 里另写一套。 - 提醒发送失败即丢弃,不要改成重试——重试会破坏"认领即计数"的防重复保证。
- 席位变更要考虑 trial 语义,尤其是第一个 Max 席位这一特例。
- 只读成员列表请复用
get_all_team_members(含 owner),查看者团队列表请复用get_user_teams,避免出现"owner 不在列表里"这类偏差。
延伸阅读:crates/teams/README.md 是事件契约的权威来源(schema、脱敏、投递语义),数据库规范见 .agents/rules/rust/db.md,六边形架构与代码规范分别见 .agents/rules/rust/architecture.md 与 .agents/rules/rust/code.md。