From ea13e87a70f746f083b146f200781cede2c26aba Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 20:51:48 +0000 Subject: [PATCH] docs(sales): rewrite the lead/contact block tables against fieldGroups, and the welcome prompt against the flow (#792, #796) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "what a record stores" table at the top of the Leads and Contacts pages (and their zh-Hans / zh-Hant siblings) described a field layout the objects never declared, so a reader looked for a field in the wrong section — or for a field that does not exist at all. Leads. `crm_lead` has no `tags` field (grep over the object finds the key only on `crm_knowledge_article`), so the Additional Info row is rewritten from the real `additional` group: annual_revenue, number_of_employees, description, notes. Those first two were listed under Company Information, and `website` too, though it is declared in `contact_info` — all three rows move. The object declares TEN fieldGroups (lead.object.ts:17-28); the page counted nine and had no row for `duplicates` at all, even though the same page teaches you how to work duplicates further down. That group is now a row of its own, and `company_normalized` is named as the hidden match key it is rather than silently dropped. The lead intro no longer attributes those groups to the detail SCREEN. `crm_lead` is the one documented object with an authored record page, and `lead_detail.page.ts:147-178` curates five `record:details` sections of its own (Lead Information / Contact / Lead Detail / Address / Description) — while `lead.view.ts:197` authors six collapsible FORM sections. Neither is the object's ten groups, so "the detail screen has N collapsible sections" is not a sentence the metadata supports at any N. The table is now stated for what it is: the record's declared field groups. Contacts. `is_primary` is declared in `preferences`, not `account_info` (contact.object.ts:165-170), and `reports_to` in `account_info`, not `additional` (:110) — the two rows that named them are swapped back. The table never mentioned `owner_id` (:28), `avatar` (:72) or `last_contacted_date` (:195), which are real members of Account & Role, Identity and Additional Info; they are listed now, and the Mailing Address row names the five fields it holds instead of "full structured address". Built-in rules. `contact_welcome` is not an email template: it is the name of a record-change flow and of its notify topic (contact-welcome.flow.ts:23, :75). The notification goes to the contact's OWNER on the inbox and by email — "Reach out to welcome them" (:71-79) — and the start condition requires `has(record.owner_id)` (:66-67), so a contact written without an owner (seed data, an integration, any `runAs: 'system'` write — #548) produces no notification at all. The page promised the new contact a welcome email; nothing reaches them, and no outbound welcome mail ships. The admin tip pointing at "email-template settings" for the same non-existent template is corrected with it, since leaving it would restate the claim two screens down. Chinese pages follow the shipped zh-CN pack for every cell they rewrite. The two objects deliberately differ there: `crm_lead.email_opt_out` is 拒收邮件 (zh-CN.ts:373) while `crm_contact.email_opt_out` is 拒绝邮件 (:178), so each page follows its own object rather than being unified. Documentation only — no metadata, behaviour or field changes. Fixes #792 Fixes #796 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa --- .changeset/lead-contact-field-group-tables.md | 40 +++++++++++++++++++ content/docs/sales/contacts.mdx | 14 +++---- content/docs/sales/contacts.zh-Hans.mdx | 14 +++---- content/docs/sales/contacts.zh-Hant.mdx | 14 +++---- content/docs/sales/leads.mdx | 19 ++++----- content/docs/sales/leads.zh-Hans.mdx | 17 ++++---- content/docs/sales/leads.zh-Hant.mdx | 17 ++++---- 7 files changed, 89 insertions(+), 46 deletions(-) create mode 100644 .changeset/lead-contact-field-group-tables.md diff --git a/.changeset/lead-contact-field-group-tables.md b/.changeset/lead-contact-field-group-tables.md new file mode 100644 index 000000000..ae1e5d11f --- /dev/null +++ b/.changeset/lead-contact-field-group-tables.md @@ -0,0 +1,40 @@ +--- +'hotcrm': patch +--- + +Sales docs: rewrite the lead / contact "what a record stores" tables against the +objects' field groups, and describe the new-contact prompt as the owner +notification it is. + +The block tables at the top of the Leads and Contacts pages (and their zh-Hans / +zh-Hant siblings) claimed a field layout the objects never declared, so a reader +went hunting in the wrong section — or for a field that does not exist: + +- **Leads** listed a *tags* field. `crm_lead` has no such field; it is removed, + the same ghost-field class fixed in the previous pass. Annual revenue, number + of employees and website were listed under **Company Information**; the first + two are declared in `additional` and the third in `contact_info`, so all three + rows move. `crm_lead` declares **10** field groups, not the 9 the page + counted: the whole **Duplicate Management** group was missing from the table + even though the same page teaches you how to work duplicates further down, and + it is now a row of its own. +- The lead intro no longer says the *detail screen* has these collapsible + sections. `crm_lead` is the one object with an authored record page, and its + Details tab curates five sections of its own — so the table is now stated for + what it is, the record's declared field groups, rather than as a map of a + screen that groups them differently. +- **Contacts** put the primary-contact flag under **Account & Role** and + reports-to under **Additional Info**; `is_primary` is declared in + `preferences` and `reports_to` in `account_info`. The contact owner, the + profile picture and the last-contacted date were absent from the table + entirely, and the mailing address row now names the five fields it holds. +- The **Built-in rules** section promised a *contact_welcome* email template + sent to the new contact. Nothing of the sort ships: `contact_welcome` is the + name of a record-change flow and of its notification topic, the notification + goes to the contact's **owner** on the inbox and by email ("Reach out to + welcome them"), and it is skipped entirely for a contact with no owner — the + seeded and integration-written records — or with *Email Opt Out* ticked. The + admin tip pointing at "email-template settings" for the same non-existent + template is corrected with it and now names `src/flows/contact-welcome.flow.ts`. + +Documentation only; no metadata, behaviour or field changes. diff --git a/content/docs/sales/contacts.mdx b/content/docs/sales/contacts.mdx index 8b59f4b66..278161782 100644 --- a/content/docs/sales/contacts.mdx +++ b/content/docs/sales/contacts.mdx @@ -13,12 +13,12 @@ The contact detail screen has 6 collapsible sections: | Section | Fields | | --- | --- | -| **Identity** | Salutation, first name, last name, full name | -| **Account & Role** | Account, job title, department, primary contact flag | +| **Identity** | Salutation, first name, last name, full name, profile picture | +| **Account & Role** | Contact owner, account, job title, department, reports-to | | **Contact Information** | Email, phone, mobile | -| **Mailing Address** | Full structured address | -| **Additional Info** | Description, birthday, lead source, reports-to | -| **Communication Preferences** | Email opt-out, do-not-call | +| **Mailing Address** | Mailing street, city, state/province, postal code and country — five separate fields | +| **Additional Info** | Birthday, lead source, description, last contacted | +| **Communication Preferences** | Primary contact flag, do-not-call, email opt-out | ## The primary contact @@ -59,7 +59,7 @@ Both are ordinary editable checkboxes: anyone who can edit the contact can set o ## Built-in rules - An **email address must be unique within your organization**. The same address cannot be used by two contacts, even when those contacts sit under different accounts — the second save is rejected with *"Another contact … with email … already exists."* Another organization on the same platform is free to have its own contact at that address; the rule is scoped to your data, not the whole platform. Email is normalised to lower case before it is stored and compared, so `Ada@Example.com` and `ada@example.com` count as the same address. A person you deal with at two companies therefore needs a different address on each contact record. -- **Welcome email** — when a contact is created, the system automatically sends them the *contact_welcome* email template. +- **New-contact prompt** — creating a contact notifies its **owner**, in the inbox and by email: *"… was added as a contact. Reach out to welcome them."* Nothing is sent to the contact: *contact_welcome* is the name of the flow and of its notification topic, not an email template, and HotCRM ships no outbound welcome mail. Two cases raise no prompt at all — a contact with **no owner** (records written by seed data or an integration carry none) and a contact with **Email Opt Out** ticked. ## Sharing — who can see which contact @@ -99,5 +99,5 @@ So *"Draft a follow-up to Jane"* gives you a personalised, on-brand email in sec ## Tips for admins - The list of departments (Sales, Marketing, Engineering, Finance, IT, Operations, HR, Legal, Executive, Other) is configurable per the picklist values. See [Customization › Extending Objects](/docs/customization/extending-objects). -- The welcome email template can be customised in your email-template settings. +- The new-contact prompt is a flow, not a template: edit `src/flows/contact-welcome.flow.ts` to change its wording, its channels, or who it goes to. There is no email-template setting behind it. - Sharing inheritance from accounts means you generally never need account-specific contact sharing rules. diff --git a/content/docs/sales/contacts.zh-Hans.mdx b/content/docs/sales/contacts.zh-Hans.mdx index 054635567..b17df19a1 100644 --- a/content/docs/sales/contacts.zh-Hans.mdx +++ b/content/docs/sales/contacts.zh-Hans.mdx @@ -13,12 +13,12 @@ description: 你向其销售并为其提供服务的客户处的人——决策 | 区块 | 字段 | | --- | --- | -| **身份** | 称谓、名、姓、全名 | -| **客户与角色** | 客户、职位、部门、主要联系人标志 | +| **身份** | 称谓、名、姓、全名、头像 | +| **客户与角色** | 联系人负责人、所属客户、职位、部门、直属上级 | | **联系信息** | 邮箱、电话、手机 | -| **邮寄地址** | 完整的结构化地址 | -| **附加信息** | 描述、生日、线索来源、汇报对象 | -| **沟通偏好** | 拒绝邮件、禁止致电 | +| **邮寄地址** | 邮寄地址、邮寄城市、邮寄省份、邮政编码、邮寄国家（五个独立字段） | +| **附加信息** | 生日、线索来源、描述、最近联系时间 | +| **沟通偏好** | 主要联系人、禁止致电、拒绝邮件 | ## 主要联系人 @@ -59,7 +59,7 @@ CEO ## 内置规则 - **邮箱地址在你所在的组织内必须唯一**。同一个地址不能同时用于两个联系人，即使这两个联系人隶属于不同的客户——第二次保存会被拒绝，并提示 *"Another contact … with email … already exists."*。同一平台上的其他组织可以有自己使用该地址的联系人——这条规则只作用于你自己的数据，而不是整个平台。邮箱在存储和比较前会统一转为小写，因此 `Ada@Example.com` 与 `ada@example.com` 视为同一个地址。因此，若同一个人同时在两家公司与你往来，两条联系人记录需要各自使用不同的邮箱地址。 -- **欢迎邮件**——当创建一个联系人时，系统会自动向其发送 *contact_welcome* 邮件模板。 +- **新联系人提醒**——创建联系人时，系统会通知这条记录的**负责人**，站内收件箱和邮件各一份：*"… was added as a contact. Reach out to welcome them."*。联系人本人收不到任何东西：*contact_welcome* 是这条流程的名字和它的通知主题，不是邮件模板，HotCRM 也没有发给客户的欢迎邮件。有两种情况一条提醒都不会有——联系人**没有负责人**（种子数据或集成写入的记录就没有），以及联系人勾选了**拒绝邮件**。 ## 共享——谁能看到哪个联系人 @@ -99,5 +99,5 @@ CEO ## 给管理员的提示 - 部门列表（Sales、Marketing、Engineering、Finance、IT、Operations、HR、Legal、Executive、Other）可按选择列表值配置。参见 [Customization › Extending Objects](/zh-Hans/docs/customization/extending-objects)。 -- 欢迎邮件模板可以在你的邮件模板设置中自定义。 +- 新联系人提醒是一条流程，不是模板：要改措辞、通知渠道或通知给谁，编辑 `src/flows/contact-welcome.flow.ts`。它背后没有任何邮件模板设置。 - 来自客户的共享继承意味着你通常永远不需要针对特定客户的联系人共享规则。 diff --git a/content/docs/sales/contacts.zh-Hant.mdx b/content/docs/sales/contacts.zh-Hant.mdx index f02c37c76..8a6ce027e 100644 --- a/content/docs/sales/contacts.zh-Hant.mdx +++ b/content/docs/sales/contacts.zh-Hant.mdx @@ -13,12 +13,12 @@ description: 你向其銷售並為其提供服務的客戶處的人——決策 | 區塊 | 欄位 | | --- | --- | -| **身份** | 稱謂、名、姓、全名 | -| **客戶與角色** | 客戶、職位、部門、主要聯絡人標誌 | +| **身份** | 稱謂、名、姓、全名、頭像 | +| **客戶與角色** | 聯絡人負責人、所屬客戶、職位、部門、直屬上級 | | **聯絡資訊** | 郵箱、電話、手機 | -| **郵寄地址** | 完整的結構化地址 | -| **附加資訊** | 描述、生日、潛在客戶來源、匯報對象 | -| **溝通偏好** | 拒絕郵件、禁止致電 | +| **郵寄地址** | 郵寄地址、郵寄城市、郵寄省份、郵政編碼、郵寄國家（五個獨立欄位） | +| **附加資訊** | 生日、線索來源、描述、最近聯絡時間 | +| **溝通偏好** | 主要聯絡人、禁止致電、拒絕郵件 | ## 主要聯絡人 @@ -59,7 +59,7 @@ CEO ## 內建規則 - **郵箱地址在你所屬的組織內必須唯一**。同一個地址不能同時用於兩個聯絡人，即使這兩個聯絡人隸屬於不同的客戶——第二次儲存會被拒絕，並提示 *"Another contact … with email … already exists."*。同一平台上的其他組織可以有自己使用該地址的聯絡人——這條規則只作用於你自己的資料，而不是整個平台。郵箱在儲存與比較前會統一轉為小寫，因此 `Ada@Example.com` 與 `ada@example.com` 視為同一個地址。因此，若同一個人同時在兩家公司與你往來，兩筆聯絡人記錄需要各自使用不同的郵箱地址。 -- **歡迎郵件**——當建立一個聯絡人時，系統會自動向其發送 *contact_welcome* 郵件範本。 +- **新聯絡人提醒**——建立聯絡人時，系統會通知這筆記錄的**負責人**，站內收件匣和郵件各一份：*"… was added as a contact. Reach out to welcome them."*。聯絡人本人收不到任何東西：*contact_welcome* 是這條流程的名字和它的通知主題，不是郵件範本，HotCRM 也沒有發給客戶的歡迎郵件。有兩種情況一條提醒都不會有——聯絡人**沒有負責人**（種子資料或整合寫入的記錄就沒有），以及聯絡人勾選了**拒絕郵件**。 ## 共享——誰能看到哪個聯絡人 @@ -99,5 +99,5 @@ CEO ## 給管理員的提示 - 部門列表（Sales、Marketing、Engineering、Finance、IT、Operations、HR、Legal、Executive、Other）可按選擇列表值設定。參見 [Customization › Extending Objects](/zh-Hant/docs/customization/extending-objects)。 -- 歡迎郵件範本可以在你的郵件範本設定中自訂。 +- 新聯絡人提醒是一條流程，不是範本：要改措辭、通知管道或通知給誰，編輯 `src/flows/contact-welcome.flow.ts`。它背後沒有任何郵件範本設定。 - 來自客戶的共享繼承意味著你通常永遠不需要針對特定客戶的聯絡人共享規則。 diff --git a/content/docs/sales/leads.mdx b/content/docs/sales/leads.mdx index a5c0948c1..1b49cdf99 100644 --- a/content/docs/sales/leads.mdx +++ b/content/docs/sales/leads.mdx @@ -35,19 +35,20 @@ You can also **reopen** an unqualified lead back to *New* if circumstances chang ## What each lead record stores -The lead detail screen has 9 collapsible sections. Open only what you need: +A lead record declares its fields in **10 groups**. The lead's own record page curates its **Details** tab from a subset of them, so read this as the full inventory of what a lead carries rather than a screen-by-screen map: -| Section | What's in it | +| Group | What's in it | | --- | --- | -| **Identity** | Salutation, first/last name, full name | -| **Company Information** | Company name, job title, industry, annual revenue, employees, website | -| **Contact Information** | Email, phone, mobile | +| **Identity** | Salutation, first/last name, full name, display title | +| **Company Information** | Company, job title, industry — plus a hidden normalised copy of the company name, which is what conversion and duplicate checks match on | +| **Contact Information** | Email, phone, mobile, website | | **Qualification** | Status, Lead Score (a 1-5 star rating), lead source, next follow-up date, last contacted, disqualification reason | | **Assignment** | Owner | -| **Address** | Mailing address | -| **Additional Info** | Description, tags | -| **Communication Preferences** | Email opt-out, do-not-call | -| **Conversion** | Auto-filled after the lead is converted | +| **Address** | A single structured address field | +| **Additional Info** | Annual revenue, number of employees, description, notes | +| **Communication Preferences** | Do-not-call, email opt-out | +| **Conversion** | Converted flag, converted account, contact and opportunity, converted date — all auto-filled when the lead is converted | +| **Duplicate Management** | Duplicate Of (which object the surviving record lives on), Duplicate Of Lead, Duplicate Of Contact, Duplicate Status — the fields behind *Duplicate leads* below | The available **industries** include Technology, Software/SaaS, Finance, Healthcare, Retail, Manufacturing, Education, Real Estate, Media, Logistics, Hospitality, Energy, Government, Non-profit, and Other. diff --git a/content/docs/sales/leads.zh-Hans.mdx b/content/docs/sales/leads.zh-Hans.mdx index 58751e9b2..05cfb92f9 100644 --- a/content/docs/sales/leads.zh-Hans.mdx +++ b/content/docs/sales/leads.zh-Hans.mdx @@ -35,19 +35,20 @@ description: 在入站咨询成为真正交易之前对其进行捕获、评分 ## 每条线索记录存储的内容 -线索详情界面有 9 个可折叠区块。只展开你需要的： +线索记录把自己的字段声明为 **10 个区块**。线索自己的记录页只把其中一部分挑进**详情**标签页，所以下表是一条线索携带的字段全集，而不是逐屏对照表： | 区块 | 其中内容 | | --- | --- | -| **身份** | 称谓、名/姓、全名 | -| **公司信息** | 公司名称、职位、行业、年营收、员工人数、网站 | -| **联系信息** | 邮箱、电话、手机 | +| **身份** | 称谓、名/姓、全名、显示名称 | +| **公司信息** | 公司、职位、行业——另有一个隐藏的公司名称规范化副本，线索转换与重复检测按它匹配 | +| **联系信息** | 邮箱、电话、手机、网站 | | **资格审核** | 状态、线索评分（1-5 星评级）、线索来源、下次跟进日期、最近联系时间、未通过原因 | | **分配** | 负责人 | -| **地址** | 邮寄地址 | -| **附加信息** | 描述、标签 | -| **沟通偏好** | 邮件退订、请勿致电 | -| **转换** | 线索转换后自动填充 | +| **地址** | 一个结构化的地址字段 | +| **附加信息** | 年营收、员工人数、描述、备注 | +| **沟通偏好** | 禁止致电、拒收邮件 | +| **转换** | 已转化、转化客户、转化联系人、转化商机、转化日期——都在线索转化时自动写入 | +| **重复线索管理** | 重复于（存活的那条记录属于哪个对象）、重复的线索、重复的联系人、重复状态——下文*重复线索*用的就是这些字段 | 可选**行业**包括 Technology、Software/SaaS、Finance、Healthcare、Retail、Manufacturing、Education、Real Estate、Media、Logistics、Hospitality、Energy、Government、Non-profit 和 Other。 diff --git a/content/docs/sales/leads.zh-Hant.mdx b/content/docs/sales/leads.zh-Hant.mdx index 10c233d94..7017323f3 100644 --- a/content/docs/sales/leads.zh-Hant.mdx +++ b/content/docs/sales/leads.zh-Hant.mdx @@ -35,19 +35,20 @@ description: 在入站詢問成為真正交易之前對其進行擷取、評分 ## 每筆潛在客戶記錄儲存的內容 -潛在客戶詳情介面有 9 個可摺疊區塊。只展開你需要的： +潛在客戶記錄把自己的欄位宣告為 **10 個區塊**。潛在客戶自己的記錄頁只把其中一部分挑進**詳情**標籤頁，所以下表是一筆潛在客戶攜帶的欄位全集，而不是逐屏對照表： | 區塊 | 其中內容 | | --- | --- | -| **身份** | 稱謂、名/姓、全名 | -| **公司資訊** | 公司名稱、職位、產業、年營收、員工人數、網站 | -| **聯絡資訊** | 郵箱、電話、手機 | +| **身份** | 稱謂、名/姓、全名、顯示名稱 | +| **公司資訊** | 公司、職位、產業——另有一個隱藏的公司名稱正規化副本，潛在客戶轉換與重複檢測按它比對 | +| **聯絡資訊** | 郵箱、電話、手機、網站 | | **資格審核** | 狀態、線索評分（1-5 星評級）、線索來源、下次跟進日期、最近聯絡時間、未通過原因 | | **指派** | 負責人 | -| **地址** | 郵寄地址 | -| **附加資訊** | 描述、標籤 | -| **溝通偏好** | 郵件退訂、請勿致電 | -| **轉換** | 潛在客戶轉換後自動填充 | +| **地址** | 一個結構化的地址欄位 | +| **附加資訊** | 年營收、員工人數、描述、備註 | +| **溝通偏好** | 禁止致電、拒收郵件 | +| **轉換** | 已轉化、轉化客戶、轉化聯絡人、轉化商機、轉化日期——都在潛在客戶轉化時自動寫入 | +| **重複線索管理** | 重複於（存活的那筆記錄屬於哪個物件）、重複的線索、重複的聯絡人、重複狀態——下文*重複的潛在客戶*用的就是這些欄位 | 可選**產業**包括 Technology、Software/SaaS、Finance、Healthcare、Retail、Manufacturing、Education、Real Estate、Media、Logistics、Hospitality、Energy、Government、Non-profit 和 Other。