深入解析 Macro 的 invite_email:Askama 邀请邮件元数据、限流键与模板工程实践

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

深入解析 Macro 的 invite_email:Askama 邀请邮件元数据、限流键与模板工程实践

invite_email 是 Macro 中专门承载“邀请类邮件”通知元数据与 HTML 模板的 crate:它既不负责发送,也不负责决定谁被邀请,而是定义“这封邀请邮件长什么样、标题怎么写、多久能发一次”。本文以该 crate 的设计说明为主线,逐一拆解五种邀请邮件的字段契约、限流键设计、环境感知链接、团队邀请的权益承诺一致性,以及模板预览与新增邮件的完整工程流程。

一、crate 定位:只做“元数据 + 模板”,不做“发送”

按 crates/invite_email/CLAUDE.md 的界定,这个 crate 属于通知体系的一部分,职责非常收敛:

  • Owns(负责):邀请 / 推荐 / 同事加入三类邮件的通知元数据与模板。
  • Not here(不负责):通知的发送与排队属于 crates/notification;谁触发一次邀请属于 crates/call、crates/referral、crates/model_notifications。
  • Depends on(依赖):notification(提供 Notification、NotificationExtEmail 等类型)、macro_env、macro_user_id、model-entity。
  • Used by(被谁使用):model_notifications、call、referral。

这种“元数据在业务 crate、投递在通知服务”的切分,在 Cargo.toml 中也有直接体现:notification 以 default-features = false 引入,说明本 crate 只需要通知的领域模型(trait、限流模型、EmailContent),不需要通知服务完整的运行时能力;依赖清单里没有 SMTP、SQS、数据库客户端之类的东西。

从源码结构看,这是一个典型的“纯数据 + 派生宏”型 crate:

文件 作用
src/lib.rs InviteToMacro、ReferralCode、ChannelInviteMetadata、InviteToTeamMetadata、InviteePlan 及共用 URL 构造函数
src/call_invite.rs CallInvite,一个类型一个文件
src/colleague_joined.rs ColleagueJoinedMacro,同事加入提醒
templates/*.html 实际的邮件 HTML(Askama 语法,与 Jinja2 高度兼容)
preview_invite.py 用 Jinja2 渲染 invite.html 并在浏览器打开的预览脚本
src/test.rs 全部单元测试(34 个 #[test])

模块顶部还有 #![deny(missing_docs)],配合每个字段上的文档注释,等于用编译器强制保证“字段语义必须写清楚”——这也是本 crate 能被当作契约阅读的原因。

二、统一的抽象:Notification 三元组

所有邀请类型都实现同一套 trait 组合。核心定义在 crates/notification/src/domain/models.rs:

pub trait Notification: Serialize + DeserializeOwned + Send + Sync + 'static {
    const TYPE_NAME: &'static str;
}

pub trait NotificationExtEmail: Notification {
    fn format_email(&self) -> EmailContent;
    fn rate_limit_config() -> RateLimitConfig;
    fn rate_limit_key(&self) -> RateLimitKey;
}

invite_email 里每个类型都遵循这个三段式:

  1. 用 const TYPE_NAME 声明通知类型名(如 "invite_to_team"),它同时进入序列化标签与限流键的首段;
  2. 用 format_email() 返回 EmailContent { subject, body },其中 body 来自 self.render()(Askama Template 派生);
  3. 用 rate_limit_config() + rate_limit_key() 声明“同一个桶里多久只能发一封”。

EmailContent 的定义在 crates/notification/src/domain/models/queue_message.rs,只有 subject 与 body 两个字符串,没有收件人字段——收件人由上层 SendNotificationRequestBuilder 的 recipient_ids 决定。这意味着同一份元数据可以被复制成多封邮件发往不同收件人,正如频道邀请所做的事。

三、五种邮件类型逐个拆解

3.1 InviteToMacro:推荐注册邀请

定义与实现见 src/lib.rs#L42-L130:

#[derive(Debug, Serialize, Deserialize, Clone, Template)]
#[template(path = "invite.html")]
pub struct InviteToMacro {
    pub recipient_email: EmailStr<'static>,
    pub referral_code: ReferralCode,
    pub sender_profile_picture_url: Option<Url>,
    pub sender_name: Option<String>,
    #[serde(default)]
    pub sender_email: Option<String>,
}

字段契约要点:

  • recipient_email 用 EmailStr<'static> 而非裸 String,构造即校验;它同时进入限流键,保证“同一收件人”维度的去重。
  • referral_code 是 #<a href="https://link.gitcode.com/i/5cb035983bfea3cb0af7fabfff3f4aa9" target="_blank">serde(transparent)] 的 newtype([#L37-L40),序列化后就是字符串,避免在 JSON 里多套一层对象。
  • sender_profile_picture_url 是 Option<Url>,模板里用 {% if let Some(url) = ... %} 决定是否渲染头像块。仓库中 referral 侧的构造点会先把字符串 url::Url::parse 一次再传入(crates/referral/src/domain/service.rs),解析失败就退化为 None,即“没有头像”。
  • sender_email 带 #<a href="https://link.gitcode.com/i/77b28af942ce1c110bab2ecc899d04b3" target="_blank">serde(default)],这正是文档 Gotchas 里强调的向后兼容手段:字段后加,旧队列负载反序列化不会失败。测试 [deserialization_without_sender_email_uses_none 就覆盖了这条。

format_email() 的兜底逻辑是一个三级降级链,任何一级可用就停止:

sender_name  →  sender_email  →  "A Macro user"

于是标题会出现 Test User has invited you to join Macro、sender@example.com has invited you to join Macro、A Macro user has invited you to join Macro 三种形态,测试 src/test.rs#L346-L382 逐一断言。模板正文里则进一步拼成 Name <email> 的形式(templates/invite.html#L163-L168)。

3.2 ChannelInviteMetadata:“频道邀请”与“DM 消息通知”共用一套元数据

这是本 crate 中最复杂的一类,因为它同时承担两种语义:频道邀请与私信消息通知。字段定义见 src/lib.rs#L132-L162。

关键设计点有三个:

(1)序列化的双写兼容。 结构体标注了 #<a href="https://link.gitcode.com/i/4190a3b4ba0aed66dd4b692592e6a99b" target="_blank">serde(rename_all = "camelCase")],于是线上格式是 invitedBy、channelName;同时每个字段又挂了 #[serde(alias = "invited_by")]、#[serde(alias = "channel_name")],让历史 snake_case 负载仍可解析。测试 [legacy_channel_invites_default_to_channel_wording 用两种 JSON 形状验证同一结果。

(2)is_direct_message 决定文案骨架。 该字段带 #[serde(default)],所以旧负载默认 false,仍然渲染“频道邀请”措辞——注释里明确写了这一点。文案分叉集中在 format_title() 与 format_email():

场景 邮件标题 推送标题 按钮
频道邀请 {sender} has invited you to join #{channel} {sender} invited you to join #{channel} Join channel
私信消息 {sender} sent you a message on Macro {sender} sent you a message View message

对应实现在 #L178-L216 与 templates/invite_to_channel.html#L171-L253。

(3)两个 #[serde(skip)] 字段只服务限流。 message_id 与 email_recipient 不参与序列化,只在构造限流键时使用:

if self.is_direct_message && let Some(message_id) = self.message_id {
    return RateLimitKey::builder(&Self::TYPE_NAME)
        .append(&message_id)
        .append(&self.email_recipient)
        .finish();
}

这就是文档“Recipes”里那句浓缩的规则:DM 邮件把稳定的 message ID 放进限流键,因此重试会被抑制,但后续消息不会被丢弃;普通频道邀请仍保留 sender/channel 维度。测试 dm_emails_deduplicate_retries_without_suppressing_later_messages 用“同一个 message_id 两次 → 键相同”“换 message_id → 键不同”“换 email_recipient → 键不同”“频道邀请换 message_id → 键仍相同”四组断言把这个语义钉死。

调用侧可以印证这个设计意图:crates/channels/src/outbound/notification_sender.rs 先对已注册用户走 APNS + conn gateway,再对未注册收件人逐个复制元数据、设置 email_recipient,然后 .with_email() 单独投递;不变量是“每个收件人一个独立的重试键”。

此外该类还实现了 NotificationExtIos,用 sender_profile_picture_url 是否存在来决定 mutable_content(#L249-L279),并为推送构造 NotifCollapseKey,让同一实体的多条推送可折叠。

3.3 InviteToTeamMetadata 与 InviteePlan:承诺必须等于实际授予

团队邀请的字段见 src/lib.rs#L282-L315:

pub struct InviteToTeamMetadata {
    pub team_name: String,
    pub team_id: Uuid,
    pub team_invite_id: Uuid,
    pub invited_by: MacroUserIdStr<'static>,
    pub role: Option<String>,
    pub sender_profile_picture_url: Option<Url>,
    #[serde(default, alias = "invitee_plan")]
    pub invitee_plan: InviteePlan,
    #[serde(default)]
    pub reminder: bool,
}

InviteePlan 是一个两态枚举,默认 Free:

  • Free:Macro 的免费计划。注释明确说明“计划被记录之前发出的邀请按 Free 读取,而这一读取始终为真:加入团队永远不会让被邀请人付钱”。
  • Premium:由付费、试用或企业团队承担的 Pro 席位。

这份枚举不是营销文案开关,而是一条业务不变量。文档 Gotchas 写得很直白:发送方 teams 的 invite_users_to_team 必须按 join_team 授予权益的方式来推导它——“Pro 只来自企业团队或带订阅的团队”,邮件文案的承诺绝不能超过实际加入时授予的东西。

源码完全对得上 crates/teams/src/domain/team_service.rs#L1495-L1534:先取企业状态,企业即 Premium;否则读支付状态与订阅 ID,(true, Some(_)) → Premium、(true, None) → Free、(false, Some(_)) → 返回 TeamNotPaying、(false, None) → 尝试回填历史订阅,成功才 Premium。这个推导结果还会被 tracing::Span::current().record("invitee_plan", ...) 记录,便于线上核查“邮件说了什么”。

模板侧用 Askama 的 {% match %} 直接分叉(templates/invite_to_team.html#L205-L252):

  • Premium → “Pro is included / {team} covers your seat, so you get every AI model and agent at no cost to you.”
  • Free → “Free to join / There's nothing to pay. Accept the invite to start working with {team} in Macro.”

测试 team_invite_promises_pro_only_when_the_team_covers_the_seat 双向断言:Premium 正文必须包含“Pro is included”且不得出现“Free to join”;Free 正文必须包含“Free to join”且不得出现“covers your seat”。这就是把文案一致性变成了可回归的测试。

其他细节同样值得注意:

  • invite_url() 生成 /app/team-invite?id={team_invite_id}(#L332-L343)。模板里这个 URL 被用三次:按钮 href、兜底链接 href、兜底链接可见文本,测试 team_invite_links_the_button_and_a_pasteable_fallback 断言 body.matches(&url).count() == 3——保证“邮件客户端屏蔽按钮”时用户仍能复制链接。
  • join_label() 用 MAX_BUTTON_TEAM_NAME_CHARS = 24(#L329-L356)控制按钮文字:短队名渲染 Join {team},超长则退化为 Join team,避免按钮被撑破。注意它按 chars().count() 计,不是字节数,所以中文队名不会被误判。
  • role 为 Some 时模板追加一行“Your role will be {role}”,为 None 时整段不渲染。

3.4 CallInvite:免注册的会议邀请

CallInvite 是唯一一个“收件人不需要 Macro 账号”的邀请,定义见 src/call_invite.rs:

pub struct CallInvite {
    pub title: String,
    pub share_token: String,
    pub invited_by: MacroUserIdStr<'static>,
    pub recipient_email: String,
}
  • 链接形如 /app/meet/join/{share_token},share_token 被注释为“已校验、由服务端签发的会议凭证”。
  • 模板极简(templates/invite_to_call.html),但包含两句必要声明:“No Macro account needed. Enter your name to join.” 与录音/转写告知。
  • 测试 call_invitation_links_directly_to_guest_join_and_escapes_titles 同时验证:正文出现 /app/meet/join/...、出现“No Macro account needed”、不出现 /signup(说明这是访客通道而不是注册漏斗)、标题里的 <script> 被转义、主题包含邀请人邮箱。
  • 调用侧的权限约束在 crates/call/src/domain/service/meetings.rs#L60-L75:只有会议 owner 能发;且 meeting.channel_id.is_some() 时直接拒绝,理由是“Channel calls cannot be shared with people outside Macro”——免注册链接不会成为绕过成员边界的通道。

3.5 ColleagueJoinedMacro:把“不可信名字”渲染成一行的示范

定义见 src/colleague_joined.rs,字段 team_name、joined_by、joined_name: Option<String>、recipient_email。其中 joined_name 被明确标注为“来自不可信来源,只显示一行、长度截断、并转义”。

实现用一个 display_name() 做规范化(#L20-L35):

let words: Vec<&str> = self.joined_name.as_deref()?
    .split(|c: char| c.is_whitespace() || c.is_control())
    .filter(|word| !word.is_empty())
    .collect();
// 用空格重连 → 取前 DISPLAY_NAME_MAX_CHARS(64) 个 char → trim_end

这处理了三类风险:换行/制表符导致的头部注入类排版问题(按空白与控制字符切分后重连)、超长名字撑爆版式(64 字符上限)、纯空白名字导致的空显示((!name.is_empty()).then(...) 返回 None,回退到邮箱)。

对应测试覆盖非常细:

  • 无名字或名字全是空白/控制字符 → 主题回退为 alice@acme.com joined Macro(#L52-L64);
  • " Alice\r\nExample\t\u{0}{100 个 x}" → 主题变成 Alice Example {50 个 x} joined Macro(#L66-L77);
  • 名字为 <b>x</b> → 主题保留原文(纯文本),正文里被转义为 &#60;b&#62;x&#60;/b&#62;(#L79-L93)。

最后一条值得单独强调:主题与正文的转义边界不同。邮件主题是纯文本,不需要 HTML 转义;正文由 Askama 按 .html 后缀做 HTML 自动转义。频道邀请的用户内容(channel_name、message_content)同理,测试 invite_email_escapes_message_content_and_channel_names 对 DM/频道两种模式都断言 <script> 不会原样出现。

四、限流:键的构成就是业务语义

限流模型来自 rate_limit crate,notification 只是 re-export(crates/notification/src/domain/models/rate_limit.rs)。实现细节在 crates/rate_limit/src/domain/models.rs:RateLimitKey 本质是 XxHash64 的 8 字节哈希,builder(seed).append(x).finish() 逐段喂入 Hash 实现——顺序敏感、内容敏感,所以“先 append sender 再 append channel”和反过来的键不同。

投递时的判定在 crates/notification/src/domain/service/egress.rs#L320-L372:先 check_rate_limit(key, config),超限直接返回 DeliveryFailure::RateLimit;发送失败则 rollback_ticket,把配额还回去,避免“发失败也算一次”。这一点对邀请邮件尤其重要:SMTP 抖动不该消耗掉用户一周一次的推荐邀请额度。

本 crate 四类邮件的限流配置汇总如下(均可从源码逐条核对):

类型 max_count window 键组成 设计意图
InviteToMacro 1 1 周(60*24*7 分钟,见 MINUTES_PER_WEEK) 类型名 + recipient_email 同一收件人每周最多被推荐邀请一次
ChannelInviteMetadata(频道) 1 7 天(24*7 小时) 类型名 + invited_by + channel_name 同一人对同一频道不重复骚扰
ChannelInviteMetadata(DM) 1 同上 类型名 + message_id + email_recipient 单条消息的重试去重,但新消息仍可触达
InviteToTeamMetadata 1 1 小时 类型名 + team_id + team_invite_id 一个邀请一个桶:批量邀请多人时每人各得一封
CallInvite 1 1 分钟 类型名 + share_token + recipient_email 允许快速重发,但仍防抖
ColleagueJoinedMacro 1 1 年(24*365 小时) 类型名 + joined_by + recipient_email 一场加入事件对同一收件人只播报一次

团队邀请的键选择有一个容易被忽略的收益,文档和源码注释都点明了:因为键是 (team_id, team_invite_id) 而不是 (sender, team),一次邀请十个同事会发出十封邮件;而“重发”复用同一个 team_invite_id,所以天然与首次发送共享配额。

五、提醒邮件:与 1 小时窗口强耦合的调度

InviteToTeamMetadata.reminder 只做一件事——在主题前加 "Reminder: "(#L364-L376)。测试 team_invite_reminder_says_so_in_the_subject 对照了加与不加两种主题。

但它带来一个跨 crate 的约束链:

  1. 提醒与首次邀请共用同一个限流桶(同一个 team_invite_id),窗口 1 小时;
  2. 因此两次提醒必须间隔 超过 1 小时,否则后一封会被限流直接丢弃;
  3. 手动“重发”也必须等过同一窗口。

这条约束在三个地方各有一份“同一事实的镜像”,这是本 crate 最值得学习的工程实践之一:

提醒的实际节奏由 sweeper 决定:模块注释写明“每个邀请最多两封提醒,最后一封邮件后 3 天一次、再 4 天一次”,SQL 里对应 reminders_sent = 0 AND last_sent_at <= NOW() - INTERVAL '3 days'(crates/teams/src/outbound/team_repo.rs#L555-L575)。两封提醒各自用 reminder_number 派生确定的通知 ID(Uuid::new_v5),所以同一封提醒重复投递只会产生一条通知。

另一个细节:提醒路径的 invitee_plan 采用更保守的推导(crates/teams/src/domain/team_service/invite_reminders.rs#L60-L72),只认 enterprise || (paying && has_subscription),不做订阅回填——后台 sweep 不应该触发副作用,“读成 free”永远不会承诺得比实际更多。

六、模板工程:Askama 写、Jinja2 预览、邮件客户端兼容

6.1 模板结构与兼容性处理

五个模板共用同一套“邮件安全 HTML”骨架,可在 templates/invite.html 中看到全部要素:

  • role="presentation" 的布局表格 + cellpadding/cellspacing="0",避免 Outlook 表格渲染差异;
  • <!--[if mso]> 条件注释包裹固定宽度 560 的表格与 PixelsPerInch 设置,处理 Windows Outlook;
  • <meta name="x-apple-disable-message-reformatting">、format-detection 关闭电话/日期自动识别;
  • <meta name="color-scheme" content="light"> 锁定浅色方案;
  • 隐藏的 preheader <div>(display:none; max-height:0; mso-hide:all)用于列表页摘要;
  • @media screen and (max-width: 600px) 内联样式覆写 padding、font-size,invite_to_team.html 还额外把按钮 display:block; width:100%;
  • 所有关键元素用内联 style(邮件客户端普遍不支持 <style> 选择器)。

一个容易被忽视的一致性守护:四封邀请邮件的 logo 图片都带固定 width="54" height="36",测试 invitation_logos_keep_the_png_aspect_ratio 会对 InviteToMacro、ChannelInviteMetadata、InviteToTeamMetadata、ColleagueJoinedMacro 四封渲染结果做空白归一化后逐一断言这串属性存在。这类“渲染产物断言”比肉眼检查可靠得多。

6.2 预览脚本如何把 Askama 喂给 Jinja2

preview_invite.py 的思路是“轻量语法转换 + Jinja2 渲染 + 临时文件 + 浏览器打开”:

def askama_to_jinja2(src: str) -> str:
    # {{ referral_url() }} → 直接替换为假 URL
    src = re.sub(r"\{\{\s*referral_url\(\)\s*\}\}", DUMMY_REFERRAL_URL, src)
    # {% if let Some(var) = expr %} → {% if expr %}{% set var = expr %}
    src = re.sub(
        r"\{%-?\s*if let Some\((\w+)\)\s*=\s*(\w+)\s*-?%\}",
        r"{% if \2 %}{% set \1 = \2 %}",
        src,
    )
    return src

转换只覆盖两件事:方法调用 referral_url()(Jinja2 无法调用 Rust 的 self 方法)与 if let Some(...) 绑定(Jinja2 没有 if-let,用 {% if %} + {% set %} 等价实现)。其余语法({{ }}、{% if %}、{% endif %})两边通用。

使用方式与注意事项:

pip3 install jinja2
python3 crates/invite_email/preview_invite.py

脚本会把渲染结果写入 tempfile(delete=False)并 webbrowser.open("file://..."),同时打印路径。三个实操要点:

  1. 改模板路径:TEMPLATE_PATH 硬编码为 templates/invite.html,预览其他模板需先改这一行;
  2. 改假数据:tmpl.render(...) 的 sender_profile_picture_url / sender_name / sender_email 就是文档所说的 dummy data,把前两者置为 None 即可验证“邮件地址回退”路径(脚本内注释亦如此提示);
  3. 预览不做转义:Environment(autoescape=False) 是有意为之(否则 RHS 的 None 与 Some 判断会更麻烦),代价是预览看不出转义问题。转义正确性必须靠 cargo test -p invite_email 里的断言兜底,而不是靠浏览器观感。

对于新增的其他模板(如 invite_to_team.html),除了改路径,还需补上脚本无法自动转换的表达式:{{ inviter() }}、{{ invite_url() }}、{{ join_label() }}、{{ match invitee_plan }}...{% endmatch %}。这是“预览脚本覆盖范围有限”的真实边界,文档用“edit its dummy data / template path first”一句带过,实际动手时正好会撞上。

6.3 与 packages/email-renderer 的区别

文档 Related 提到:如果要在独立渲染器里渲染,而不是走这里的邮件模板管线,去看 packages/email-renderer/README.md。后者处理的是用户来信正文的确定性 HTML/CSS 准备、引用折叠、主题色适配、Shadow DOM 挂载等前端渲染职责,与本 crate 的“服务端 Askama 生成整封邀请邮件”是两条完全不同的路径,不要混用。

七、新增一种邀请邮件:完整配方

文档 Recipes 给出的三步是主干,结合源码可以展开成可执行的检查清单。

第 1 步:新建元数据类型。 在 src/<name>.rs 里定义结构体并派生:

#[derive(Debug, Clone, Serialize, Deserialize, Template)]
#[template(path = "<name>.html")]
pub struct MyInvite {
    pub invited_by: MacroUserIdStr<'static>,
    pub recipient_email: String,
}

CallInvite 与 ColleagueJoinedMacro 就是照此写的,且都用 use super::*; 复用 lib.rs 中的 frontend_host、signup_url 等私有构造函数——所以新文件必须 mod 到 lib.rs 里(或像这两个文件一样被 mod + pub use)。

第 2 步:实现三个 trait 方法。

impl Notification for MyInvite {
    const TYPE_NAME: &'static str = "my_invite";
}

impl NotificationExtEmail for MyInvite {
    fn format_email(&self) -> EmailContent { /* subject + self.render() */ }
    fn rate_limit_config() -> RateLimitConfig { /* max_count + window */ }
    fn rate_limit_key(&self) -> RateLimitKey { /* 业务语义 */ }
}

注意 TYPE_NAME 必须是全局唯一的字符串:它既作为序列化标签,也是限流键首段。

第 3 步:写模板 templates/<name>.html。 最省事的做法是复制 templates/invite.html 改文案——骨架(MSO 条件注释、preheader、响应式媒体查询、logo 尺寸)已经被测试守护,不要重写。

第 4 步:在 lib.rs 中导出。 与其他类型保持一致:

mod my_invite;
pub use my_invite::MyInvite;

若该类型需要出现在推送/摘要/前端契约里,还要同步下游(这是文档 Boundaries 与 Gotchas 共同指向的“扩散面”):

  • 在 crates/model_notifications/src/metadata.rs 的 pub use invite_email::{...} 中 re-export;
  • 若属于“不应进入摘要邮件”的类型,加到 crates/model_notifications/src/digest_state.rs 的 digest_email_block_list()(现有的 InviteToMacro、CallInvite、ColleagueJoinedMacro、InviteToTeamMetadata 都在其中);
  • 若需要出现在通知服务的 OpenAPI 里,请派生 utoipa::ToSchema(当前只有 ChannelInviteMetadata、InviteToTeamMetadata、InviteePlan 派生了它)。

第 5 步:处理 serde 演进。 文档把这条列为 Gotcha,值得原样重申:元数据是排队并以 JSON 存储的,所以

  • 新字段一律加 #[serde(default)],否则部署前入队的负载会反序列化失败;
  • 需要与旧命名兼容时加 #[serde(alias = "...")](频道/团队两类邮件就是这么做的);
  • 线上字段形状要稳定,测试里用 serde_json::json!({...}) 固化 wire shape 是有效手段(参见 colleague_joined_serde_round_trip_keeps_the_wire_shape 与 team_invite_plan_keeps_its_wire_shape);
  • 若该类型暴露给前端,需要重新生成客户端:在 apps/web 下执行 bun run gen-api notification-service。

第 6 步:加测试。 现有 34 个测试基本给出了模板:主题降级链、限流键区分度、HTML 转义、历史 payload 兼容、按钮兜底链接次数。照抄最接近的那个再改断言即可。

八、验证与排错速查

# 单元测试:34 个用例,覆盖渲染、转义、限流键、serde 兼容
cargo test -p invite_email

# 模板视觉预览(需 jinja2)
pip3 install jinja2 && python3 crates/invite_email/preview_invite.py

常见现象与根因对照:

现象 可能根因 定位点
本地邮件里的链接指向 macro.com 而不是 localhost 环境变量未设置,Environment::new_or_prod() 回退到 Production crates/macro_env/src/lib.rs#L51-L53、src/lib.rs#L73-L85
本地链接端口不是期望值 FRONTEND_PORT 未设,默认 3000 同上
重发邀请失败/静默丢失 1 小时窗口未过,或 last_sent_at 已被前移 invite_resend_interval() 与 SQL 过滤
批量邀请只到了一封 限流键误用 (sender, team) 而非 (team_id, team_invite_id) src/lib.rs#L387-L394
同一 DM 反复发多封 键里缺少稳定 message_id src/lib.rs#L225-L238
部署后旧通知反序列化失败 新字段漏加 #[serde(default)] 各结构体字段属性
邮件承诺 Pro 但用户加入后没有 InviteePlan 派生与 join_team 不一致 crates/teams/src/domain/team_service.rs#L1495-L1534

九、小结

invite_email 的价值不在于“五个 HTML 文件”,而在于它把邀请邮件的三件难事都变成了可编译、可测试的代码:

  1. 契约——Notification / NotificationExtEmail 把“标题怎么降级、键怎么算、多久发一次”固化为类型系统的一部分;
  2. 一致性——InviteePlan 让邮件文案与团队实际授予权益同源,invite_resend_interval() 让后端判定、SQL 过滤、前端按钮共享同一个窗口数值;
  3. 安全——不可信名字按空白/控制字符规范化并截断到 64 字符,用户内容统一走 Askama 自动转义,并用断言把转义结果写进回归测试。

当你需要新增一封邀请邮件时,真正的成本不在写模板,而在想清楚三件事:限流键代表哪个业务维度、文案是否超额承诺、新字段如何与已排队的 JSON 负载共存。这三点想清楚了,剩下的就是照着 crates/invite_email/src/test.rs 的既有模式补齐断言。

登录后查看全文
macro