docs(revenue,sales): 按 contract.hook 与续约 flow 写实 Customer Since 幽灵与提醒收件人 (#824)

[yinlianghui]

Fixes #824

#805 / PR #823 只修了 revenue/contracts.mdx 三语。本 PR 收掉同一条幽灵声明剩下的两页(各三语),并按 contract-renewal.flow.ts 改掉同页的续约提醒收件人。

前提复核(逐条,基线 origin/main = a501812,#823 / #831 / #835 / #839 均已在其中)

⚠️ 派单提示 accounts.mdx ×3 今天被 #768 改过、revenue/index 被 #750 一族动过,故逐条在最新 main 上重核行号与事实:

issue 说法	复核结果
customer_since 不存在	成立。grep -rn "customer_since" src/ 零命中(exit=1);account.object.ts 的字段表里也没有任何其它名字记录「何时成为客户」——最接近的两个日期字段是 last_activity_date(:338)与 next_renewal_date(:383),都不是
激活只做两件事	成立。contract.hook.ts:104-119:合同上盖 signed_date(仅当为空)、account.type 改成 customer(仅当还不是);触发条件是 afterUpdate 且 input.status === 'activated' && previous?.status !== 'activated'
revenue/index.mdx:43 幽灵 bullet	成立,行号未变(en/zh-Hans/zh-Hant 均在 :43)
sales/accounts.mdx:69 幽灵 bullet	成立,行号未变(三语均在 :69)。#768 改的是同页别处,未触及本行
revenue/index.mdx:45 收件人过宽	成立,行号未变。contract-renewal.flow.ts 全流程只有一个 notify 节点 notify_owner,recipients: ['{currentContract.owner_id}'] 单值,channels: ['inbox','email'];crm_account.owner_id 与 crm_account.renewal_owner 在该 flow 中从未被读
同页其余 bullet	:42「Auto-promote account to Customer」与 :44「午夜到期扫描,通知所有者」经核属实(contract-expiration.flow.ts:26 是 0 0 * * *,notify 收件人同样是合同负责人),按「不动已对的部分」保留原样

改了什么(6 个文件,三语同步)

1. Customer Since 两处 —— 描述真实行为,不留幽灵引用

按 #823 已落的口径:两处都改成「激活真正做的那次写入 + 明说账户上没有这个日期 + 指出同期群该读哪儿」。没有默默删掉 Customer Since 这个名字——照着它找过的读者需要一个去处。

• revenue/index.mdx:43:原「Auto-stamp Customer Since date on the first activation」→ 改为写实的另一次写入(合同上的 Signed Date,仅当为空时盖),并写明账户上不盖任何日期、没有 Customer Since 字段、同期群只能读合同的 Signed Date / Start Date。
• sales/accounts.mdx:69:原「The Customer Since date is captured on the first contract activation」→ 改为账户侧真实发生的自动更新(Type 变成 Customer),后半句明说不随之记任何日期。这条留在「Automatic updates」小节里仍然成立,而这正是 issue 点名的危险处:它与同小节里真实的 last_activity_date、商机金额汇总、开放案例数并排。

刻意没有写「激活写回账户的就只有这一件事」这类全称句:account.hook.ts:118-121 在类型变化时会盖 last_activity_date(且仅限 ctx.user?.id 的用户写),hook 内 api 写入是否带用户上下文没有测试钉住,不在本 PR 断言。

2. revenue/index.mdx:45 续约提醒 —— 按 flow 写实

收件人从「the owner and the account owner」改为只有合同负责人(inbox + 邮件两通道),并明说账户所有者与账户上的续约负责人都收不到——这正是 issue 影响分析里那一条。

同句一并对齐(#794 先例,已披露)

改写 :45 这一句时,同句里另两处若原样保留就会与新句自相矛盾,故一并对齐:

• 「a reminder email」→ 任务 + 通知:notify_owner 之前的边序是 create_renewal_task → notify_owner(b4),任务先建。同页 lifecycle 第 5 步本来就写着「schedules a renewal task and a renewal reminder」,只改收件人而不提任务,会让同页两句对不上。(自动开续约商机那一步属 contracts 页深度,docs(contracts): 按到期/续约 flow 与 contract.object.ts 重写三语剩余三处失真 (#826) #831 已写全,本页概览不展开。)
• 「(e.g., 60 days before end)」→ Renewal Notice (Days),默认 30:contract.object.ts:157-162 是 defaultValue: 30,窗口是每份合同自己的值;凭空举例的 60 天既非默认值也非任何声明值。按 docs(contracts): 按到期/续约 flow 与 contract.object.ts 重写三语剩余三处失真 (#826) #831 在 contracts 页写下 defaultValue: 30 的同一口径对齐。

zh 两页的字段名按语言包拼写(#825 先例):签署日期 / 开始日期 / 续约通知（天）(zh-CN.ts:555/527/547);accounts zh 页的账户类型按语言包写作类型 = 正式客户(zh-CN.ts:64-66),与该页 :119/:121 已有的写法一致,不引入页面里没有的「客户类型」。

越界发现(已单独立单 #840,本 PR 未修改)

grep 换拼法后发现同一条幽灵声明还剩最后 6 处,全在 content/docs/ai-copilot/:sales-copilot 的 Customer 360°「关系快照」与 service-copilot 的案例分诊「客户画像」各三语,英文页写作 customer-since(带连字符)、zh 页写作「成为客户的日期」,所以前三轮按 Customer Since 关键字的搜索都没扫到。两个技能的 instructions(src/skills/customer-360.skill.ts、case-triage.skill.ts)里也没有这个数据点。已按越界纪律另立 #840(不带 label、未 assign),先做过关键字 + 文件路径去重搜索,无同类在途单。

其它

不为散文加钉子测试(与 #805 / #765 同)。仅文档:无 metadata / 行为 / 字段变更,src/** 与 content/docs/releases/ 未动。要不要在 crm_account 上加 customer_since 仍是产品决定,本 PR 只是让文档不再声称它已经存在。本 PR 未新增任何链接。

changeset:.changeset/customer-since-ghost-and-renewal-recipient.md(hotcrm, patch)。

验证

全量四件套 + lint + hygiene(flock -w 7200 /tmp/os-heavy-verify.lock,NODE_OPTIONS=--max-old-space-size=4096,vitest --maxWorkers=2):

pnpm validate  → 17 Objects 344 Fields / 24 Flows     VALIDATE_EXIT=0（5 条 warning 均为既有 approval / campaign_member 项）
pnpm typecheck → tsc --noEmit                          TYPECHECK_EXIT=0
pnpm hygiene   → ✓ source hygiene clean                HYGIENE_EXIT=0
pnpm build     → Artifact: dist/objectstack.json       BUILD_EXIT=0
pnpm lint      → 13 warning(s), 14 suggestion(s)       LINT_EXIT=0（均为既有,与本 PR 无关）
pnpm test      → Test Files 66 passed (66)
                 Tests 1587 passed | 1 skipped (1588)

控制字符:pnpm hygiene 现已覆盖 content/(#835 已落地,自报「the control-byte scan adds 382 under content, .changeset」),另对本次 6 个 mdx + changeset 做了越出 gate 的自扫:

grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' content/docs/revenue/index*.mdx \
  content/docs/sales/accounts*.mdx .changeset/customer-since-ghost-and-renewal-recipient.md
→ 零命中（exit=1）

---

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 5, 2026 11:15pm