docs(marketing): campaign metrics are live, not snapshotted at completion

[os-steve]

Closes #1691

Two customer-facing marketing pages still described the completion-time metric snapshot that #597 retired. The metric block is kept live by four refresh hooks — campaign_metrics_refresh, campaign_attribution_refresh, campaign_lead_conversion_refresh (campaign.hook.ts) and campaign_member_metrics_refresh (campaign_member.hook.ts) — so the numbers move as members are enrolled, as members respond, as their leads convert and as opportunities are attributed. Completion is one more status transition over numbers that were already current, exactly as campaign-completion.flow.ts's header has said since #1668 / PR #1690, which is the wording reference this PR follows.

The harm, and the acceptance bar

The defect was directional, not merely factual. A reader following these pages would expect an in-progress campaign to report zeros, and would therefore distrust the live dashboard numbers — the docs talked them out of a feature that works. So every page now states the live behaviour positively in its own bullet rather than only dropping the false claim. The reader finishes knowing the numbers are usable right now, and also knowing what completion does do (it flips the status), so that step does not read as if nothing happens.

Three stale lines per locale face, not two

file	line	was
marketing/campaigns.mdx	16	Completed | Finished — metrics are final, ROI is calculated
marketing/campaigns.mdx	58	… final metrics (sent, responded, converted, ROI) snapshot at that moment
marketing/index.mdx	29	Completed — campaign ends; metrics are snapshotted

The status-table row was wrong in both halves: metrics are not final (a completed campaign's numbers still move — enrolling a member into one is precisely the case flow-campaign-enrollment guards against), and roi is a formula over actual_cost / actual_revenue, evaluated on read. It is never "calculated" at a moment; it has always had a value.

⭐ The difference set — reported as the card requires

Search A (identifier/keyword, snapshot|快照 across content/docs) — 63 files. Every non-marketing hit was classified and none is this defect, so nothing was over-deleted: sales/forecasting (a forecast genuinely is a frozen snapshot — a real, current feature), analytics/cubes (says nothing snapshots the pipeline), analytics/dashboards (reads forecast snapshots), marketplace/* (immutable sys_package_version), customization/testing-and-ci (vitest toMatchSnapshot), ai-copilot/* ("Account Snapshot" as a section name; sales-copilot explicitly says "not a cached snapshot"), administration/*, service/index, guides/import-and-export, reference/security-and-compliance. In scope, Search A finds campaigns.mdx:58 and index.mdx:29 (×3 faces).

Search B (behaviour description) — final metrics · at that moment · when/once the campaign completes · metrics are (final|frozen|locked) · at completion · no longer change · stops updating, and the Chinese equivalents 完成时 · 最终指标 · 指标最终确定 · 定格 · 冻结 · 不再变化.

B \ A is NOT empty: campaigns.mdx:16 × 3 faces. "metrics are final, ROI is calculated" carries the retired model and contains no occurrence of snapshot. This is the card's own lesson reproduced one level down: a keyword search finds the bullet at line 58 and stops 42 lines short of the same claim on the same page. An auditor working from the identifier would have fixed line 58 and left the status table telling readers the numbers are final. Notably even a proximity search (campaign within 120 chars of a finality word) misses it, because the table row never says "campaign" — only the un-anchored phrase search reached it.

A \ B in scope is empty — no other page carries this defect.

Checks the dispatch asked for

• Doc-wording pin tests — checked before editing. No docs-* test asserts these sentences; grep for every fragment across test/ and scripts/ returns nothing. docs-view-rosters does read campaigns.mdx, but only its Standard list views roster section. automation-docs-coverage reads administration/automation.mdx only. docs-metadata-counts walks every .mdx but matches digit-form counts of objects/flows/dashboards/datasets/actions/positions — the new prose states no count. Nothing went red; no assertion was touched.
• campaign-members.mdx (×3) — checked, needed nothing. It already said the campaign-level metrics are "always live" / 「始终是实时的」/「始終是即時的」, so the two corrected pages had been contradicting their own sibling page. Its register is the vocabulary these fixes adopt.
• Third candidate test/flow-campaign-enrollment.test.ts:121 — read, deliberately NOT changed. Reasoning below.
• No new gate, no new test (AGENTS.md:431). content/docs/releases/ untouched. Surface stayed inside content/docs/marketing/**; no overlap with Retire crm_case.customer_rating / customer_feedback under ADR-0049, and retire or rewrite case_csat_followup with them (ruled A, 2026-09-03; the internal_notes half landed in PR #1506) #1428 or [finding] ~25 form fields author an absolute colSpan, and objectstack validate warns every one of them #1524.

Why the third candidate was left alone

The comment reads "Enrolling into a finished campaign corrupts its final snapshot metrics." Its operative claim is true, and true only because of the live model: under the retired snapshot the metric block was written once on → completed, so a late enrolment could not have disturbed it. It is the live refresh (campaign_member_metrics_refresh firing on member insert) that makes a late enrolment move a completed campaign's numbers at all — which is exactly the harm the guard prevents. Only the two words "final snapshot" carry the old vocabulary; the sentence is not misinforming anyone.

It is also an internal test rationale, not published documentation, so it cannot produce this card's harm — no reader is talked out of trusting the dashboard by it. Changing it would widen a docs card's diff into test/ for a vocabulary preference. Left as-is, per the card's own "worth a read, not asserted as wrong" and the PM's "read it and decide". Not filed as a separate issue either: #1691 already records it, and a new card would duplicate that text.

Verification

pnpm verify fully green at 7c9af2e5 — all eight stages ran (validate → typecheck → lint → lint:i18n-gate → hygiene → hygiene:tokens → build → test):

✓ i18n lint gate: 0 `i18n/missing-*` issues (13 total lint issue(s) reported, unaffected by this gate)
 Test Files  161 passed (161)
      Tests  3414 passed | 1 skipped (3415)
   Duration  204.90s
VERIFY_EXIT=0

All three locale faces were written, not machine-translated, reusing the vocabulary already on these pages (发送/响应/转化 · 傳送/回應/轉化, 线索 · 潛在客戶) and the 实时 / 即時 register campaign-members established. One changeset (patch).

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 6, 2026 11:21am UTC