Data Visualization Report Generator

从 CSV/Excel 数据生成专业的交互式 HTML 数据报表。

核心能力

数据处理与确认流程：自动分析列类型（数值/日期/类别/文本），向用户确认维度与度量映射
多模板 HTML 报表：3套模板（现代简约 / 数据看板 / 商务经典），带 ECharts 交互动效
一键截图：内置 html2canvas，一键导出 PNG 截图
全文可编辑：所有标题和标签支持 contentEditable 直接修改
中英文切换：默认中文，一键切换英文界面
颜色自动适配：从参考图片/HTML 提取主色调，或直接指定颜色
筛选联动：时间范围选择器 + 多维度下拉筛选
格式化规范：百分比2位小数、千分位、微软雅黑、涨红跌绿

使用流程

Step 1: 分析数据

python scripts/generate_html_report.py data.csv --analyze

输出将展示每列的类型、唯一值、空值率、数值范围等，并给出建议的维度/度量映射。

Step 2: 与用户确认

将分析结果呈现给用户，确认：

维度列（X轴 / 分组依据）：一般是日期或类别
度量列（Y轴 / 数值）：一般是数值列，需确认聚合方式（sum/avg/max/min/count）
图表类型：推荐合适的图表，让用户选择
KPI 指标：需要展示哪些关键数字卡片

Step 3: 生成报表

方式一：自动推断（快速）

python scripts/generate_html_report.py data.csv --auto --template modern -o report.html

如果参数不生效或想确认实际使用的配置，加 --verbose：

python scripts/generate_html_report.py data.csv --auto --verbose -o report.html

方式二：配置文件（精细控制）

创建 config.json：

{
  "title": "月度销售报表",
  "subtitle": "2024年Q1数据",
  "dimensions": [
    {"column": "month", "role": "x_axis"},
    {"column": "region", "role": "group_by"}
  ],
  "measures": [
    {"column": "revenue", "aggregation": "sum"},
    {"column": "profit", "aggregation": "sum"}
  ],
  "filters": [
    {"column": "region", "role": "filter"}
  ],
  "kpis": [
    {"column": "revenue", "aggregation": "sum", "label_cn": "总收入", "format": "currency"},
    {"column": "profit", "aggregation": "sum", "label_cn": "总利润", "format": "currency"}
  ],
  "charts": [
    {"chart_type": "bar", "x_column": "month", "y_columns": ["revenue", "profit"], "title_cn": "月度营收与利润"},
    {"chart_type": "pie", "x_column": "region", "y_columns": ["revenue"], "title_cn": "区域营收占比"},
    {"chart_type": "line", "x_column": "month", "y_columns": ["revenue"], "title_cn": "营收趋势"}
  ]
}

然后：

python scripts/generate_html_report.py data.csv --config config.json --template modern -o report.html

指定颜色

从参考图片提取：

python scripts/color_extractor.py logo.png --output palette.json
python scripts/generate_html_report.py data.csv --auto --color-file palette.json -o report.html

直接指定：

python scripts/generate_html_report.py data.csv --auto --colors "#1a73e8,#ea4335,#34a853" -o report.html

生成 Excel 报表（辅助功能）

python scripts/generate_excel_report.py data.csv --group-by region --value-columns revenue,profit --aggregation sum --chart-type bar --title "区域销售" -o report.xlsx

模板选择

| 模板 ID | 名称 | 特点 | 适用场景 | |---------|------|------|----------| | modern | 现代简约 | 白底、清爽、卡片阴影 | 日常报告、数据分析 | | dashboard | 数据看板 | 深色主题、数据大屏 | KPI看板、大屏展示 | | classic | 商务经典 | 暖色调、稳重典雅 | 正式汇报、高管报告 |

支持的图表类型

bar line pie stacked_bar area scatter heatmap radar funnel gauge

详见 references/chart_selection_guide.md

格式化规范

详见 references/format_standards.md

关键规则：

字体：Microsoft YaHei（微软雅黑）
百分比：保留2位小数
金额：¥ + 千分位分隔
涨 = 红色 #dc3545，跌 = 绿色 #28a745（中国股市惯例）
正增长率：+前缀 + 红色；负增长率：-前缀 + 绿色

依赖

Python 3.8+
openpyxl（Excel读写）
Pillow（颜色提取，可选）

安装：pip install openpyxl Pillow

生成的 HTML 依赖 CDN（无需安装）：

ECharts 5.5（图表渲染）
html2canvas 1.4（截图导出）

能力边界

使用本 skill 前请了解以下限制，避免踩坑：

文件大小：最大 50MB，超过 20MB 给出性能警告。行数 >50000 不建议使用
Excel 多 sheet：仅读取第一个工作表，其他 sheet 会被忽略
CSV 编码：优先 UTF-8，但内置 GBK/GB2312/GB18030 自动检测
图表数量：自动模式最多 4 个图表、6 个 KPI、50 个筛选选项
CDN 依赖：生成的 HTML 依赖 jsdelivr CDN（ECharts + html2canvas），离线不可用
数据修改：HTML 中的可编辑文字仅在当前浏览器会话有效，刷新丢失
截图限制：部分 CSS 效果（如 backdrop-filter）截图会丢失

完整边界说明和已知限制见 references/limitations_and_faq.md

故障排除

遇到错误时，脚本会输出带有错误码的友好提示，包含具体原因和修复建议。常见错误码：

| 错误码 | 含义 | |--------|------| | FILE_NOT_FOUND | 数据文件路径错误 | | UNSUPPORTED_FORMAT | 文件格式不被支持（仅 CSV/Excel） | | CSV_ENCODING_ERROR | CSV 编码无法识别，建议存为 UTF-8 | | MISSING_OPENPYXL | 缺少 openpyxl 库：pip install openpyxl | | NO_DATA_ROWS | 文件仅有表头无数据 | | INVALID_COLOR_FORMAT | 颜色值格式错误，需为 #rrggbb | | COLOR_FILE_NOT_FOUND | 颜色方案文件不存在 | | CONFIG_NOT_FOUND | 配置文件路径错误 |

使用 --verbose（或 -v）参数可查看当前使用的完整配置摘要，帮助确认参数是否正确生效。

完整 FAQ 见 references/limitations_and_faq.md

HTML 报表特性

生成的 HTML 自带以下交互功能：

模板切换：工具栏按钮，3套模板即时切换
一键截图：工具栏按钮，导出全页 PNG
中英文切换：工具栏按钮，全部界面文字切换
文字可编辑：点击标题/标签直接修改（contentEditable）
筛选联动：时间范围选择器 + 下拉多选，联动所有图表
响应式：适配桌面和移动端
动效：卡片入场动画、图表弹性动画、KPI 渐入
提示框：悬停显示详细数据（格式化后）