docs(service): 把工单页眉与首次响应打戳两行写实到源码 (#941)

.changeset/cases-detail-header-and-first-response.md

@@ -0,0 +1,27 @@
+---
+"hotcrm": patch
+---
+
+Service docs: the case detail header bullet and the first-response stamp now match the app.
+
+`content/docs/service/cases` described the case detail header as carrying a status badge, a
+priority badge and an **SLA countdown**. None of the three is there. The header renders the
+case number and subject as its title, the account as its subtitle, an icon, a breadcrumb and
+the action buttons — and nothing in this app computes time remaining or time over, so there is
+no countdown to render anywhere on the case. **Status** and **Priority** are ordinary fields in
+the **Key Information** highlights strip below the header, alongside SLA Due Date, SLA
+Violated, Owner and Account; that strip is now a bullet of its own instead of being folded into
+the header. This also settles a straight contradiction with `content/docs/service/sla-and-escalation`,
+which already said there is no countdown and that the header carries the case number, subject
+and account only.
+
+The same page said **first response time** was "stamped the first time an agent comments or
+replies". Neither action stamps it. `first_response_date` has exactly one writer,
+`logActivityAction`, and it stamps when a call or meeting that **already took place** is logged
+on the case (**Log a Call** / **Log a Meeting**), only while the field is still empty. A
+comment, an outbound email, a status change and a meeting that is merely *scheduled* all leave
+it untouched — so a case worked entirely through comments and email keeps an empty field.
+
+The **Status path** bullet beside the header one was re-checked against the page metadata and
+is accurate, so it stays as written. English, Simplified Chinese and Traditional Chinese.
+Documentation only — no metadata changed.

content/docs/service/cases.mdx

@@ -65,7 +65,7 @@ The detail screen is organised into 6 sections:
 
 ## What happens automatically
 
-- **First response time** — stamped the first time an agent comments or replies.
+- **First response date** (`first_response_date`) — stamped the first time a call or meeting that **already took place** is logged on the case. Its only writer is `logActivityAction` (`src/actions/global.actions.ts`), which stamps on the `held` activity kinds — **Log a Call** and **Log a Meeting** — and reads the stored value back before writing, so a second log never overwrites the first. Nothing else stamps it: a comment goes to the feed, an email goes to `sys_email`, a status change is deliberately not counted (an agent can move a case to *In Progress* and investigate for an hour while the customer hears nothing), and a meeting merely *scheduled* is not a response either. On a case worked entirely through comments and email the field stays empty.
 - **Closed flag** — set automatically when status changes to *Closed*.
 - **Closed date** — stamped to NOW when status changes to *Closed*.
 - **Resolution time (hours)** — calculated as the difference between *Created date* and *Closed date*.
@@ -139,7 +139,8 @@ Six names this section used to list are not views at all:
 
 When you open a case, you'll see:
 
-- **Header** — case number, subject, status badge, priority badge, SLA countdown.
+- **Header** — the case number and subject as the title (`{case_number} · {subject}`), the **account** as the subtitle, plus an icon, a breadcrumb and the action buttons. That is the whole header: there is **no status badge, no priority badge and no SLA countdown** on it. Nothing in this app computes time remaining or time over — not here, not anywhere else on the case — so there is no countdown to render. See [SLA & Escalation](/docs/service/sla-and-escalation) for what the two SLA fields do instead.
+- **Key Information** — the highlights strip directly under the header, and where **Status** and **Priority** actually live: ordinary fields rather than badges, side by side with **SLA Due Date**, **SLA Violated**, **Owner** and **Account**.
 - **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** — account, primary contact, contract tier, open cases this month.
 - **Three tabs:**

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

@@ -65,7 +65,7 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 
 ## 自动发生的事
 
-- **首次响应时间**——客服第一次评论或回复时标记。
+- **首次响应日期**（`first_response_date`）——在工单上记录一次**已经发生过**的通话或会议时才打戳，而且只打第一次。它唯一的写入方是 `logActivityAction`（`src/actions/global.actions.ts`），只在 `held` 这两种活动上打戳——**Log a Call** 与 **Log a Meeting**——并且写之前先把库里存着的值读回来，所以第二次记录不会覆盖第一次。别的动作都不打这个戳：评论进的是动态流，邮件进的是 `sys_email`，状态变更是被刻意排除的（客服可以把工单转到 *In Progress* 然后自己查一小时，客户什么都没听到），仅仅**预约**了一场会议也不算响应。所以一张全程靠评论和邮件处理的工单，这个字段始终是空的。
 - **关闭标记**——状态变为 *Closed* 时自动设置。
 - **关闭日期**——状态变为 *Closed* 时标记为 NOW。
 - **解决时间（小时）**——按 *Created date* 与 *Closed date* 之间的差值计算。
@@ -139,7 +139,8 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 
 打开一个工单时，你会看到：
 
-- **页眉**——工单编号、主题、状态徽章、优先级徽章、SLA 倒计时。
+- **页眉**——标题是工单编号与主题（`{case_number} · {subject}`），副标题是**账户**，此外只有一个图标、面包屑和几个动作按钮。页眉就这些：上面**没有状态徽章、没有优先级徽章，也没有 SLA 倒计时**。本应用里没有任何东西会计算剩余时间或超时时长——页眉上没有，工单上别的任何地方也没有——所以根本没有倒计时可渲染。那两个 SLA 字段实际做什么，见 [SLA 与升级](/zh-Hans/docs/service/sla-and-escalation)。
+- **关键信息**——紧贴页眉下方的摘要栏，也是**状态**与**优先级**真正待的地方：它们在这里是普通字段而不是徽章，与 **SLA 截止日期**、**SLA Violated**、**负责人**、**账户**并排。
 - **状态路径**——一个 Salesforce 风格的水平流程，显示 New → In Progress → Waiting on Customer → Escalated → Resolved → Closed，让客服一眼就能看出工单的进展和下一站。
 - **客户面板**——账户、主要联系人、合同等级、本月未结工单。
 - **三个标签页：**

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

@@ -65,7 +65,7 @@ description: 客戶支援工單——主題、優先順序、狀態、解決方
 
 ## 自動發生的事
 
-- **首次回應時間**——客服第一次評論或回覆時標記。
+- **首次回應日期**（`first_response_date`）——在工單上記錄一次**已經發生過**的通話或會議時才打戳，而且只打第一次。它唯一的寫入方是 `logActivityAction`（`src/actions/global.actions.ts`），只在 `held` 這兩種活動上打戳——**Log a Call** 與 **Log a Meeting**——並且寫之前先把庫裡存著的值讀回來，所以第二次記錄不會覆蓋第一次。別的動作都不打這個戳：評論進的是動態流，郵件進的是 `sys_email`，狀態變更是被刻意排除的（客服可以把工單轉到 *In Progress* 然後自己查一小時，客戶什麼都沒聽到），僅僅**預約**了一場會議也不算回應。所以一張全程靠評論和郵件處理的工單，這個欄位始終是空的。
 - **關閉標記**——狀態變為 *Closed* 時自動設定。
 - **關閉日期**——狀態變為 *Closed* 時標記為 NOW。
 - **解決時間（小時）**——按 *Created date* 與 *Closed date* 之間的差值計算。
@@ -139,7 +139,8 @@ description: 客戶支援工單——主題、優先順序、狀態、解決方
 
 打開一個工單時，你會看到：
 
-- **頁首**——工單編號、主題、狀態徽章、優先順序徽章、SLA 倒數計時。
+- **頁首**——標題是工單編號與主題（`{case_number} · {subject}`），副標題是**帳戶**，此外只有一個圖示、麵包屑和幾個動作按鈕。頁首就這些：上面**沒有狀態徽章、沒有優先順序徽章，也沒有 SLA 倒數計時**。本應用裡沒有任何東西會計算剩餘時間或超時時長——頁首上沒有，工單上別的任何地方也沒有——所以根本沒有倒數計時可渲染。那兩個 SLA 欄位實際做什麼，見 [SLA 與升級](/zh-Hant/docs/service/sla-and-escalation)。
+- **關鍵資訊**——緊貼頁首下方的摘要欄，也是**狀態**與**優先順序**真正待的地方：它們在這裡是普通欄位而不是徽章，與 **SLA 截止日期**、**SLA Violated**、**負責人**、**帳戶**並排。
 - **狀態路徑**——一個 Salesforce 風格的水平流程，顯示 New → In Progress → Waiting on Customer → Escalated → Resolved → Closed，讓客服一眼就能看出工單的進展和下一站。
 - **客戶面板**——帳戶、主要聯絡人、合約等級、本月未結工單。
 - **三個標籤頁：**