feat(scripts): object-aware field consumer ledger, and the product docs it corrects (#1193, #1194)

.changeset/object-aware-field-consumer-scan.md

@@ -0,0 +1,23 @@
+---
+"hotcrm": patch
+---
+
+Product docs: the *Standard list views* section now describes the two views the
+catalog actually ships — **All Products** (the grid, grouped by category) and
+**Product Catalog** (the gallery) — in all three locales. It previously named
+*Active Products*, *By Category* and *By Family*, none of which exists; the
+category grouping is a setting on the grid, not a saved view, and nothing groups
+by family. The same section on the campaigns page named six views that do not
+exist and is corrected the same way, and the cases page's roster gained the
+*Unassigned — triage* view it had been omitting while claiming to list them all.
+
+The products page also stops promising that tax is applied. *Default Tax Rate %*
+is stored on the product and read by nothing: tax on a quote is an amount you
+enter on the quote itself, and a quote line item carries its own per-line rate.
+The sales-rep tip that said "pricing and tax are auto-filled" now says what is
+actually filled in — the list price, and the sales price on a new line.
+
+For maintainers: `pnpm scan:fields` prints an object-aware ledger of which
+declared field is read by what. The sweep it replaces matched field names across
+the whole source tree, so a field whose name is also used on another object read
+as consumed whatever it did — `crm_product.tax_rate` was invisible that way.

content/docs/marketing/campaigns.mdx

@@ -94,12 +94,16 @@ For deals influenced by multiple campaigns (multi-touch), the convention is to r
 
 ## Standard list views
 
-- **Active Campaigns** — status = *In Progress*.
-- **Upcoming Campaigns** — start date in the future, status = *Planning*.
-- **Completed This Quarter** — status = *Completed* AND end date in current quarter.
-- **Over Budget** — actual cost > budgeted cost.
-- **By Type** — grouped.
-- **Best ROI** — sorted by ROI descending.
+Campaigns saves **four** views (`src/views/campaign.view.ts`), and the tab row above the list changes how the same campaigns are *drawn*, not which campaigns are in them:
+
+| View | What it shows | Tab |
+| --- | --- | --- |
+| **All Campaigns** | The grid: name (pinned left, and the link into the record), channel, status, start and end date, budgeted cost and expected revenue — the last two with column totals. Ordered by **Start Date**, earliest first. 25 rows a page. | *All* |
+| **Campaign Schedule** | One gantt bar per campaign, from start date to end date, titled by name, so overlapping runs line up against one another. | *Schedule* |
+| **Launch Calendar** | The same campaigns on a month calendar, placed on their **Start Date** and coloured by channel. | *Launches* |
+| **Marketing Timeline** | The same start-to-end spans on a month scale, grouped by channel and coloured by status. | *Timeline* |
+
+None of the four filters anything, so **every campaign you can see appears in all four** and switching tabs only redraws them. There is no saved *Active Campaigns*, *Upcoming Campaigns*, *Completed This Quarter*, *Over Budget*, *By Type* or *Best ROI*: to narrow the list to one status, sort and filter the grid columns yourself. **ROI** is not among those columns — it is on the campaign record, under *Costs*, and in the marketing dashboards.
 
 ## Sharing — campaigns are public by default
 

content/docs/marketing/campaigns.zh-Hans.mdx

@@ -94,12 +94,16 @@ description: 规划、启动并衡量市场营销举措——电子邮件、网
 
 ## 标准列表视图
 
-- **Active Campaigns** — 状态 = *In Progress*。
-- **Upcoming Campaigns** — 开始日期在未来，状态 = *Planning*。
-- **Completed This Quarter** — 状态 = *Completed* 且结束日期在本季度。
-- **Over Budget** — 实际成本 > 预算成本。
-- **By Type** — 已分组。
-- **Best ROI** — 按 ROI 降序排列。
+营销活动一共保存了**四个**视图（`src/views/campaign.view.ts`），列表上方的标签行改的是同一批营销活动**怎么画**，而不是里面有哪些营销活动：
+
+| 视图 | 它展示什么 | 标签 |
+| --- | --- | --- |
+| **All Campaigns** | 表格：名称（固定在左侧，也是进入记录的链接）、渠道、状态、开始与结束日期、预算成本和预期营收——后两列带列合计。按**开始日期**升序排列，每页 25 行。 | *All* |
+| **Campaign Schedule** | 每个营销活动一根甘特条，从开始日期到结束日期，以名称为标题，让相互重叠的档期对齐排布。 | *Schedule* |
+| **Launch Calendar** | 同一批营销活动排在月历上，落在各自的**开始日期**，按渠道着色。 | *Launches* |
+| **Marketing Timeline** | 同样的起止跨度画在月度刻度上，按渠道分组、按状态着色。 | *Timeline* |
+
+四个视图都没有任何过滤条件，所以**你能看到的每个营销活动在四个标签里都在**，切换标签只是换一种画法。不存在名为 *Active Campaigns*、*Upcoming Campaigns*、*Completed This Quarter*、*Over Budget*、*By Type* 或 *Best ROI* 的已保存视图：要把列表收窄到某个状态，请自己对表格的列排序和过滤。**ROI** 并不在这些列里——它在营销活动记录的*成本*区块上，以及市场仪表盘里。
 
 ## 共享——营销活动默认公开
 

content/docs/marketing/campaigns.zh-Hant.mdx

@@ -94,12 +94,16 @@ description: 規劃、啟動並衡量行銷舉措——電子郵件、網路研
 
 ## 標準清單檢視
 
-- **Active Campaigns** — 狀態 = *In Progress*。
-- **Upcoming Campaigns** — 開始日期在未來，狀態 = *Planning*。
-- **Completed This Quarter** — 狀態 = *Completed* 且結束日期在本季。
-- **Over Budget** — 實際成本 > 預算成本。
-- **By Type** — 已分組。
-- **Best ROI** — 按 ROI 降序排列。
+行銷活動一共儲存了**四個**檢視（`src/views/campaign.view.ts`），列表上方的標籤行改的是同一批行銷活動**怎麼畫**，而不是裡面有哪些行銷活動：
+
+| 檢視 | 它展示什麼 | 標籤 |
+| --- | --- | --- |
+| **All Campaigns** | 表格：名稱（釘在左側，也是進入記錄的連結）、通路、狀態、開始與結束日期、預算成本和預期營收——後兩欄帶欄位合計。按**開始日期**升序排列，每頁 25 列。 | *All* |
+| **Campaign Schedule** | 每個行銷活動一根甘特條，從開始日期到結束日期，以名稱為標題，讓相互重疊的檔期對齊排布。 | *Schedule* |
+| **Launch Calendar** | 同一批行銷活動排在月曆上，落在各自的**開始日期**，按通路著色。 | *Launches* |
+| **Marketing Timeline** | 同樣的起訖跨度畫在月度刻度上，按通路分組、按狀態著色。 | *Timeline* |
+
+四個檢視都沒有任何過濾條件，所以**你能看到的每個行銷活動在四個標籤裡都在**，切換標籤只是換一種畫法。不存在名為 *Active Campaigns*、*Upcoming Campaigns*、*Completed This Quarter*、*Over Budget*、*By Type* 或 *Best ROI* 的已儲存檢視：要把列表收窄到某個狀態，請自己對表格的欄位排序和過濾。**ROI** 並不在這些欄位裡——它在行銷活動記錄的*成本*區塊上，以及行銷儀表板裡。
 
 ## 共享——行銷活動預設公開
 

content/docs/revenue/products.mdx

@@ -44,10 +44,12 @@ Categories and families let you slice reports by product mix — *"how much SMB-
 | --- | --- |
 | **List Price** | Standard published price — what shows up on a quote by default |
 | **Cost** | Your cost — used for margin calculation |
-| **Default Tax Rate %** | The rate carried on the product record |
+| **Default Tax Rate %** | Stored on the product. Nothing applies it — see below |
 
 The system warns you if Cost is greater than List Price (which would be a losing sale).
 
+**Tax is a quote-level figure, and the product rate is not applied anywhere.** The price fill that copies a product's List Price onto a quote or opportunity line item does not copy the rate, and a quote's total is *subtotal − discount + Tax + Shipping*, where **Tax** is an amount you type on the quote itself. A quote line item has its own **Tax Rate %**, defaulted to 0 and set per line. So setting *Default Tax Rate %* on a product changes no total anywhere today.
+
 ## No inventory, no billing schedule
 
 A product record is a catalog entry and nothing more. HotCRM holds **no stock figure** — no quantity on hand, no reorder point, and nothing decrements on a closed deal — and **no billing schedule or unit of measure**: how a subscription is billed lives in the contract and the quote, not on the catalog row. Those fields used to be declared here and were read by nothing, which made the catalog look like an inventory and billing system it never was. Stock belongs to your fulfilment system; see [Billing Handoff](/docs/revenue/billing-handoff).
@@ -73,9 +75,14 @@ The product catalog is **public read-only** for the whole organisation. Sales re
 
 ## Standard list views
 
-- **Active Products** — `is_active = true`.
-- **By Category** — grouped.
-- **By Family** — grouped.
+Products saves **two** views (`src/views/product.view.ts`), and the two tabs above the list switch between them:
+
+| View | What it shows | Tab |
+| --- | --- | --- |
+| **All Products** | The grid: product code (pinned left, and the link into the record), name, category, family, SKU, list price with a column average, cost and Active. Sorted by name and **grouped by category**, 50 rows a page. | *All* |
+| **Product Catalog** | The same products drawn as cards, with the **Product Image** as the cover and product code, category, family, list price and SKU on the face. | *Catalog* |
+
+Neither view filters anything, so **every product appears in both**, inactive ones included, and switching tabs only redraws them. There is no saved *Active Products*, *By Category* or *By Family* view: grouping by category is a setting on the grid above, not a second saved view, and nothing groups by family at all. To work with active products only, sort or filter the **Active** column yourself.
 
 ## Tips for product managers
 
@@ -85,7 +92,7 @@ The product catalog is **public read-only** for the whole organisation. Sales re
 
 ## Tips for sales reps
 
-- ✅ Use products from the catalog rather than typing line items by hand — pricing and tax are auto-filled.
+- ✅ Use products from the catalog rather than typing line items by hand — the List Price is filled in for you, and on a new line the Sales Price starts there too. Tax is not filled in: enter it on the quote.
 - ✅ Check the datasheet before proposing — it usually has the exact spec sheet you need for the proposal.
 
 ## Tips for admins

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

@@ -44,10 +44,12 @@ description: 你所销售内容的目录——编码、标价、SKU 和税率。
 | --- | --- |
 | **List Price** | 标准公布价——默认显示在报价上的价格 |
 | **Cost** | 你的成本——用于利润计算 |
-| **Default Tax Rate %** | 产品记录上携带的税率 |
+| **Default Tax Rate %** | 存在产品记录上。没有任何东西会应用它——见下 |
 
 如果成本大于标价（这会是一笔亏本的销售），系统会警告你。
 
+**税是报价单层面的数字，产品上的税率不会被应用到任何地方。** 把产品标价填到报价或商机明细行上的那段价格填充逻辑并不会复制税率；报价单的总额是 *小计 − 折扣 + 税额 + 运费*，其中**税额**是你在报价单上自己填的一个金额。报价明细行有它自己的 **Tax Rate %**，默认为 0、按行设置。所以今天在产品上设置 *Default Tax Rate %*，不会改变任何地方的任何金额。
+
 ## 没有库存，也没有计费周期
 
 产品记录就是一条目录条目，仅此而已。HotCRM **不保存任何库存数字**——没有库存数量、没有补货阈值，赢单也不会扣减任何东西——也**没有计费周期或计量单位**：订阅如何计费属于合同和报价，而不属于目录行。这些字段过去声明在这里、却没有任何东西读取，让目录看起来像一套它从来不是的库存与计费系统。库存属于你的履约系统；参见 [计费交接](/zh-Hans/docs/revenue/billing-handoff)。
@@ -73,9 +75,14 @@ description: 你所销售内容的目录——编码、标价、SKU 和税率。
 
 ## 标准列表视图
 
-- **Active Products**——`is_active = true`。
-- **By Category**——分组。
-- **By Family**——分组。
+产品一共保存了**两个**视图（`src/views/product.view.ts`），列表上方的两个标签在它们之间切换：
+
+| 视图 | 它展示什么 | 标签 |
+| --- | --- | --- |
+| **All Products** | 表格：产品编码（固定在左侧，也是进入记录的链接）、名称、类别、产品系列、SKU、标价（列尾带平均值）、成本和是否活跃。按名称排序，并**按类别分组**，每页 50 行。 | *All* |
+| **Product Catalog** | 同一批产品画成卡片，以 **Product Image** 作为封面，卡面上是产品编码、类别、产品系列、标价和 SKU。 | *Catalog* |
+
+两个视图都没有任何过滤条件，所以**每个产品在两个视图里都在**（包括已停用的），切换标签只是换一种画法。不存在名为 *Active Products*、*By Category* 或 *By Family* 的已保存视图：按类别分组是上面那个表格的一项设置，而不是第二个已保存视图，而按产品系列分组则根本不存在。只想看活跃产品，请自己对**是否活跃**这一列排序或过滤。
 
 ## 给产品经理的提示
 
@@ -85,7 +92,7 @@ description: 你所销售内容的目录——编码、标价、SKU 和税率。
 
 ## 给销售代表的提示
 
-- ✅ 使用目录中的产品，而不是手动输入明细行——定价和税会被自动填充。
+- ✅ 使用目录中的产品，而不是手动输入明细行——标价会自动填好，新建明细行时销售价格也从标价起步。税不会被填充：请在报价单上填写。
 - ✅ 在提案前检查规格表——它通常包含你提案所需的确切规格表。
 
 ## 给管理员的提示

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

@@ -44,10 +44,12 @@ description: 你所銷售內容的目錄——編碼、標價、SKU 和稅率。
 | --- | --- |
 | **List Price** | 標準公佈價——預設顯示在報價上的價格 |
 | **Cost** | 你的成本——用於利潤計算 |
-| **Default Tax Rate %** | 產品記錄上攜帶的稅率 |
+| **Default Tax Rate %** | 存在產品記錄上。沒有任何東西會套用它——見下 |
 
 如果成本大於標價（這會是一筆虧本的銷售），系統會警告你。
 
+**稅是報價單層級的數字，產品上的稅率不會被套用到任何地方。** 把產品標價填到報價或商機明細行上的那段價格填充邏輯並不會複製稅率；報價單的總額是 *小計 − 折扣 + 稅額 + 運費*，其中**稅額**是你在報價單上自己填的一個金額。報價明細行有它自己的 **Tax Rate %**，預設為 0、逐行設定。所以今天在產品上設定 *Default Tax Rate %*，不會改變任何地方的任何金額。
+
 ## 沒有庫存，也沒有計費週期
 
 產品記錄就是一條目錄條目，僅此而已。HotCRM **不保存任何庫存數字**——沒有庫存數量、沒有補貨閾值，贏單也不會扣減任何東西——也**沒有計費週期或計量單位**：訂閱如何計費屬於合約和報價，而不屬於目錄列。這些欄位過去宣告在這裡、卻沒有任何東西讀取，讓目錄看起來像一套它從來不是的庫存與計費系統。庫存屬於你的履約系統；參見 [計費交接](/zh-Hant/docs/revenue/billing-handoff)。
@@ -73,9 +75,14 @@ description: 你所銷售內容的目錄——編碼、標價、SKU 和稅率。
 
 ## 標準列表檢視
 
-- **Active Products**——`is_active = true`。
-- **By Category**——分組。
-- **By Family**——分組。
+產品一共儲存了**兩個**檢視（`src/views/product.view.ts`），列表上方的兩個標籤在它們之間切換：
+
+| 檢視 | 它展示什麼 | 標籤 |
+| --- | --- | --- |
+| **All Products** | 表格：產品編碼（釘在左側，也是進入記錄的連結）、名稱、類別、產品系列、SKU、標價（欄尾帶平均值）、成本和是否活躍。按名稱排序，並**按類別分組**，每頁 50 列。 | *All* |
+| **Product Catalog** | 同一批產品畫成卡片，以 **Product Image** 作為封面，卡面上是產品編碼、類別、產品系列、標價和 SKU。 | *Catalog* |
+
+兩個檢視都沒有任何過濾條件，所以**每個產品在兩個檢視裡都在**（包括已停用的），切換標籤只是換一種畫法。不存在名為 *Active Products*、*By Category* 或 *By Family* 的已儲存檢視：按類別分組是上面那個表格的一項設定，而不是第二個已儲存檢視，而按產品系列分組則根本不存在。只想看活躍產品，請自己對**是否活躍**這一欄排序或過濾。
 
 ## 給產品經理的提示
 
@@ -85,7 +92,7 @@ description: 你所銷售內容的目錄——編碼、標價、SKU 和稅率。
 
 ## 給銷售代表的提示
 
-- ✅ 使用目錄中的產品，而不是手動輸入明細行——定價和稅會被自動填充。
+- ✅ 使用目錄中的產品，而不是手動輸入明細行——標價會自動填好，新增明細行時銷售價格也從標價起步。稅不會被填充：請在報價單上填寫。
 - ✅ 在提案前檢查規格表——它通常包含你提案所需的確切規格表。
 
 ## 給管理員的提示

content/docs/service/cases.mdx

@@ -149,7 +149,7 @@ See [SLA & Escalation](/docs/service/sla-and-escalation) for the full mechanics.
 
 ## Standard list views
 
-`crm_case` ships **seven** views (`src/views/case.view.ts`), and the case list surfaces them as tabs:
+`crm_case` ships **eight** views (`src/views/case.view.ts`), and the case list surfaces them as tabs:
 
 | View | What it shows | Tab |
 | --- | --- | --- |
@@ -158,6 +158,7 @@ See [SLA & Escalation](/docs/service/sla-and-escalation) for the full mechanics.
 | **SLA Calendar** | Cases laid out on their **SLA Due Date** — every case carries one now, so the calendar shows the whole open backlog | *SLA* |
 | **Case Timeline** | Cases on a *created → closed* timeline, grouped by owner | *Timeline* |
 | **Escalated Cases** | `is_escalated` is true | *Escalated* |
+| **Unassigned — triage** | Open cases with no owner at all, urgent first then soonest due — where a web-to-case submission lands when nobody holds the Service Agent position | *Triage* |
 | **⏰ SLA at Risk** | Open **High and Critical** cases, soonest due date first | *SLA at Risk* |
 | **My Open Cases** | Your cases that are not closed | *My Cases* |
 

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

@@ -149,7 +149,7 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 
 ## 标准列表视图
 
-`crm_case` 一共发布 **7 个**视图（`src/views/case.view.ts`），工单列表把它们做成页签：
+`crm_case` 一共发布 **8 个**视图（`src/views/case.view.ts`），工单列表把它们做成页签：
 
 | 视图 | 展示什么 | 页签 |
 | --- | --- | --- |
@@ -158,6 +158,7 @@ description: 客户支持工单——主题、优先级、状态、解决方案
 | **SLA Calendar** | 按 **SLA 截止日期** 把工单铺在日历上——现在每张工单都带截止日期，所以它显示的是整个未结积压 | *SLA* |
 | **Case Timeline** | 工单按「创建 → 关闭」铺在时间轴上，按负责人分组 | *Timeline* |
 | **Escalated Cases** | `is_escalated` 为真 | *Escalated* |
+| **Unassigned — triage** | 完全没有负责人的未结工单，先按紧急程度、再按最近的截止日期——没有人担任服务坐席时，Web 提交的工单就落在这里 | *Triage* |
 | **⏰ SLA at Risk** | 未结的 **High 与 Critical** 工单，截止日期最近的排在前面 | *SLA at Risk* |
 | **My Open Cases** | 你名下尚未关闭的工单 | *My Cases* |