docs(service): 把工单字段的三套分组与 Details 页签写实 (#958)

.changeset/cases-record-sections-and-details-tab.md

@@ -0,0 +1,28 @@
+---
+"hotcrm": patch
+---
+
+Service docs: *What a case record stores* now separates the three things that organise a case's fields, and the *Details* tab stops promising all of them.
+
+`content/docs/service/cases` opened its field section with "the detail screen is organised into
+6 sections" and a six-row table. No screen in this app has those six sections. The six **names**
+are real — they are `crm_case`'s `fieldGroups` (`src/objects/case.object.ts`), the object's own
+filing scheme for its fields — but the detail screen and the form each declare sections of their
+own and render three apiece: *Case Information* / *Status & SLA* / *Description* on the **Details**
+tab (`src/pages/case_detail.page.ts`), and *Case* / *SLA* / *Resolution* on the tabbed form
+(`src/views/case.view.ts`). The section now keeps all six names, says what they actually are, and
+gives the three layouts as three tables instead of one merged fiction.
+
+Five of the six field-group rows were also wrong on their own terms: **Parent Case** is in *Case
+Information*, not *Origin & Routing*; **Status** and **Case Type** are in *Case Information*, not
+*SLA & Priority*; **Closed Date** is in *SLA & Priority*, not *Resolution*; and *System* holds
+**Internal Notes** and **Is Closed** — there is no *audit trail* field on a case at all. Only
+*Escalation* was accurate. **Priority Rank** belongs to no group, which the table now says.
+
+The **Details** tab bullet said it carries "all metadata fields". It carries **16** of `crm_case`'s
+**28**. The twelve it does not carry are named, including **First Response Date** — the field the
+*What happens automatically* section above explains at length, which a reader following "all
+metadata fields" would go to this tab to find and not find. Nine of the twelve are on the form
+instead; **Escalated Date**, **Priority Rank** and **Display Title** are on no case screen.
+
+English, Simplified Chinese and Traditional Chinese. Documentation only — no metadata changed.

content/docs/service/cases.mdx

@@ -52,16 +52,46 @@ This drives reporting (which channels generate the most volume) and is auto-fill
 
 ## What a case record stores
 
-The detail screen is organised into 6 sections:
+`crm_case` declares **28 fields** (`src/objects/case.object.ts`), and three different things organise them: the object's own field groups, the case detail screen, and the case form. Only the first of the three has six sections, and no two of them agree — so it is worth knowing which one you are being shown.
+
+### The object's field groups
+
+The six names below are real, but not one of them is a screen: they are `crm_case`'s **field groups** (`fieldGroups`), the object's own filing scheme for its fields. Neither the detail screen nor the form renders them — each declares sections of its own, listed below. This is, though, the one list that accounts for every field the object has:
+
+| Field group | Fields |
+| --- | --- |
+| **Case Information** | Case Number, Subject, Display Title, Description, Account, Contact, Status, Case Type, Parent Case |
+| **Origin & Routing** | Case Owner, Case Origin |
+| **SLA & Priority** | Priority, Created Date, Closed Date, First Response Date, Resolution Time (Hours), SLA Due Date, SLA Violated |
+| **Resolution** | Resolution, Customer Satisfaction, Customer Feedback, Customer Signature |
+| **Escalation** *(collapsed by default)* | Escalated, Escalated Date, Escalation Reason |
+| **System** *(collapsed by default)* | Internal Notes, Is Closed |
+
+Five of those six rows used to be written differently on this page, and the differences were not cosmetic: **Parent Case** is in *Case Information*, not *Origin & Routing*; **Status** and **Case Type** are in *Case Information*, not *SLA & Priority*; **Closed Date** is in *SLA & Priority*, not *Resolution*; and *System* holds **Internal Notes** and **Is Closed** — there is no *audit trail* field on a case at all, and the timestamps sit in *SLA & Priority*. Only *Escalation* was right as it stood. **Priority Rank**, the hidden sort key that orders *My Open Cases*, is in no group at all.
+
+### The detail screen
+
+The **Details** tab of the case detail page (`src/pages/case_detail.page.ts`) declares **three** sections, holding **16** of the 28 fields:
 
 | Section | Fields |
 | --- | --- |
-| **Case Information** | Case number, subject, description, account, contact |
-| **Origin & Routing** | Origin, owner, parent case |
-| **SLA & Priority** | Status, priority, type, first response time, SLA due date, SLA Violated |
-| **Resolution** | Closed date, resolution, customer signature |
-| **Escalation** *(collapsed by default)* | Escalation flag, escalated date, escalation reason |
-| **System** *(collapsed by default)* | Audit trail, timestamps |
+| **Case Information** | Case Number, Subject, Account, Contact, Case Type, Case Origin |
+| **Status & SLA** | Status, Priority, Case Owner, Escalated, Escalation Reason, SLA Due Date, SLA Violated, Resolution Time (Hours) |
+| **Description** *(collapsible)* | Description, Resolution |
+
+*Description* is the only one of the three that can be collapsed, and nothing marks it collapsed to begin with, so it opens along with the rest.
+
+### The form
+
+The case form (`src/views/case.view.ts`) is tabbed, and has three sections of its own — different names, different contents, 24 of the 28 fields:
+
+| Form tab | Fields |
+| --- | --- |
+| **Case** | Case Number, Subject, Account, Contact, Status, Priority, Case Origin, Case Owner, Description |
+| **SLA** | Created Date, First Response Date, SLA Due Date, Resolution Time (Hours), SLA Violated, Escalated, Escalation Reason, Parent Case |
+| **Resolution** | Resolution, Internal Notes, Customer Satisfaction, Customer Feedback, Customer Signature, Closed Date, Is Closed |
+
+The two are not one screen wearing different chrome. **Parent Case** is on the form and nowhere else — the detail screen carries it in no section — while **Case Type** is the other way round. The public support form at `/forms/support` is a third layout again: a single section with four fields (subject, description, type, priority).
 
 ## What happens automatically
 
@@ -144,7 +174,7 @@ When you open a case, you'll see:
 - **Status path** — a Salesforce-style horizontal flow showing New → In Progress → Waiting on Customer → Escalated → Resolved → Closed, so an agent can see at a glance where the case stands and what the next stop is.
 - **Customer panel** — there is no such panel. The page (`src/pages/case_detail.page.ts`) declares two regions and nothing else: a header holding the three components above, and a main region holding the tab strip below. What customer context there is sits in those: the **account** appears three times over — the header subtitle, the Key Information strip, and a field in the *Details* tab — and the **primary contact** is a field in that same tab's *Case Information* section. **Contract tier** and **open cases this month** are on no case surface at all. A case links to no contract, and `crm_contract` carries no tier field either; the nearest real field is **Customer Tier** on the account record, which this page does not show. Nothing in this app counts a customer's cases by month.
 - **Three tabs:**
-  - **Details** — full case description and resolution, all metadata fields.
+  - **Details** — the case description and resolution in full, but not "all metadata fields": **16** of the object's **28**, in the three sections listed under *What a case record stores* above. The twelve that are not on the tab are **First Response Date**, **Created Date**, **Closed Date**, **Escalated Date**, **Is Closed**, **Parent Case**, **Customer Satisfaction**, **Customer Feedback**, **Customer Signature**, **Internal Notes**, **Priority Rank** and **Display Title**. Nine of them are on the case form instead; the remaining three are on no case screen at all — **Escalated Date** is written by the escalation flows and displayed nowhere, **Priority Rank** is the sort key behind *My Open Cases*, and **Display Title** is the object's `nameField`, the title formula that names a case wherever one is referenced rather than a field you read here. **First Response Date** is the omission worth knowing about: *What happens automatically* above explains at length how it gets stamped, and this is not the tab you can read it on.
   - **Related** — one list, not four: **Open Tasks** — the `crm_task` records pointing at this case through **Related Case** (`related_to_case`), filtered to those whose status is not *Completed*, ten at a time. That is the whole tab. There is no attachments list: files can be attached to a case (the object enables them), but no component on this page lists them. There is no linked-opportunity list, because `crm_case` has no opportunity relationship in either direction. And there is no milestone list — the case's three milestones, *escalated*, *resolved* and *closed*, are emitted as entries in the **Activity** timeline, not as records here.
   - **Activity** — a unified timeline (more on this below).
 - **AI Reference Rail** — there is no rail on this page, of any kind. The main region holds the tab strip and nothing else, and not one component on the page is AI-driven. The service skills are real — see *How the AI assistant helps* below — but you reach them by asking, not from a panel beside the case. The one reference rail this app does render sits on the opportunity detail page, and even there it lists related records (quotes, products, open tasks) rather than suggestions.

content/docs/service/cases.zh-Hans.mdx

@@ -52,16 +52,46 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 
 ## 工单记录存储的内容
 
-详情界面分为 6 个区块：
+`crm_case` 一共声明 **28 个字段**（`src/objects/case.object.ts`），而把它们组织起来的东西有三样：对象自己的字段分组、工单详情界面、工单表单。三者里只有第一样是六个分区，而且两两都不一致——所以要紧的是分清你看的是哪一样。
 
-| 区块 | 字段 |
+### 对象自己的字段分组
+
+下面这六个名字都是真的，但没有一个是界面：它们是 `crm_case` 的**字段分组**（`fieldGroups`），是对象给自己字段定的归档方案。详情界面和表单都不渲染它们——两者各自声明了自己的分区，见下文。不过，这确实是唯一一份把对象全部字段都交代到的清单：
+
+| 字段分组 | 字段 |
 | --- | --- |
-| **Case Information** | 工单编号、主题、描述、账户、联系人 |
-| **Origin & Routing** | 来源、所有者、父工单 |
-| **SLA & Priority** | 状态、优先级、类型、首次响应时间、SLA 截止日期、SLA Violated |
-| **Resolution** | 关闭日期、解决方案、客户签名 |
+| **Case Information** | 工单编号、主题、显示名称、描述、账户、联系人、状态、类型、父工单 |
+| **Origin & Routing** | 负责人、来源 |
+| **SLA & Priority** | 优先级、创建日期、关闭日期、首次响应日期、解决时间（小时）、SLA 截止日期、SLA Violated |
+| **Resolution** | 解决方案、客户满意度、客户反馈、客户签名 |
 | **Escalation** *(默认折叠)* | 升级标记、升级日期、升级原因 |
-| **System** *(默认折叠)* | 审计跟踪、时间戳 |
+| **System** *(默认折叠)* | 内部备注、关闭标记 |
+
+这六行里有五行，本页原先写的是另一个样子，而且差的不是细枝末节：**父工单**在 *Case Information* 里，不在 *Origin & Routing*；**状态**与**类型**也在 *Case Information* 里，不在 *SLA & Priority*；**关闭日期**在 *SLA & Priority* 里，不在 *Resolution*；*System* 装的是**内部备注**与**关闭标记**——工单上根本没有名为「审计跟踪」的字段，时间戳则待在 *SLA & Priority* 里。六行里只有 *Escalation* 原样就是对的。**优先级排序**——把 *My Open Cases* 排出先后的那个隐藏排序键——则不属于任何一个分组。
+
+### 详情界面
+
+工单详情页（`src/pages/case_detail.page.ts`）的 **Details** 页签声明了**三个**分区，装着 28 个字段中的 **16** 个：
+
+| 分区 | 字段 |
+| --- | --- |
+| **Case Information** | 工单编号、主题、账户、联系人、类型、来源 |
+| **Status & SLA** | 状态、优先级、负责人、升级标记、升级原因、SLA 截止日期、SLA Violated、解决时间（小时） |
+| **Description** *(可折叠)* | 描述、解决方案 |
+
+三个分区里只有 *Description* 是可折叠的，而且没有任何地方把它标成折叠态，所以它和其余两个一样是展开着的。
+
+### 表单
+
+工单表单（`src/views/case.view.ts`）是分页签的，自己另有三个分区——名字不同、内容也不同，覆盖 28 个字段中的 24 个：
+
+| 表单页签 | 字段 |
+| --- | --- |
+| **Case** | 工单编号、主题、账户、联系人、状态、优先级、来源、负责人、描述 |
+| **SLA** | 创建日期、首次响应日期、SLA 截止日期、解决时间（小时）、SLA Violated、升级标记、升级原因、父工单 |
+| **Resolution** | 解决方案、内部备注、客户满意度、客户反馈、客户签名、关闭日期、关闭标记 |
+
+这两者并不是同一个界面换了层皮。**父工单**只在表单上有——详情界面的任何一个分区里都没有它——**类型**则正好反过来。`/forms/support` 上那张公开支持表单又是第三种排布：一个分区、四个字段（主题、描述、类型、优先级）。
 
 ## 自动发生的事
 
@@ -144,7 +174,7 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 - **状态路径**——一个 Salesforce 风格的水平流程，显示 New → In Progress → Waiting on Customer → Escalated → Resolved → Closed，让客服一眼就能看出工单的进展和下一站。
 - **客户面板**——不存在这样一个面板。这一页（`src/pages/case_detail.page.ts`）只声明了两个区域，再无其他：一个页眉区域装着上面那三个组件，一个主区域装着下面那组页签。客户上下文就散落在这两处：**账户**在页面上出现了三次——页眉副标题、关键信息摘要栏，以及 *Details* 页签里的一个字段；**主要联系人**则是同一页签 *Case Information* 分区里的一个字段。**合同等级**与**本月未结工单**在工单的任何界面上都没有承载：工单不关联任何合同，`crm_contract` 上也没有等级字段；最接近的真实字段是账户记录上的 **Customer Tier**（中文界面作「客户分层」），而这一页并不展示它。本应用里也没有任何东西按月统计一个客户的工单数。
 - **三个标签页：**
-  - **Details**——完整的工单描述和解决方案、所有元数据字段。
+  - **Details**——完整的工单描述和解决方案是有的，但不是「所有元数据字段」：是对象 **28** 个字段里的 **16** 个，分在上文《工单记录存储的内容》列出的那三个分区里。不在这个页签上的十二个是：**首次响应日期**、**创建日期**、**关闭日期**、**升级日期**、**关闭标记**、**父工单**、**客户满意度**、**客户反馈**、**客户签名**、**内部备注**、**优先级排序**、**显示名称**。其中九个在工单表单上；剩下三个在工单的任何界面上都没有——**升级日期**由升级流程写入，但哪里都不展示，**优先级排序**是 *My Open Cases* 背后的排序键，**显示名称**是对象的 `nameField`，一个在任何地方引用工单时给它命名的标题公式，而不是你在这里能读到的字段。这里面最该知道的缺席者是**首次响应日期**：上文《自动发生的事》整整一段讲清了它是怎么打戳的，而你读不到它的地方正是这个页签。
   - **Related**——只有一个列表，不是四个：**Open Tasks**——通过**关联工单**（`related_to_case`）指向本工单的 `crm_task` 记录，过滤掉状态为 *Completed* 的，一次最多十条。整个页签就这些。没有附件列表：工单是可以挂附件的（对象上开了这项能力），但这一页没有任何组件把它们列出来。没有关联商机列表，因为 `crm_case` 与商机之间双向都不存在任何关系字段。也没有里程碑列表——工单的三个里程碑（*escalated*、*resolved*、*closed*）是以条目形式发到 **Activity** 时间线上的，不是在这里当记录列出来。
   - **Activity**——统一的时间线（下文详述）。
 - **AI 参考栏**——这一页上不存在任何形式的参考栏。主区域里除了那组页签什么都没有，页面上也没有任何一个组件是 AI 驱动的。服务技能本身是真实存在的——见下文《AI Copilot 如何提供帮助》一节——但你是靠提问去用它们，而不是靠工单旁边的一块面板。本应用里唯一真正渲染出来的参考栏在商机详情页上，而且即便在那里，它列的也是关联记录（报价、产品、未完成任务），不是什么建议。