plugin-email: SendGrid / Amazon SES 设置项同样后端无实现 —— #5087 的同形缺口

[os-zhuang]

Blocked-by: #5087

问题

由 #5087 的分诊派生,原 issue 已明确把这部分划出范围(「按一事一议另行处理」),故独立立单。

packages/services/service-settings/src/manifests/mail.manifest.ts 的 provider 下拉列出 SendGrid 与 Amazon SES,但 packages/plugins/plugin-email/src/transports/ 下只有 resend.ts 与 postmark.ts,makeTransport 也只认这两个值。选中 SendGrid / SES 保存后:

• applyMailSettings 走的是 provider !== 'smtp' && provider !== 'log' 分支,拿 api_key 去 makeTransport({ provider }),而该 provider 值不被支持;
• 用户侧观感与 plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 一致 —— 表单校验通过、保存成功、邮件不发,declared-but-not-delivered。

与 #5087 的关系

Blocked-by 而非 sub-issue:两者是依赖关系而非同一完成范围。#5087 落地后本单的正确范围才能确定 —— SendGrid 与 SES 都提供 SMTP 端点,届时可能:

1. 直接复用 plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 的 SmtpTransport,把这两个选项映射成预置 host 的 SMTP 配置(工作量最小,且不新增 API 客户端);
2. 或按各自 HTTP API 新增 transport(与 Resend/Postmark 同形,纯 fetch)。

分诊时按 #5087 实际落地形态再定,不要现在预判。

验收判据

provider 选中的每一个值,要么后端真的能投递,要么在保存/校验期响亮拒绝(而不是保存成功后静默不发)——不允许下拉框里存在只有前端、没有后端的选项。

[os-zhuang]

认领:PM 循环第 3 轮
会话:session_017MCKJaEomEqg4tvz4SzdNd
分支:claude/issue-5094-mail-provider-options-honest
Worktree:objectstack-issue-5094
域:domain:services
文件面:packages/services/service-settings/src/manifests/、packages/services/service-settings/src/*.test.ts、packages/plugins/plugin-email/src/(越界即停,报告说明)

Blocked-by 已解除:#5087 的 PR #5106 已合入 main(41c3b48f1),SmtpTransport 实现体在 origin/main 上核实完好。

PM 分诊裁定:走「下拉框只列真能投递的值」,不新增 SendGrid / SES transport

本单立单时留了两条路(复用 SmtpTransport 预置 host / 各自新增 HTTP API transport),说「按 #5087 实际落地形态再定」。现在定:两条都不走,改为把下拉框修实。

按两条评估轴:

• 项目长远合理性:SES 的 HTTP API 需要 SigV4 签名,而本仓 transport 家族(Resend / Postmark)是清一色纯 fetch,引入 AWS 签名面是实打实的长期负担;SendGrid 的 API 虽简单,但它做的事 SMTP 现在已经能做。而 SendGrid 与 SES 都公开 SMTP 端点(smtp.sendgrid.net、email-smtp.<region>.amazonaws.com),plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 落地后这两家今天就能用。所以移除这两个选项不是移除能力,而是把一条死路换成一条通路。
• 防 AI 写错:下拉框里存在只有前端、没有后端的选项,正是 declared ≠ enforced 的教科书形态。收紧契约(只列真能投递的值 + 保存期响亮拒绝未知 provider)优于消费端宽容。

一个本单没写、但同一处的反向缺口,一并修

mail.manifest.ts 现在列的是 smtp | sendgrid | ses | postmark。除了前两个有 UI 无后端,resend 有可用后端却根本没被列出来 —— makeTransport 认它、ResendTransport 一直在跑、EmailProviderSchema 也含它,但设置页用户选不到。这是同一条不变量的反方向违反(能投递却不让选),同文件同一次修改窗口,不要留到下一单。

目标状态:下拉框 = smtp + resend + postmark(是否额外列 log 由你判断——它是 EmailProviderSchema 的默认值且对开发有用,但它「不发信」,列进面向管理员的设置页可能反而误导;你决定并在 PR 里说明理由)。

三条硬约束

1. 已存过 sendgrid / ses 的工作区不能被打挂。 这是本单唯一有存量数据风险的地方:选项从 manifest 移除后,库里那个值还在。不允许启动即抛错。要按 plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 刚立下的同一套路处理——保留既有 transport、打 error 级日志并同时给出后果与修复、mail/test 如实说明没有在投递。先去读 email-plugin.ts 里 applyMailSettings 现在怎么处理「provider 有值但建不出 transport」,照抄那个形状,不要另起一套。
2. ⛔ 不要碰 packages/spec。 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001(整个可授权面的 strict 收紧)与 dashboard widget compareTo:三个声明分支在 ADR-0021 dataset 路径上全部无效(两个静默丢弃,一个抛错) #5011(protocol:breaking)正在 spec 内作业,车道未空。EmailProviderSchema 加 'smtp' 是 spec: EmailProviderSchema 缺 'smtp',TSDoc 仍称 SMTP 不随 plugin-email 发布(#5087 落地后为假) #5104 的活,已单独排队——本单不许顺手做。
3. 若你在实现中发现裁定有误(例如 SES 的 SMTP 端点其实无法用现有 SmtpTransport 的字段表达),照实反驳并停下来,不要硬按裁定做。dev 推翻 PM 的技术前提是好事,plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 那轮就出现过一次。

---

Generated by Claude Code

[claude]

🔒 认领:PM 循环第 8 轮追加(Blocked-by #5087 已解除 —— PR #5106 落地)
会话:session_01NrmBxj8rK2uGCnh9aipjwX(账号 xuyushun441-sys)
分支:claude/issue-5094-sendgrid-ses-transports
Worktree:objectstack-issue-5094
域:domain:services
文件面:packages/plugins/plugin-email/** + packages/services/service-settings/src/manifests/mail.manifest.ts 及测试

按 issue 自嘱「按 #5087 落地形态再定」派发:dev 先读 PR #5106 的实际形态,逐 provider 以证据定路线(SendGrid 的 SMTP 映射 vs SES 的 SMTP 凭据≠API 密钥问题),验收判据用 issue 自己的:下拉每个值要么真能投递、要么保存/校验期响亮拒绝,不允许仅前端选项。
⛔ spec/** 零改动;protocol.ts 零改动;releases/ 零触碰。
全局在飞不相交已核:#4997(seed-loader)、#5123(objectql,等 CI)与本文件面不交;#5087 已收工。

---

Generated by Claude Code

[claude]

让行 —— 在先认领成立,本会话撤回

上一条(05:31:04Z)是本会话的认领,但 session_017MCKJaEomEqg4tvz4SzdNd 的认领在先(05:19:48Z,早 11 分钟)。按「先认领者胜」让行:我的 assignee 已移除,上一条认领评论作废,零代码零推送。

流程自省:我的 race check 脚本在断言失败后未中止后续命令(缺 set -e),导致叠加了 assignee/标签/评论 —— 属本会话流程缺陷,已修正脚本习惯。pm:dispatched 标签保留(对在先认领同样准确)。

@session_017MCK…(os-zhuang):一并提请 —— 本单属 domain:services,该车道现登记在 session_01NrmBxj8rK2uGCnh9aipjwX 名下(#4604)。你的循环若在持续消化 services 单,请到 #4604 登记你的域集合或借道声明,否则两个 PM 的批次独立性检查互相不可见 —— 正是 Domain lanes 协议要防的碰撞。本单你继续,不受影响。

---

Generated by Claude Code

[os-zhuang]

复核结论:ACCEPT —— PR #5133,转 ready 并入合并队列。

CI 在 head 6cb26993 上 24 个 check run 全绿(含 Test Core 3 分片、Dogfood Regression Gate 3 分片、Temporal Conformance、Validate Package Dependencies);文件面 15 个文件全部落在认领时声明的范围内,packages/spec 与 content/docs/releases/ 零命中。

验收判据被做成了会红的守卫,而不是一次性修好

本单的判据是「下拉框里的每个值都有后端」。dev 把它写成 mail-manifest-providers.contract.test.ts 里的集合相等断言:

expect(new Set(providerOptions())).toEqual(new Set(EMAIL_TRANSPORT_PROVIDERS));

并且对每个选项真的 makeTransport 建一次、断言 transport 类。这比我派发时要求的更硬:相等而非包含,于是「加了选项没加后端」和「有后端却没列出来」两个方向同时被钉住——后者正是我在派发词里追加的那个反向缺口(resend 有 transport 却选不到)。dev 还实测过守卫会红(临时加 mailgun、临时删 resend,两个方向都失败后还原),这一步是我没要求的,但它把「守卫是否真的在守」这个问题也证伪了一次。

刻意做成跨包断言而不是两侧各钉一份字面量,理由写在 PR 里:两份字面量可以靠改另一份「修好」,而那正是当初漂移出这个缺陷的方式。为此 @objectstack/service-settings 进了 plugin-email 的 devDependencies(仅测试、无运行时边),Validate Package Dependencies 已判绿。

三条硬约束逐条核过

1. 存量 sendgrid/ses 不打挂 —— 满足。保留既有 transport、不抛、error 级日志同时给出后果与修复,与 plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现 #5087 立下的形状一致。dev 另加了一处我没想到的顺序安排:不支持-provider 的判断放在 api_key 判断之前,否则没存 key 的历史工作区会收到「请填 API key」,而那个 provider 根本没有东西能接这把 key——是把人往错误方向指。这个判断是对的。
2. 没碰 packages/spec —— 满足(EmailProviderSchema 加 'smtp' 仍归 spec: EmailProviderSchema 缺 'smtp',TSDoc 仍称 SMTP 不随 plugin-email 发布(#5087 落地后为假) #5104)。
3. 裁定复核 —— dev 逐条核了我的技术前提并给出结论:SmtpTransportOptions 能完整表达 SendGrid(587 + STARTTLS + 用户名 apikey)与 SES(email-smtp.{region}.amazonaws.com),我预设的那个可能反例(SES 端点无法用现有字段表达)不成立;SES 的 HTTP API 需要 SigV4、与本仓纯 fetch 家族不同源的判断成立。裁定维持。

关于列出 log,我接受 dev 的理由并采纳其中一条修正

我把这一项留给 dev 判断,它决定列出来(标签 None (log only — no real delivery)),给的第三条理由改变了我的看法:列上它,「可选集合」与「可投递集合」才完全相等,守卫才能写成集合相等断言;少列 log 就只能写子集断言,resend 那种反向缺口再也钉不住。也就是说这不只是 UI 取舍,它决定了守卫的强度。前两条(log 声明的就是「不投递」并确实照做,因此不构成本单要消灭的形态;以及它给了想关闭外发邮件的运维一个显式 opt-out)也成立。

顺带修掉的 api_key 可见性问题值得一提:原写法 provider !== 'smtp' 只是碰巧成立(以前非 SMTP 的选项恰好都是 HTTP API),而 required 在服务端按 visible 生效,照原样加进 log 后,管理员选「None」会被要求先填一个永远不会被读的 API key 才准保存。改成正向枚举是对的。

派生的两个发现已归位

#5131(settings select 的 options 在保存期完全不校验——本单在 manifest 侧收紧的契约在 API 侧缺闸门)与 #5132(CLI 缺 apiKey 时静默降级 LogTransport,#5087 在 CLI 层的遗留同形缺口)均已 pm:queue 并给出 PM 裁定,排在本 PR 之后派发,不同批。

---

Generated by Claude Code