spec: EmailProviderSchema 缺 'smtp',TSDoc 仍称 SMTP 不随 plugin-email 发布(#5087 落地后为假)

[os-zhuang]

Blocked-by: #5087

由 #5087 的实现派生。修复落在 packages/spec,而 #5087 的 PR 被派发约束明确禁止碰 spec(同批 #5080 / #4001 正在 spec 内作业,避免撞车),故单独立单。

PM 分诊(勿在解除前派发):除上面的 Blocked-by 外,还需等 spec 车道空出 —— #5080 / #4001 在飞期间本单不可进,因为本单要动的生成物 content/docs/references/system/email-config.mdx 走 merge=os-regen,会静默吞掉一侧改动。详见本单评论。

现状

packages/spec/src/system/email-config.zod.ts:

• EmailProviderSchema = z.enum(['log', 'resend', 'postmark']) —— 不含 'smtp'。
• 同文件该 schema 的 TSDoc 明写:「Self-hosted SMTP is intentionally NOT shipped in plugin-email; apps that need SMTP register a custom IEmailTransport themselves and pass it via EmailServicePluginOptions.transport.」

#5087 落地后这两句都不再成立:@objectstack/plugin-email 已内置 SmtpTransport(ADR-0012,nodemailer 惰性加载),EmailServicePluginOptions.provider 与 CLI OS_EMAIL_PROVIDER 都接受 'smtp',并新增了 OS_EMAIL_SMTP_HOST / _PORT / _SECURE / _USER / _PASSWORD。

影响

• 用 EmailServiceConfig 类型标注 objectstack.config.ts 的作者写 provider: 'smtp' 会拿到类型错误(运行时其实可用 —— CLI 直接读 config.email,不过这个 schema)。
• 生成文档 content/docs/references/system/email-config.mdx 的 Allowed Values 仍只列三个值,注释也仍在劝人自带 transport。AI 作者读到的就是「SMTP 不受支持」—— 与运行时实际能力相反的 declared ≠ implemented。

建议改动

1. EmailProviderSchema 增加 'smtp'(纯加值,非破坏性,不需要 ADR-0087 conversion/migration)。
2. 重写该段 TSDoc:SMTP 由 plugin-email 内置(ADR-0012),nodemailer 为惰性 import。
3. 顺带说明 EmailServiceConfig.options 对 provider: 'smtp' 承载连接参数(host / port / secure / user / password),与 OS_EMAIL_SMTP_* 一一对应。
4. 按 AGENTS.md:pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated --fix,提交被证明过期的生成物(至少 email-config.mdx)。

验收

• EmailServiceConfig 类型接受 provider: 'smtp';
• 生成的 email-config 参考文档列出 smtp 并且不再宣称 SMTP 需要自带 transport;
• spec 的生成物门禁全绿。

[os-zhuang]

分诊(PM 循环,邮件线):接下,但本轮不派发 —— 两条阻塞都还没解除。

1. 等 plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 落地。现在就把 'smtp' 加进 EmailProviderSchema,会造成反方向的 declared ≠ implemented:spec 声明了一个 main 上还没有实现的 provider(SmtpTransport 目前只存在于 PR feat(plugin-email): SmtpTransport —— 真实 SMTP 投递、设置热替换、不再说谎的 mail/test (#5087) #5106 的分支上)。等 feat(plugin-email): SmtpTransport —— 真实 SMTP 投递、设置热替换、不再说谎的 mail/test (#5087) #5106 合入 main 之后再动,这一单就只是把契约追平既成事实。
2. spec 车道当前不可进。E1(#5040 执行器契约面):IMetadataService.matchEndpoint? / generateOpenApi? + IHttpServer.setFallbackHandler? 可选契约方法与契约测试 #5080 与 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 两单正在 packages/spec 内作业(均 pm:dispatched),而本单要碰 email-config.zod.ts 加上生成物 content/docs/references/system/email-config.mdx。生成物走 .gitattributes 的 merge=os-regen 驱动——它会让 merge exit 0、零冲突标记,却静默丢掉一侧的改动,只有整体重新生成才暴露。三单同时在飞正是踩这个坑的标准姿势,所以严格串行。

派发时会在派发词里带上:合并 origin/main 后整体重新生成(⛔ 绝不做文本合并),并断言兄弟单的条目与实现体都还在。

维护者若认为这条可以先行,随时否决——但请注意上面第 1 条,提前落地会让 spec 短暂地承诺一个 main 上不存在的能力。

---

Generated by Claude Code