程式資訊

程式 ID：ITEMSHIP
所屬子系統：M.主管資訊
狀態：stable

品號出貨毛利統計¶

此功能尚在開發中（beta），查詢邏輯目前停用

本頁描述「品號出貨毛利統計（Itemship）」的設計用途。在目前版本中，這支表單的查詢與報表邏輯（資料載入、毛利計算、列印）在 ItemshipViewModel 裡是停用（註解）狀態——畫面與欄位都已備好，但 Query() 方法內容為空，按下查詢不會帶出任何資料。因此以下「操作步驟」描述的是設計上的預期行為，尚不可實際使用。等功能正式啟用後本頁會改寫成可操作版本。

功能簡介¶

「品號出貨毛利統計」原本是主管資訊（M-EIS）模組中 Daily 主管日報儀表板 的一個分頁，用來以品號（SKU）為單位呈現出貨銷售的金額、成本、毛利與毛利率，並同時提供本月累計（MTD）與本年度累計（YTD）兩種口徑，供業務／營運主管快速掌握各品號的獲利貢獻。

依程式碼規劃，資料來源以查詢日期（TransactionDate）為基準，由 SP PRIME_QRY_DAILY_ITEMSHIP 一次回傳兩組結果：

YTD（年度累計）：自當年 1/1 起到查詢日的累計銷售額、成本與毛利。
MTD（當月累計）：自當月 1 日起到查詢日的累計銷售額、成本與毛利。

兩組結果再依品號合併成一份報表，並可依消費性（Consumer）與工業用（Industrial）兩種報表型態分別列印。

與 Daily 主管儀表板的關係

本表單與 Daily 主管日報共用同一個 ProgramClass.Daily 與同一份 ItemshipViewModel。在 Daily 儀表板中它以「Itemship」分頁的形式出現（設定為僅供列印 OnlyPrint）；本頁則對應其獨立開啟的版本。兩者背後是同一支程式邏輯，啟用後的計算方式一致。

前置需求¶

權限：M.主管資訊 → 本表單的瀏覽／列印權限。
資料來源：查詢結果完全來自 SP PRIME_QRY_DAILY_ITEMSHIP，畫面本身不做計算。下列基礎資料的維護狀況會影響報表內容——

資料	影響的結果
出貨／銷貨交易（出貨單／銷貨單）	各品號的銷售金額（Sales Amount）來源
品號主檔（含品名、群組碼）	SKU／品名（SKUDescription）／群組碼（Group Code）／說明（Description）欄位
成本資料（成本管理）	各品號的成本（Cost）與毛利、毛利率計算基礎

SP 為前提

本表單沒有自帶 SQL，完全倚賴後端 SP PRIME_QRY_DAILY_ITEMSHIP 回傳兩張結果表（YTD、MTD）。若該 SP 未部署或未在 proc_param 登錄，啟用後查詢會回空或報錯。

操作步驟¶

以下為規劃中的預期流程，目前不可操作

在功能正式啟用前，以下步驟僅供理解設計用途，實際執行不會帶出資料。

開啟本表單。系統會把查詢日期預設帶為今天（程式於建構時以 DateTimeWrapper.TodayYYYYMMDD() 帶入）。
視需要修改 Date（查詢日期 / Transaction Date）：此日期同時決定 YTD 與 MTD 的截止點。
- YTD 起算日 = 查詢日所屬年度的 1/1。
- MTD 起算日 = 查詢日所屬月份的 1 日。
按工具列的 查詢，結果顯示在兩個頁籤：
- CS By Item：以品號列出年度累計銷售金額（Sales Amount）。
- CS Margin By Item：以品號列出 MTD 與 YTD 的銷售金額、成本、毛利與毛利率。
需要列印時，透過列印版面（PrintLayoutControl）選擇報表型態（消費性／工業用）後輸出。報表規劃使用 ItemShipYTD 報表樣板，並帶入公司名稱、報表型態與查詢日期。

欄位說明¶

查詢條件¶

欄位	必填	說明/格式/預設
Date（查詢日期）	✔	短日期格式（ShortDate）。預設為今天。同時作為 YTD 與 MTD 的截止日；YTD 由當年 1/1 起算、MTD 由當月 1 日起算。查詢條件是否成立由 `HaveReportData()` 判斷——日期為空白即不執行查詢。

結果欄位（規劃）¶

下列欄位來自畫面綁定與 SP 回傳的兩組結果合併（YTD 一筆、MTD 一筆，以 SKU 對應）：

頁籤	欄位	說明
CS By Item	SKU	品號
	SKUDescription	品名
	Group Code	品號群組碼
	Description	群組／類別說明
	Sales Amount	年度累計（YTD）銷售金額
CS Margin By Item	SKU / SKUDescription / Group Code / Description	同上，品號基本資料
	Sales Amount MTD	當月累計銷售金額
	Cost MTD	當月累計成本
	Margin MTD	當月累計毛利（銷售額 − 成本）
	Avg Margin% MTD	當月平均毛利率，規劃以 SP 回傳值 ×100 換算為百分比顯示
	Sales Amount YTD	年度累計銷售金額
	Cost YTD	年度累計成本
	Margin YTD	年度累計毛利
	Avg Margin% YTD	年度平均毛利率，規劃以 SP 回傳值 ×100 換算為百分比顯示

金額欄的幣別

結果頁多數金額欄（CS By Item 的 Sales Amount，以及 CS Margin By Item 的 Cost、Margin、Margin% 等欄）在 XAML 中設定 PlaceEnum="Local"，以本位幣（Local）呈現。但 CS Margin By Item 頁的 Sales Amount MTD／YTD 兩欄未設此屬性。

欄位連動與附加功能¶

以下行為描述自程式碼，但目前多數處於停用狀態

這一節整理程式碼中規劃的連動與附加功能。標明「規劃中／停用」者，在目前版本不會作用。

開啟表單時自動帶今天的查詢日期（已實作）：ItemshipViewModel 建構時即把 TransactionDate 設為今天（DateTimeWrapper.TodayYYYYMMDD()），所以一進畫面日期欄就有值，不必手動輸入。
是否允許查詢的判斷（已實作）：HaveReportData() 會檢查查詢日期是否為空白；日期空白時不執行查詢。
按「查詢」後重算 YTD／MTD（規劃中／停用）：規劃中 Query() 會以查詢日推出三個基準日——查詢日本身、當年 1/1（YTD 起算）、當月 1 日（MTD 起算），呼叫 SP PRIME_QRY_DAILY_ITEMSHIP 取回 YTD 與 MTD 兩張表，再以 SKU 為鍵把 MTD 的成本／毛利／毛利率併進對應品號列。目前 Query() 內容為空，按查詢不會帶資料。
毛利率自動換算百分比（規劃中／停用）：規劃中把 SP 回傳的毛利率（PMarginMTD／PMarginYTD）乘以 100 後再顯示，亦即畫面上的 Avg Margin% 已是百分比數值。
消費性／工業用兩種報表（規劃中／停用）：規劃中提供 Consumer() 與 Industrial() 兩個列印來源，皆使用同一份 ItemShipYTD 報表樣板，差別在於報表型態參數（ReportType = Consumer / Industrial），並帶入公司名稱與查詢日期（轉成 MM/DD/YYYY 格式）。目前這兩個方法為停用狀態。
僅列印模式（已實作，作用於 Daily 儀表板）：當本 VM 被 Daily 主管日報以分頁方式嵌入時，會設定 OnlyPrint = true。規劃中此旗標決定列印時是即時重撈資料（GetData）或沿用畫面上已查詢的結果。因撈取邏輯停用，目前不影響實際輸出。

為什麼畫面有欄位卻查不到資料

Itemship.xaml 仍綁定 CSMarginByItem、SalesAmountYTD 等屬性，但這些屬性與其載入邏輯在 ItemshipViewModel 中目前是註解（停用）狀態。也就是說，UI 已備好、後端 SP 名稱也已登錄，但「把資料填進畫面」的程式碼尚未啟用，因此這是一支已搭好骨架、待啟用的功能。

常見問題¶

按了查詢，畫面為什麼一直空白？

目前本功能的查詢與資料載入邏輯在程式中是停用（註解）狀態，Query() 沒有實際動作，所以按查詢不會帶出任何資料。這不是設定或權限問題，而是功能尚未正式啟用。等啟用後，資料會由 SP PRIME_QRY_DAILY_ITEMSHIP 帶入。

毛利率（Avg Margin%）顯示的是小數還是百分比？

依規劃，SP 回傳的毛利率會在程式內乘以 100 後再顯示，因此畫面上的 Avg Margin% MTD／YTD 是百分比數值（例如 25 代表 25%），不是 0.25。此換算邏輯目前同樣處於停用狀態。

本頁和「Daily 主管日報」的 Itemship 分頁有什麼不同？

沒有功能上的不同——兩者共用同一支 ItemshipViewModel 與同一個 ProgramClass.Daily。差別只在於 Daily 儀表板把它當成其中一個分頁（並設為僅供列印），本頁則是它獨立開啟的入口。背後計算與資料來源完全一致。詳見 Daily 主管日報。

YTD 和 MTD 的起算日是怎麼決定的？

兩者都以畫面上的查詢日期為截止點：YTD 從查詢日所屬年度的 1/1 起算，MTD 從查詢日所屬月份的 1 日 起算。因此只要改查詢日，兩個累計區間會跟著一起變動。