docs(automation): spell the merge-field example with this app's real names (#863)

[yinlianghui]

Fixes #863

改了什么

content/docs/administration/automation{,.zh-Hans,.zh-Hant}.mdx「电子邮件模板」节的合并字段 bullet 一行 ×3 语言,其余一行未动。

改前(三语同形):

- **Merge fields** — {{Opportunity.Name}}, {{Account.Owner.Email}}.

Opportunity / Name / Account.Owner.Email 在本仓不是任何对象或字段的拼写,是 Salesforce 式 PascalCase 的借用。本仓的对象是 crm_opportunity / crm_account / crm_contact,字段是 name / owner_id / email,而 AGENTS.md 对此是硬约束(复核仍在):

The name in source = the name at runtime = the name in DB = the name in URL = the name in docs. No translation layer.

同页其余引用字段的地方(flow 表的 end_date、expiration_date、owner_id)用的都是真实拼写,只有这一条例外。管理员在 设置 → 电子邮件模板 里照抄它,写出来的路径对不上任何值。

改后(英文,中文两版同义):

- **Merge fields** — {{path.to.value}} placeholders, rendered against the data payload
  passed on that send. Spell every segment the way HotCRM spells it — objects are
  crm_opportunity and crm_contact, fields are name, owner_id, email — never
  Salesforce-style Opportunity.Name. What the path is rooted at depends on the payload
  shape the sender passes, and this app ships no sendTemplate() caller to copy one from,
  so declare the names your template reads in its variables list and agree the shape with
  whoever sends the mail.

stale-premise 复核(rc.3 基线)

issue 的两条 spec 主张在 17.0.0-rc.3 上逐字复核,均成立 —— node_modules/@objectstack/spec/src/system/email-template.zod.ts:

• 头注释:"subject/body strings carry simple {{path.to.value}} placeholders rendered against a per-send data payload" → 占位符语法本身是对的,本 PR 不动语法,只动路径拼写。
• EmailTemplateDefinitionVariableSchema.name 的 describe:"Variable name as referenced in placeholders (snake_case or dotted path)" → snake_case 正是本仓的命名法。

{{Opportunity.Name}} / {{Account.Owner.Email}} 在本仓 content/ 内仅这 3 处命中,全部改掉。

为什么不写 {{record.name}} 这类前缀形状

issue 给的两个选项里采用「不依赖载荷形状」的一个。占位符路径从哪一层写起,取决于每次发送传入的 data 载荷形状,该形状由 sendTemplate() 的调用方决定;而本仓没有任何调用方可供实测 —— sendTemplate 与 email_template 在 src/ / content/ / objectstack.config.ts 下零命中,与 #834 在编译产物里的结论一致。

所以这一行只承诺两件本仓能证明的事:拼写用真名,以及路径根部由发送方决定;并把作者指向模板自己的 variables 列表(spec 里声明占位符名字的地方),而不虚构 {{record.name}} / {{crm_opportunity.name}} 之类未经实测的形状当作「正确答案」。

边界

• 同页其余部分(含 automation 三语的「内置模板涵盖潜在客户路由、商机赢单、案例确认、合同激活、续约提醒」—— 本仓一个邮件模板都没有 #834/docs(automation): retire the workflow-rules section in all three locales (#833) #854/docs(automation): 按 flow 源码写实内置流程表两行，并修 opportunity_won_alert 的 description (#851) #870/docs(automation,opportunities): 补回 zh 两页缺的预测分工段，并按语言包对齐 best_case / closed_amount 词 (#836, #845) #879/docs(i18n): spell the lead convert verb 转化 on every Chinese page (#844) #906 已落地内容)一行未动;与本轮并行的 「工作流规则」清扫后仍有 bare workflows 残留族：faq / performance-and-limits 的「重新评估 5 次后停止」是 PR #854 已判虚构那条说法的未清扫副本，quotes:141 指向不存在的配置面 #899 明确排除 automation 页,无交叠。
• 三语同步,术语沿本仓既有口径:载荷 / 酬載(对齐 integrations 页 payload 的三语译法)、调用方 / 呼叫方。
• 纯文档,不涉及元数据、行为或字段;@objectstack/* 版本与 releases/ 未触碰。
• changeset:.changeset/automation-docs-merge-field-spelling.md。

验证

本地全绿(退出码均为 0):

门	结果
pnpm validate	✓ Validation passed (3278ms);警告与 main 同(approval 空审批人 ×4、campaign_member 分组)
pnpm typecheck	✓ tsc --noEmit 无输出
pnpm lint	✓ 13 warning(s), 14 suggestion(s) —— 与 main 同,均非本改动引入
pnpm hygiene	✓ 415 files under content/.changeset 控制字节扫描通过
pnpm build	✓ Build complete;dist/objectstack.json 1921.4 KB
pnpm test -- --maxWorkers=2	✓ Test Files 66 passed / Tests 1587 passed, 1 skipped

守卫盲区如实说明:本仓没有针对文档正文的断言测试(仅 scripts/check-source-hygiene.mjs 对 content/ 做控制字节与体积扫描),因此这三行文字的正确性由上面的源码比对承担,而不是由某个门把守 —— 对这三行,所有门的 predicted 结果都是 GREEN,实测亦然。push 前对四个改动文件做了控制字节自扫 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]',无命中。未起 dev server。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 7:55am