name: sales-cross-year-comparison description: | 用於對天貓/電商銷售資料做兩年（如 2025 vs 2026）交叉對比分析，並一鍵產出 HTML 報告 + Excel 分析表。當用戶上傳包含【商品程式碼】【商品名稱】【數量】【讓利後金額】【去退後銷量】【去退後金額】【品類】【年份】列的 Excel（.xls / .xlsx），並要求按條碼做 上升/下跌/消失/新增 分析、用「數量−去退後銷量」算退貨率並找出異常品、看品類漲跌、以及同步生成 HTML（含圖表+表格）和 Excel（可篩選透視）時使用本 Skill。 version: 2.0.0 agent_created: true

天貓銷售兩年交叉對比（讀 xls → 分析 → 出 HTML + Excel）

Overview

以「商品程式碼（條碼，第一列）」為唯一鍵，對兩年同期銷售資料做交叉對比。核心指標為 去退後金額 與 去退後銷量；同時用 數量 與 去退後銷量 計算退貨率。一條命令產出：

• <源基名>-report.html：雜誌風 HTML 報告（Chart.js 已內聯，斷網也能看圖表），含 KPI、圖表、資料解答說明（計算口徑） 主區塊、品類交叉表、商品四態表（上升/下跌/消失/新增）、退貨率異常表（高退區 ≥15%）、背後關注點、商品全量明細表。每張衍生表正上方帶 📐 計算口徑（分行展示，不擠一行）。
• <源基名>-分析表.xlsx：多 Sheet Excel（① 指標說明（計算口徑） / 概覽 / 品類交叉 / 商品四態 / 退貨率異常 / 資料需複核 / 全量明細 / 關注點），深藍表頭、凍結首行、漲紅跌綠、自動篩選；所有算出來的列都帶絕對變化數字（金額Δ¥ / 銷量Δ件）+ 變化率。
• analysis.json：中間產物（含 metrics_catalog 指標口徑目錄、weak_summary 孤品/常規品量化），供二次消費與 HTML/Excel 同源渲染。

觸發條件

使用者提到以下任一表述時觸發本 Skill：

• 「2025 和 2026 銷售交叉對比」「按條碼看哪些上漲/下跌/消失/新增」
• 「退貨率分析」「去退後銷量/金額分析」「數量減掉退後算退貨」
• 「品類維度對比」「生成 HTML 報告」「匯出 Excel」「出圖表和表格」

輸入資料要求

輸入 Excel 必須包含以下列（列名需匹配；若列名不同，先與使用者確認對映關係，不要擅自改列名）：

若列名略有差異（如「貨號」「條碼」），按語義靈活匹配，不要因叫法不同就跳過。

工作流程

1. 確認環境與依賴 使用 WorkBuddy 託管的 Python 虛擬環境（已隔離，含 pandas / xlrd / openpyxl / charset-normalizer）： C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe 若依賴缺失，在該 venv 下 python -m pip install pandas xlrd openpyxl charset-normalizer。

2. 一鍵執行 進入 Skill 的 scripts/ 目錄，執行編排指令碼（輸入檔案路徑 + 可選輸出目錄）： bash PY="C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe" SKILL="C:/Users/Administrator/.workbuddy/skills/sales-cross-year-comparison/scripts" "$PY" "$SKILL/run_all.py" "<原始檔.xls 或 .xlsx>" [--outdir "<輸出目錄>"] run_all.py 會依次呼叫：

3. analyze.py：讀取→以條碼為鍵做兩年聚合→算絕對Δ與變化率/退貨率（數量口徑）/品類與商品交叉/消失新增排序與弱品類弱化/孤品vs常規品量化(weak_summary)/指標口徑目錄(metrics_catalog)/全量明細/圖表資料→寫出 analysis.json。
4. gen_report.py：把 analysis.json 注入 references/report_template.html，並內聯 scripts/chartjs.min.js→寫出離線 HTML。

5. gen_excel.py：把 analysis.json 寫出多 Sheet 的 Excel。

6. 輸出位置

7. 預設：與輸入檔案同目錄，檔名 = 源基名 + -report.html / -分析表.xlsx / analysis.json。

8. 若輸入檔案在只讀/受控目錄（如某些 Desktop 子目錄），用 --outdir 指定一個可寫目錄（如當前工作區）再交付。

9. 交付與校驗

10. 用 present_files 展示 HTML（預覽面板）與 Excel。
11. 自檢：gen_report.py 會列印 has cdn.jsdelivr: False（確認無外部 CDN 依賴）、has </script>: 2（確認 Chart.js 已內聯且結構完整）。

分析口徑（務必嚴格遵守）

• 唯一鍵：商品程式碼（條碼）。一行 = 某商品在某年的銷售彙總。
• 主指標：去退後金額、去退後銷量。
• 絕對變化 + 變化率必須同源取數（重要教訓）：
• 金額Δ(¥) = 26去退後金額 − 25去退後金額；金額變化率 = Δ ÷ 25去退後金額。
• 銷量Δ(件) = 26去退後銷量 − 25去退後銷量；銷量變化率 = Δ ÷ 25去退後銷量。
• ⚠️ 銷量變化率必須用去退後銷量算，絕不能錯用「數量(qty)」列——兩列口徑打架會出現「Δ件=-2 卻顯示 +50%」的反直覺錯誤（v1.1 已修復此 bug）。
• 每張比較表都要同時給出絕對數字和變化率，不能只給率（高價品單價高，只看率會誤判影響體量）。
• 退貨率（數量口徑，真實資料）：(數量 − 去退後銷量) / 數量。異常判定：≥15% 偏高（進入高退區，建議中觀關注）、≥50% 嚴重、<0 或 >100% 為負值/邏輯異常（去退後銷量為負）。
• 交叉狀態：以條碼為鍵取兩年並集——
• 消失：舊年有、新年無（注意：若資料視窗僅為某段日期，多為該視窗內無銷售，不等於全年下架）；
• 新增：新年有、舊年無；
• 共有：兩年均有，按去退後金額判定 上升/下跌/持平。
• 消失/新增排序與弱品類弱化：消失/新增列表按 (弱品類置後, 品類, -金額) 排序；WEAK_CATS = {閒章印石, 社員作品}（多為孤品、不可複製、參考意義有限），排到最後並在文案中弱化，避免誤讀。
• 孤品 vs 常規品量化（weak_summary）：對消失/新增分別算孤品與常規品的金額、銷量合計及佔比 + 常規品金額 Top5。中性如實量化——孤品金額體量大就照實說（某些視窗新增孤品金額佔比可高達 80%+），但同時點明「孤品多為一次性、不可複製；常規品才是可運營最佳化的主流」。切勿把「孤品影響有限」寫死（會與真實資料矛盾）。
• 計算口徑展示：所有算出來的列都在 HTML/Excel 裡給出計算公式說明（資料解答說明）；每個演算法分行展示，不用「：」擠一行。口徑目錄沉澱在 analyze.py 的 metrics_catalog，HTML 與 Excel 同源渲染，保證口徑永遠一致。

資料完整性原則

• 不刪除、不修改、不四捨五入原始資料；僅對展示格式（單元格數字格式、顏色、HTML 表格）做調整。
• 對明顯邏輯矛盾/零值（負值、去退後>讓利後、去退後銷量為負）在 「資料需複核」Sheet 單獨標註，提示覆核原始訂單後再計入彙總，不視為正常業務資料（否則會汙染品類彙總）。
• 所有數值按原始檔原樣寫入 Excel/JSON，HTML 趨勢與表格可交叉驗證。

資源引用

• scripts/run_all.py：一鍵編排（analyze → gen_report → gen_excel）。
• scripts/analyze.py：核心分析，輸出 analysis.json（引數：<input> 必填，--outdir 可選）。
• scripts/gen_report.py：生成離線 HTML（--json 必填，--out 可選）。
• scripts/gen_excel.py：生成 Excel（--json 必填，--out 可選）。
• scripts/chartjs.min.js：內聯的 Chart.js 4.x（斷網可用）。
• references/report_template.html：雜誌風報告模板，含 __DATA__（資料佔位）與 __CHARTJS__（Chart.js 佔位），頁首/結論/各章節計數均由資料動態生成，換任何資料檔案均可複用。

  7w4.net收錄了海量優質技能外掛。

• references/design-brief.md：報告視覺設計方向（雜誌風 / 資訊密度高 / 剋制配色）。

環境依賴

• Python 3.10+（託管 venv 已滿足）
• pandas、xlrd（僅 .xls）、openpyxl、charset-normalizer

注：本 Skill 由本會話中實際跑通的天貓銷售交叉對比流程固化而來；其前身（僅出 Excel 原生圖表 + 可選 PNG 的版本）已歸檔至工作區 archive_old_skill/，未刪除。

整體質量良好，是一款成熟的銷售資料分析工具。優點：分析邏輯完整、文件清晰易懂、圖表美觀專業、退貨率異常檢測實用、計算口徑透明；輸出同時包含視覺化報告和可篩選的 Excel，方便不同場景使用。不足：沒有測試覆蓋，偶爾可能有 bug；依賴的是已停止更新的舊庫，存在相容隱患。推薦用於常規銷售對比分析，但建議先用小資料驗證輸出準確性。