docs(sales): the opportunity header says what it holds

.changeset/opportunity-header-says-what-it-holds.md

@@ -0,0 +1,44 @@
+---
+'hotcrm': patch
+---
+
+The Opportunities page describes the opportunity detail layout the app actually
+ships: the header bullet is rewritten against the component, the highlights
+strip gets the line it never had, and the sales path stops being counted twice
+— in all three locales.
+
+The **Header** bullet promised "name, stage badge with the 7-stage path,
+amount, close date, owner", and was wrong in both directions at once. The
+`page:header` on `src/pages/opportunity_detail.page.ts` declares a title
+(`{name}`), a subtitle (`{crm_account}`), a breadcrumb and five action ids —
+`generate_quote`, `clone_opportunity`, `log_call`, `log_meeting` and
+`schedule_meeting`. So the stage badge is not on the header: the path is a
+separate `record:path`, which the same list already named on its own line as
+**Sales Path**, and that is how one component came to be counted twice. The
+amount, close date and owner are fields on the `record:highlights` strip — a
+component the page description never mentioned at all. Meanwhile the subtitle,
+the breadcrumb and all five buttons went unnamed, **Generate Quote** among
+them, which the page placed on the *Quote* related list rather than on the
+header where it actually sits.
+
+Each bullet in that list now describes one component. **Header** names what is
+on the header and, just as plainly, what is not. A new **Key Information**
+bullet names the strip's six fields — Amount, Close Date, Probability (%),
+Expected Revenue, Opportunity Owner, Account — and points out that the account
+is therefore on the screen twice. **Sales Path** describes the path once, and
+the *Quote* related list says where the Generate Quote button really is.
+
+Two claims went with the rewrite, for one reason. "Click any stage on the path
+to jump directly to it" and "one-click stage progression" both promise a
+control that does not exist: `RecordPathProps` declares `statusField`, `stages`
+and `aria` and nothing else, and the renderer shipped in `@objectstack/console`
+17.3.0 draws the strip as `role="list"` / `role="listitem"` spans with no
+`onClick`, no button and no link anywhere in the component. The path is a
+read-only indicator. A deal moves when its **Stage** field changes, under the
+transition rules this same page already documents.
+
+The Chinese faces are rewritten in their own register rather than translated
+back from the English, and take the zh-CN language-pack wording for the UI
+nouns they name. No `src/` metadata changed — the page is correct as authored,
+and this is the documentation catching up with it — and no gate or test was
+added.

content/docs/sales/opportunities.mdx

@@ -143,9 +143,10 @@ That third filter is what makes the name true: summing the **Amount** column giv
 
 When you open an opportunity, you'll see:
 
-- **Header** — name, stage badge with the 7-stage path, amount, close date, owner. Click any stage on the path to jump directly to it.
-- **Sales Path** — one-click stage progression.
-- **Quote** related list — with a **Generate Quote** button that runs the [Quote Generation flow](/docs/sales/quotes#generating-a-quote).
+- **Header** — the deal's **Opportunity Name** as the title, its **Account** as the subtitle, a breadcrumb, and five action buttons: **Generate Quote**, **Clone Opportunity**, **Log a Call**, **Log a Meeting** and **Schedule a Meeting**. What is *not* on it matters just as much: there is **no stage badge, no amount, no close date and no owner** on the header — those belong to the two components below it. **Generate Quote** is the CPQ entry point, and the header is where it actually sits.
+- **Key Information** — the highlights strip immediately under the header, and where this deal's numbers really are: **Amount**, **Close Date**, **Probability (%)**, **Expected Revenue**, **Opportunity Owner** and **Account**, side by side. The account therefore appears twice on the screen — once as the header subtitle, once here.
+- **Sales Path** — the stage strip below the highlights: all seven stages in funnel order, the current one marked and the ones already passed ticked. It is a **read-only indicator, not a control** — the stages are not clickable, so there is no one-click progression, and clicking a stage does not move the deal to it. You move a deal by editing its **Stage** field, on the *Details* tab or in the edit form, and the transition rules in *The 7 sales stages* above are what decide whether the move is allowed.
+- **Quote** related list — this deal's quotes, on the *Related* tab. The **Generate Quote** button that runs the [Quote Generation flow](/docs/sales/quotes#generating-a-quote) is not on this list: it is one of the header buttons above.
 - **Line Items** — with an **Add Product** button.
 - **Activity timeline** — a unified feed of comments, logged calls (`sys_activity`), outbound emails (`sys_email`), task completions, and field-history audit entries. Every tracked change on the opportunity (stage, amount, close-date, owner) shows up here automatically; there is no separate "history" tab.
 - **Competitors & Notes** — there is no such panel. The page (`src/pages/opportunity_detail.page.ts`) declares three regions: a header, the main column carrying the tab strip, and one narrow side column (`aside`) whose only occupant is the reference rail described below. Nothing on the page renders talking points, and there is no competitors field left to render either: the opportunity's **Competitors** multi-select offered three placeholder options (*Competitor A*, *Competitor B*, *Competitor C*), no screen in the app ever read the value back, and #1061 retired it. The only competitor signal the app records is the *Lost to Competitor* closed-lost reason, with the free-text **Loss Details** beside it. The closest thing to notes on the page itself is the *Details* tab's collapsible **Description** section, which carries **Description** and **Next Steps**.

content/docs/sales/opportunities.zh-Hans.mdx

@@ -143,9 +143,10 @@ description: 活跃的销售交易——销售管道的核心，包含 7 个阶
 
 当你打开一个商机时，会看到：
 
-- **头部**——名称、带 7 阶段路径的阶段徽章、金额、成交日期、负责人。点击路径上的任意阶段可直接跳转到它。
-- **销售路径**——一键阶段推进。
-- **报价**相关列表——带有一个**生成报价**按钮，可运行 [报价生成流程](/zh-Hans/docs/sales/quotes)。
+- **头部**——标题是这笔交易的**商机名称**，副标题是它的**所属客户**，此外还有面包屑和五个动作按钮：**生成报价单**、**克隆商机**、**记录通话**、**记录会议**、**安排会议**。它上面*没有*什么同样要紧：头部上**没有阶段徽章，也没有金额、成交日期和负责人**——那三样属于它下面的两个组件。**生成报价单**是 CPQ 的入口，而它真正待的地方就是头部。
+- **关键信息**——紧贴头部下方的摘要栏，也是这笔交易的数字真正待的地方：**金额**、**成交日期**、**成交概率 (%)**、**预期收入**、**商机负责人**、**所属客户**并排排列。所以客户在这个界面上出现了两次：一次是头部副标题，一次在这里。
+- **销售路径**——摘要栏下方的阶段条：七个阶段按漏斗顺序排开，当前阶段被标出，已经走过的打勾。它是一个**只读指示器，而不是控件**——阶段并不可点击，所以既没有「一键推进阶段」这回事，点某个阶段也不会把交易移到那个阶段去。推进一笔交易靠改它的**阶段**字段（在 *Details* 标签页里或编辑表单上），而这次移动允不允许，由上文《7 个销售阶段》里的转换规则决定。
+- **报价**相关列表——本商机的报价单，在 *Related* 标签页上。运行 [报价生成流程](/zh-Hans/docs/sales/quotes) 的那个**生成报价单**按钮并不在这个列表上：它是上面头部的五个按钮之一。
 - **行项目**——带有一个**添加产品**按钮。
 - **活动时间线**——统一汇集评论、已记录通话（`sys_activity`）、外发邮件（`sys_email`）、任务完成以及字段历史审计条目。商机上每个被跟踪的更改（阶段、金额、成交日期、负责人）都会自动出现在这里；没有单独的"历史"标签页。
 - **竞争对手与备注**——不存在这样一个面板。这一页（`src/pages/opportunity_detail.page.ts`）声明了三个区域：一个头部、一个装着那组标签页的主列，以及一条窄侧栏（`aside`），而侧栏里唯一的组件就是下一条讲的参考栏。页面上没有任何组件渲染「谈话要点」，也没有竞争对手字段可渲染了：商机上那个**竞争对手**多选字段只有三个占位选项（*Competitor A*、*Competitor B*、*Competitor C*），应用里没有任何界面把它读回来，#1061 已将其退役。应用里仅存的竞争对手信号，是「输给竞争对手」这条丢单原因，以及它旁边的自由文本 **丢单详情**。这一页上最接近「备注」的，是 *Details* 标签页里那个可折叠的 **描述** 分区，里面放着 **描述** 与 **下一步**。

content/docs/sales/opportunities.zh-Hant.mdx

@@ -143,9 +143,10 @@ description: 活躍的銷售交易——銷售管道的核心，包含 7 個階
 
 當你打開一個商機時，會看到：
 
-- **頭部**——名稱、帶 7 階段路徑的階段徽章、金額、成交日期、負責人。點擊路徑上的任意階段可直接跳轉到它。
-- **銷售路徑**——一鍵階段推進。
-- **報價**相關列表——帶有一個**生成報價**按鈕，可執行 [報價生成流程](/zh-Hant/docs/sales/quotes)。
+- **頭部**——標題是這筆交易的**商機名稱**，副標題是它的**所屬客戶**，此外還有麵包屑和五個動作按鈕：**生成報價單**、**克隆商機**、**記錄通話**、**記錄會議**、**安排會議**。它上面*沒有*什麼同樣要緊：頭部上**沒有階段徽章，也沒有金額、成交日期和負責人**——那三樣屬於它下面的兩個元件。**生成報價單**是 CPQ 的入口，而它真正待的地方就是頭部。
+- **關鍵資訊**——緊貼頭部下方的摘要欄，也是這筆交易的數字真正待的地方：**金額**、**成交日期**、**成交機率 (%)**、**預期收入**、**商機負責人**、**所屬客戶**並排排列。所以客戶在這個介面上出現了兩次：一次是頭部副標題，一次在這裡。
+- **銷售路徑**——摘要欄下方的階段條：七個階段按漏斗順序排開，當前階段被標出，已經走過的打勾。它是一個**唯讀指示器，而不是控制項**——階段並不可點擊，所以既沒有「一鍵推進階段」這回事，點某個階段也不會把交易移到那個階段去。推進一筆交易靠改它的**階段**欄位（在 *Details* 標籤頁裡或編輯表單上），而這次移動允不允許，由上文《7 個銷售階段》裡的轉換規則決定。
+- **報價**相關列表——本商機的報價單，在 *Related* 標籤頁上。執行 [報價生成流程](/zh-Hant/docs/sales/quotes) 的那個**生成報價單**按鈕並不在這個列表上：它是上面頭部的五個按鈕之一。
 - **行項目**——帶有一個**新增產品**按鈕。
 - **活動時間線**——統一彙集評論、已記錄通話（`sys_activity`）、外發郵件（`sys_email`）、任務完成以及欄位歷史稽核條目。商機上每個被追蹤的更改（階段、金額、成交日期、負責人）都會自動出現在這裡；沒有單獨的「歷史」標籤頁。
 - **競爭對手與備註**——不存在這樣一個面板。這一頁（`src/pages/opportunity_detail.page.ts`）宣告了三個區域：一個頭部、一個裝著那組標籤頁的主欄，以及一條窄側欄（`aside`），而側欄裡唯一的元件就是下一條講的參考欄。頁面上沒有任何元件渲染「談話要點」，也沒有競爭對手欄位可渲染了：商機上那個**競爭對手**多選欄位只有三個佔位選項（*Competitor A*、*Competitor B*、*Competitor C*），應用裡沒有任何介面把它讀回來，#1061 已將其退役。應用裡僅存的競爭對手訊號，是「輸給競爭對手」這條丟單原因，以及它旁邊的自由文字 **丟單詳情**。這一頁上最接近「備註」的，是 *Details* 標籤頁裡那個可摺疊的 **描述** 分區，裡面放著 **描述** 與 **下一步**。