docs(contracts): 以 contract.hook.ts 为唯一事实来源重写三语「合同激活时」小节 (#805)

.changeset/contracts-docs-activation-against-the-hook.md

@@ -0,0 +1,41 @@
+---
+'hotcrm': patch
+---
+
+Rewrite the Contracts page's "On contract activation" section against the hook
+that actually runs, in all three languages. Three of its four steps had no
+implementation behind them, and the one thing activation really does was missing.
+
+`contract_on_activation` (`src/objects/contract.hook.ts`) does exactly two things
+when a contract's status changes to *Activated*: it stamps **Signed Date** on the
+contract when the contract carries none yet, and it sets the account's **type** to
+*Customer* when the account is not already one. The page documented neither the
+signed-date stamp nor the true promotion condition, and promised three things
+instead:
+
+- a **Customer Since** date stamped on the account — `crm_account` has no
+  `customer_since` field, and no field of any name records when an account became
+  a customer, so the cohort report a reader would build on it cannot exist;
+- a **welcome email** to the primary contact, "(configurable)" — no outbound
+  customer mail is sent at activation and there is no setting behind one, the
+  same promise `content/docs/sales/contacts.mdx` made and lost in #796;
+- a **notification** to the account owner — the hook raises none, for the account
+  owner or the contract owner. The two contract `notify` nodes that do exist
+  belong to the daily expiration and renewal sweeps, not to activation.
+
+The surviving step is also stated more tightly than "if it was a Prospect": the
+hook promotes every account that is not already a *Customer*, so a *Partner* and a
+*Former Customer* are promoted too. Two mechanics that decide whether anything
+happens at all are now written down — the writes run after the save with failures
+logged rather than raised, and they hang off an **update**, so a contract that
+arrives already *Activated* (data import, seed data, an integration writing the
+record in one shot) triggers neither and leaves its account a *Prospect*.
+
+The admin tip on the same page is corrected with it: contract activation is an
+object hook, not a flow, so an admin who followed it to the flow list found
+nothing to customize.
+
+Documentation only — no metadata, behaviour or field changes. Whether HotCRM
+*should* send a welcome email or carry a `customer_since` field is a product
+decision and stays open; this change only stops the docs from claiming it already
+happens. Fixes #805.

content/docs/revenue/contracts.mdx

@@ -74,12 +74,14 @@ When the contract enters its renewal window, the system creates a follow-up task
 ## What the system does automatically
 
 ### On contract activation
-The owner promotes the contract to *Activated*:
+Changing a contract's status **to** *Activated* runs two writes, and only these two:
 
-1. **Account status → Customer** if it was a Prospect.
-2. **Customer Since date** stamped on the account if blank.
-3. **Welcome email** sent to the primary contact (configurable).
-4. **Notification** to the account owner.
+1. **Signed Date** stamped on the contract — today's date, and only when the contract has none yet. Set Signed Date in the same edit that activates the contract and your date is kept.
+2. **Account type → Customer** — every account that is not already a *Customer* is promoted, so this catches a *Partner* or a *Former Customer* just as it catches a *Prospect*.
+
+Nothing is sent and nobody is told. Activation raises no notification for the contract owner or the account owner, and no message goes to the primary contact — there is no outbound customer email here, and no setting behind one. There is no *Customer Since* field on the account either: an account keeps no date of its own for when it became a customer, so cohort reporting has to read the contract's signed date or start date.
+
+Both writes run *after* the save, with failures logged rather than raised, so the contract stays activated even if promoting the account fails. They also hang off an **update** — a contract that arrives already *Activated* (a data import, seed data, an integration that writes the record in one shot) triggers neither, and its account stays a *Prospect*.
 
 ### Daily — expiration sweep
 Each night at midnight the system finds *Activated* contracts whose end date has passed:
@@ -131,5 +133,5 @@ If your org wants contracts to follow the account, an admin has to author that,
 
 ## Tips for admins
 
-- The contract activation flow and expiration sweep can be customized. See [Administration › Automation](/docs/administration/automation).
+- Contract activation is an **object hook** (`src/objects/contract.hook.ts`), not a flow — that is where the signed-date stamp and the account promotion live, and it is not in the flow list. The expiration sweep and the renewal reminder *are* scheduled flows. See [Administration › Automation](/docs/administration/automation).
 - Contract types and billing frequency picklists are extensible.

content/docs/revenue/contracts.zh-Hans.mdx

@@ -74,12 +74,14 @@ description: 与客户签署的协议——条款、价值、续约，以及自
 ## 系统自动做的事
 
 ### 合同激活时
-所有者将合同提升为 *Activated*：
+把合同状态**改成** *Activated* 会触发两次写入，也只有这两次：
 
-1. 如果账户曾是潜在客户，则 **账户状态 → Customer**。
-2. 如果账户的 **Customer Since 日期**为空，则标记它。
-3. 向主要联系人发送**欢迎邮件**（可配置）。
-4. 向账户所有者发送**通知**。
+1. 在合同上盖 **签署日期**——写入当天日期，且仅当合同上还没有签署日期时才盖。如果你在激活的同一次编辑里一并填了签署日期，系统保留你填的值。
+2. **账户类型 → Customer**——凡是还不是 *Customer* 的账户都会被提升，所以除了潜在客户，合作伙伴和前客户也同样会被改成正式客户。
+
+不会发出任何东西，也不会通知任何人。激活既不给合同所有者发通知，也不给账户所有者发通知，主要联系人那边更是什么都收不到——这里没有面向客户的外发邮件，也没有哪个开关能打开它。账户上同样没有 *Customer Since* 字段：账户本身不记录自己何时成为客户，做同期群分析只能读合同的签署日期或开始日期。
+
+这两次写入都在保存**之后**执行，失败只记日志、不向上抛，所以即使账户提升失败，合同也已经是激活状态。它们还只挂在**更新**上——创建时就已经是 *Activated* 的合同（数据导入、种子数据、一次性写入整条记录的集成）两次都不会触发，其账户仍然停留在潜在客户。
 
 ### 每日——到期扫描
 每晚午夜，系统会查找结束日期已过的 *Activated* 合同：
@@ -131,5 +133,5 @@ description: 与客户签署的协议——条款、价值、续约，以及自
 
 ## 给管理员的提示
 
-- 合同激活流程和到期扫描可以定制。参见 [管理 › 自动化](/zh-Hans/docs/administration/automation)。
+- 合同激活是一个**对象 hook**（`src/objects/contract.hook.ts`），不是 flow——盖签署日期和提升账户都写在那里，流程列表里找不到它。到期扫描和续约提醒**才是**定时 flow。参见 [管理 › 自动化](/zh-Hans/docs/administration/automation)。
 - 合同类型和计费频率选项列表是可扩展的。

content/docs/revenue/contracts.zh-Hant.mdx

@@ -74,12 +74,14 @@ description: 與客戶簽署的協議——條款、價值、續約，以及自
 ## 系統自動做的事
 
 ### 合約啟用時
-所有者將合約提升為 *Activated*：
+把合約狀態**改成** *Activated* 會觸發兩次寫入，也只有這兩次：
 
-1. 如果帳戶曾是潛在客戶，則 **帳戶狀態 → Customer**。
-2. 如果帳戶的 **Customer Since 日期**為空，則標記它。
-3. 向主要聯絡人發送**歡迎郵件**（可配置）。
-4. 向帳戶所有者發送**通知**。
+1. 在合約上蓋 **簽署日期**——寫入當天日期，且僅當合約上還沒有簽署日期時才蓋。如果你在啟用的同一次編輯裡一併填了簽署日期，系統保留你填的值。
+2. **帳戶類型 → Customer**——凡是還不是 *Customer* 的帳戶都會被提升，所以除了潛在客戶，合作夥伴和前客戶也同樣會被改成正式客戶。
+
+不會發出任何東西，也不會通知任何人。啟用既不給合約所有者發通知，也不給帳戶所有者發通知，主要聯絡人那邊更是什麼都收不到——這裡沒有面向客戶的外發郵件，也沒有哪個開關能打開它。帳戶上同樣沒有 *Customer Since* 欄位：帳戶本身不記錄自己何時成為客戶，做同期群分析只能讀合約的簽署日期或開始日期。
+
+這兩次寫入都在儲存**之後**執行，失敗只記日誌、不向上拋，所以即使帳戶提升失敗，合約也已經是啟用狀態。它們還只掛在**更新**上——建立時就已經是 *Activated* 的合約（資料匯入、種子資料、一次性寫入整條記錄的整合）兩次都不會觸發，其帳戶仍然停留在潛在客戶。
 
 ### 每日——到期掃描
 每晚午夜，系統會查找結束日期已過的 *Activated* 合約：
@@ -131,5 +133,5 @@ description: 與客戶簽署的協議——條款、價值、續約，以及自
 
 ## 給管理員的提示
 
-- 合約啟用流程和到期掃描可以定制。參見 [管理 › 自動化](/zh-Hant/docs/administration/automation)。
+- 合約啟用是一個**物件 hook**（`src/objects/contract.hook.ts`），不是 flow——蓋簽署日期和提升帳戶都寫在那裡，流程列表裡找不到它。到期掃描和續約提醒**才是**排程 flow。參見 [管理 › 自動化](/zh-Hant/docs/administration/automation)。
 - 合約類型和計費頻率選項列表是可擴展的。