天猫销售两年交叉对比（读 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 必须包含以下列（列名需匹配；若列名不同，先与用户确认映射关系，不要擅自改列名）：
| 列名 | 含义 | 说明 |
|---|---|---|
| 商品代码 | 唯一条码/商品编码 | 第一列，唯一键，不可篡改 |
| 商品名称 | 商品名称 | 展示用 |
| 数量 | 原始发货数量 | 含退货 |
| 让利后金额 | 让利后金额 | 非主指标，保留原样 |
| 去退后销量 | 去退后销量 | 主指标之一 |
| 去退后金额 | 去退后金额 | 主指标之一 |
| 品类 | 商品所属品类 | 分析维度 |
| 年份 | 年份标识 | 如「2025年」「2026年」，自动提取 4 位年份 |
> 若列名略有差异（如「货号」「条码」），按语义灵活匹配，不要因叫法不同就跳过。
工作流程
-
确认环境与依赖
使用 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。 -
一键运行
进入 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会依次调用：
-analyze.py：读取→以条码为键做两年聚合→算绝对Δ与变化率/退货率（数量口径）/品类与商品交叉/消失新增排序与弱品类弱化/孤品vs常规品量化(weak_summary)/指标口径目录(metrics_catalog)/全量明细/图表数据→写出analysis.json。
-gen_report.py：把analysis.json注入references/report_template.html，并内联scripts/chartjs.min.js→写出脱机 HTML。
-gen_excel.py：把analysis.json写出多 Sheet 的 Excel。 -
输出位置
- 默认：与输入文件同目录，文件名 = 源基名 +-report.html/-分析表.xlsx/analysis.json。
- 若输入文件在只读/受控目录（如某些 Desktop 子目录），用--outdir指定一个可写目录（如当前工作区）再交付。 -
交付与校验
- 用present_files展示 HTML（预览面板）与 Excel。
- 自检：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 占位），页眉/结论/各章节计数均由数据动态生成，换任何数据文件均可复用。references/design-brief.md：报告视觉设计方向（杂志风 / 信息密度高 / 克制配色）。
环境依赖
- Python 3.10+（托管 venv 已满足）
pandas、xlrd（仅 .xls）、openpyxl、charset-normalizer
> 注：本 Skill 由本会话中实际跑通的天猫销售交叉对比流程固化而来；其前身（仅出 Excel 原生图表 + 可选 PNG 的版本）已归档至工作区 archive_old_skill/，未删除。
