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 已内联且结构完整）。

分析口径（务必严格遵守）

来源于7w4.net。

• 唯一键：商品代码（条码）。一行 = 某商品在某年的销售汇总。
• 主指标：去退后金额、去退后销量。
• 绝对变化 + 变化率必须同源取数（重要教训）：
• 金额Δ(¥) = 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/，未删除。

整体质量良好，是一款成熟的销售数据分析工具。优点：分析逻辑完整、文档清晰易懂、图表美观专业、退货率异常检测实用、计算口径透明；输出同时包含可视化报告和可筛选的 Excel，方便不同场景使用。不足：没有测试覆盖，偶尔可能有 bug；依赖的是已停止更新的旧库，存在兼容隐患。推荐用于常规销售对比分析，但建议先用小数据验证输出准确性。