销售数据分析与可视化
把一份销售明细 Excel 变成一份可直接交付的分析报告：多维图表 + 数据驱动的结论 + 行动清单。
报告中的图表全部以内联 SVG 渲染，不依赖任何 CDN、JS 库或外部字体。生成的 HTML 是单文件、完全自包含的——断网、内网、离线电脑上打开都能完整显示。
快速开始
第 1 步：环境自检
python scripts/check_env.py
会告诉你依赖是否齐备，以及缺什么、怎么装。
第 2 步：一键体验（可选）
不想准备数据？直接生成一份演示报告看看效果：
python scripts/gen_sales_report.py --demo --output 演示报告.html
脚本会自造一份销售明细并产出完整报告。
第 3 步：用真实数据出报告
python scripts/gen_sales_report.py --input 销售明细.xlsx --output 销售分析报告.html
环境要求
| 项 | 要求 |
|---|---|
| Python | 3.8 或更高 |
| 必需依赖 | openpyxl（读写 Excel）→ pip install openpyxl |
| 可选依赖 | pymupdf（仅 PDF 提取用到）→ pip install "pymupdf>=1.23.0" |
> python 命令不可用时，按你的系统改用 python3 或 py。
> 命令中的 scripts/ 指本技能目录下的 scripts 文件夹，按实际安装位置调整。
输入格式
只需一份 Excel（.xlsx），第一行为列标题。列名会自动识别，不必严格一致：
| 用途 | 可识别的列名（包含即匹配） |
|---|---|
| 销售额（必需） | 销售额、销售金额、成交金额、金额、业绩、营收、收入、GMV、amount、sales |
| 销量（可选） | 销量、销售数量、数量、件数、台数、qty |
| 日期（可选） | 日期、下单时间、成交日期、时间、月份、下单日期、签约日期、周、year、week、date、month |
| 维度（至少一个） | 区域/地区/大区/省区/城市、产品线/产品/品类、业务员/销售员/负责人/员工、渠道/门店/客户/来源/部门、省份/品牌/型号/团队/小组/门店名称/客户名称/会员 |
| 目标（可选） | 目标、销售目标、业绩目标、预算、target、goal、quota |
| 成本（可选） | 成本、采购成本、成本额、成本(元)、cost |
| 利润（可选） | 利润、毛利、净利润、利润(元)、profit、margin、gross_profit |
| 客户（可选） | 客户、客户名称、客户类型、客群、会员、buyer、customer |
最简可用格式：只要「销售额」+ 任意一个维度列就能出报告。
有销量列 → 额外产出客单价、效能四象限、利润质量分析；有日期列 → 额外产出周期趋势。
> 列名对不上？把金额列改名为「销售额」即可。多出的列（备注、订单号等）会被忽略。
流水线 1：销售分析报告（推荐）
python scripts/gen_sales_report.py \
--input 销售明细.xlsx \
--output 销售分析报告.html \
--title "2026年8月销售分析"
| 参数 | 说明 |
|---|---|
-i, --input |
销售明细 Excel 路径 |
-o, --output |
输出 HTML 路径（默认 <输入名>_分析报告.html） |
--title |
报告标题（默认「销售数据分析报告」） |
--sheet |
指定工作表名，默认取第一个 |
--demo |
用内置演示数据出报告，无需自备文件 |
--markdown |
同时生成 Markdown 文字版经营简报（<输出名>_简报.md） |
--export-svg |
将报告内所有内联 SVG 图表导出为独立 .svg 文件；可跟目录，省略则用 <输出名>_svgs/ |
报告包含的内容
| 模块 | 内容 |
|---|---|
| KPI 概览 | 总销售额、平均客单价、总销量、订单数、Top20% 集中度；若有成本/利润列额外显示毛利率，有目标列额外显示目标完成率 |
| 各维度分析 | 每个维度一组：柱线双轴图（销售额 + 客单价）+ 占比环形图 + 明细表 |
| 效能四象限 | 气泡散点图，以客单价/人均销量为基准线划分明星、潜力、走量、待提升 |
| 月度趋势与环比 | 按自然月汇总的折线图（销售额 + 销量双序列），并标注相邻月的环比增长率（涨绿跌红） |
| 二八帕累托 | 柱图 + 累计占比折线，80% 虚线标注关键少数，一眼看清贡献 80% 的少数品类/人员 |
| 目标完成率 | 半圆仪表盘直观显示实际相对目标的完成度（红/橙/绿三档） |
| 成本与盈利 | 有成本/利润列时，输出总成本、毛利、毛利率与单均毛利 |
| 异常检测 | IQR 法识别各维度中偏离常态的离群销售额，主动提示复核 |
| 交叉矩阵 | 前两个维度的热力矩阵，定位优势组合与空白机会 |
| 结论与行动 | 自动生成的洞察 + 可执行行动清单；另可 --markdown 生成纯文字简报 |
洞察是算出来的，不是写死的
所有结论都由当前数据实时计算，包括：规模与质量的背离、销售额第一是否等于效率最高、高客单低渗透市场、业绩集中度、交叉洼地、周期峰值、月度环比拐点、二八关键少数、目标达成缺口、毛利率与异常离群值。换一份数据，结论就跟着变。
对不完整周期（如月末残周）会自动标注口径提示，避免误读环比。
流水线 2：Excel 格式化报表
需要把结果继续加工、发给同事时用这个：
python scripts/gen_excel_report.py \
--input 销售明细.xlsx \
--output 销售月报.xlsx \
--group-by 业务员,区域,产品线
| 参数 | 说明 |
|---|---|
-i, --input |
销售明细 Excel |
-o, --output |
输出 xlsx 路径 |
-g, --group-by |
分组维度，逗号分隔（每个维度一个工作表） |
--target |
可选，销售目标值，用于计算完成率与排名 |
三色规则（财务/经营报表通用约定）：
| 颜色 | 含义 |
|---|---|
| 🔵 蓝色 | 输入项 / 目标值 |
| ⚫ 黑色 | 计算值 / 实际值 |
| 🟢 绿色 | 公式 / 完成率 |
每个分组维度输出一个工作表，含销售额、销量、单数、客单价、完成率与自动排名，末尾带汇总行。
流水线 3：PDF / 图片文字提取
把手头只有 PDF 或截图的数据导入进来（需先装 pymupdf）：
python scripts/pdf_extract.py \
--input 订单.pdf \
--output 提取结果.md
- PDF：提取文本块并按
(y, x)坐标排序，尽量还原阅读顺序 - 图片（订单截图、名片、合同照片）：交给 AI 的图像识别能力处理
> ⚠️ 已知限制：PDF 提取的是纯文本块，表格的列结构不会自动还原，需要人工二次对齐。脚本会同时输出原始块供对照。
可视化设计说明
| 设计选择 | 原因 |
|---|---|
| 内联 SVG，不用 Canvas/JS | 断网、内网、老旧浏览器都能显示；截图、打印、转 PDF 不失真 |
| 零外部资源 | 报告可以单文件邮件发送、U 盘拷贝，不会出现「图片裂了」 |
| 单文件 HTML | 不需要部署、不需要服务器，双击即看 |
| 配色区分涨跌 | 遵循中文财务习惯，报告面向国内经营场景 |
常见问题
Q：提示「未识别到销售额列」？
把金额列的表头改成「销售额」即可。用 --input 传入的文件第一行必须是列标题。
Q：报告打开后图表是空白？
v2.0.0 起图表为内联 SVG，不会出现此问题。若仍空白，请确认生成的是最新版本脚本（旧版曾依赖境外 CDN）。
Q：能算目标完成率、毛利率吗？
能。把列名设为「目标 / 成本(元) / 利润(元)」之类（包含关键词即可自动识别），报告会显示目标完成率仪表盘、毛利率 KPI 与成本盈利模块，Excel 报表也会带上成本/毛利/毛利率列。
Q：想要纯文字版发到群里 / 飞书？
加 --markdown 参数，会额外生成一份 <输出名>_简报.md，含核心指标、维度排名、月度趋势、二八结论与行动清单，直接复制即可。
Q：想把图表单独放进 PPT？
加 --export-svg 参数，报告里每个图表会导出为独立 .svg 文件（矢量、可无限缩放不失真），直接插入 PPT / 文档。
Q：中文显示成方块？
报告使用系统字体链（苹方 / 微软雅黑 / 思源黑体）。若系统缺中文字体，安装任一常见中文字体即可。
Q：能处理多大的数据量？
万行级别没问题。报告只取每个维度的前 8 项作图，表格给出全量，避免图表拥挤。
Q：数据敏感，会上传到外部吗？
不会。全部计算在本机完成，脚本不发起任何网络请求。
Q：想改配色 / 加维度？
直接改脚本里的 CC 色板数组；维度词表在文件顶部的 DIM_KEYS，加词就能识别新维度。
输出规范
- 所有数值均来自原始数据聚合，不估算、不补齐缺失值
- 涉及客户姓名、电话、价格体系的数据，输出前请确认是否需要脱敏
- 非完整周期数据会明确标注口径限制，不参与环比结论
- 报告结论供经营参考，涉及重大决策请结合业务实际复核
附：文件清单
SKILL.md 本说明
README.md 简版介绍
CHANGELOG.md 版本更新日志
workbuddy.json 平台元数据
scripts/
check_env.py 环境自检
gen_sales_report.py 流水线 1：分析报告（内联 SVG 可视化）
gen_excel_report.py 流水线 2：Excel 格式化报表
pdf_extract.py 流水线 3：PDF 文字提取
