bi-report-generation

将分析结论和数据文件转化为读者友好的 HTML 报告。支持单主题和多主题场景。

报告生成遵循三个核心原则：

• 准确：报告中的所有数字和结论必须来自分析产出的数据文件，不得编造或推测数据
• 紧凑：充分利用页面空间，优先将数据块并排布局，减少纵向滚动
• 高密度：每张卡片尽量承载多个相关结论，避免一个指标独占一张卡片

前置检查

开始前确认以下事项已就绪，任一缺失应先完成前置分析流程：

• 分析主题明确（可能包含多个子主题）
• 各主题的分析步骤已执行完毕，结论已产出
• 支撑结论的数据文件已生成且可访问

执行步骤

1：展示布局规划

基于已完成的分析过程，梳理各主题涉及的关键指标、分析维度和数据特征，为每个主题规划展示形式：

1. 根据分析路径选择展示方式：每个主题的第一张卡片必须是数据概况卡，展示核心指标整体情况作为背景，再按分析路径展开后续内容：

   分析路径	展示方式
   基础数据观测	KPI 卡展示核心数字，表格/图表展示数据细节
   下钻/拆解/归因	按照「现象 → 归因 → 数据佐证」展示完整分析路径
   归因类分析（含外部事件）	数据概况卡 → 按关键数据点或异常区间分块，每块附触发原因 + 具体动作描述的归因列表

2. 选择图表类型：按 references/layout-spec.md §1 中的图表类型表匹配，命中即停；标注"✦ 支持切换"的场景需同时生成图表和表格视图（详见步骤 3）。

3. 列出每个主题需要读取的数据文件。

4. 多主题场景下，额外确定报告的总标题（概括报告整体范围）和总摘要（提炼各主题核心结论，形成跨主题的综合性洞察，将放在报告顶部的摘要区块）。

对每个主题，依次执行步骤 2 和步骤 3：

2：数据准备

根据步骤 1 确定的文件列表，读取该主题所需数据：

1. 读取数据文件
2. 列筛选：数据表可能包含与当前主题不直接相关的列，只保留相关列用于展示，剔除无关列

3：生成 HTML 卡片

根据步骤 1 的布局规划，为该主题生成独立的 HTML 卡片：

• 卡片需包含标题、摘要、数据展示（表/图/KPI）、现象描述、分析解读和数据来源。

• 生成卡片时需严格遵循 references/layout-spec.md 中的排版规范。

• 图片一律用 ECharts 在 HTML 中动态绘制：从数据文件读取数值，在卡片内初始化 ECharts 实例渲染图片。禁止引用分析过程中已生成的 PNG/JPG 等静态图片（不得使用 <img> 标签嵌入图片路径、base64 或外链图片来展示图片）。

• 标注"✦ 支持切换"的场景必须实现图表/表格双视图：图表容器顶部右侧放"图表"/"表格"切换按钮，默认显示图表，点击切换到表格；表格视图数值列颜色规则与图表保持一致。

• 图表高亮重点：趋势图和折线图必须用 markPoint / markLine 标注关键数据点（异常值、大幅增长、增长停滞等），图表正下方紧跟一行小字列出具体数值和简要说明。

• 分块归因分析：归因类卡片按数据重点分块展示，每块对应一个关键数据点或异常区间，块内归因列表中每条归因需包含：触发原因 + 具体动作描述，禁止只写原因不写动作。

• 卡片写入 sections_{xxx}.json 文件（使用唯一标识区分不同报告）。每条 section 的字段说明：

  字段	类型	说明
  title	string	卡片标题
  icon	string（可选）	Bootstrap Icon 类名，如 bi-graph-up-arrow
  type	string（可选）	填 "timeline" 表示时间线 section，渲染在 tab 区域外部且始终可见；不填则为普通可切换卡片
  html_fragment	string	卡片内容 HTML

  [
    {
      "title": "访问趋势分析",
      "icon": "bi-graph-up-arrow",
      "html_fragment": "<div class='bg-white rounded-xl shadow-md p-6'>...</div>"
    },
    {
      "title": "业务事件时间线",
      "type": "timeline",
      "icon": "bi-calendar-event",
      "html_fragment": "<div class='bi-timeline'>...</div>"
    }
  ]
  

• 时间线 section（可选）：如果分析过程中涉及业务事件（促销活动、模型上线、策略变更等），在所有普通卡片之后追加一条 "type": "timeline" 的 section。时间线的 html_fragment 使用以下结构：

  • 外层容器：<div class="bi-timeline">
  • 每个事件：<div class="bi-tl-item {类型class}"><div class="bi-tl-date">{日期}</div><div class="bi-tl-title">{事件名}</div><div class="bi-tl-desc">{描述}</div></div>
  • 事件类型 class：tl-major（异常/突发）、tl-promo（促销/活动）、tl-product（产品发布/功能变更）、不加 class（常规事件）
  • 事件按时间升序排列，时间线 section 不参与 tab 切换，始终在报告底部可见

4：生成完整报告

所有主题卡片生成后，调用 scripts/report_builder.py 将各 JSON 文件拼接成完整的 HTML 报告。

参数：

参数	说明
--sections	主题卡片 JSON 文件路径，支持多个（必填）
--output / -o	输出报告文件路径，HTML 格式（必填）
--report-title	报告总标题（多主题场景使用）
--overall-summary	跨主题核心结论摘要（多主题场景使用）

调用示例：

# 多主题
python scripts/report_builder.py \
    --sections sections_001.json sections_002.json \
    --output report_v1.html \
    --report-title "XXX 产品 2025 年 12 月数据分析报告" \
    --overall-summary "<p>跨主题核心结论摘要...</p>"

# 单主题（不传 report-title 和 overall-summary，让主题卡片直接展示）
python scripts/report_builder.py \
    --sections sections_001.json \
    --output report_v1.html

输出命名遵循 runtime-guide §1.5 交付物版本化：首份报告输出 report_v1.html， 报告被重做时（口径修正、用户反馈驱动、依赖数据重算）输出 report_v2.html、 report_v3.html…，不原地覆盖已有版本。步骤 5 自检失败后的修正属于同一版本内的 局部修正，可复用当前版本号。

5：生成后自检

报告生成后，必须逐项检查以下内容，任一项不通过则修正后重新生成：

布局与内容：

• 每个主题的第一张卡片为数据概况卡，展示整体指标背景
• 每个数据展示单元（图表、表格、或一组二级维度下拆数据）都配有独立的「现象」和「分析」
• 多个数据单元（图表、表格等）优先用 grid 并排展示，充分利用页面空间，避免大面积空白
• 表格宽度与列数匹配（如 2-6 列的表格不应独占全宽），具体规则见 references/layout-spec.md

图表类型：

• 转化漏斗场景使用漏斗图，各环节标注转化率和绝对流失量
• 趋势/折线图已用 markPoint / markLine 标注关键数据点，图表正下方有具体数值小字说明
• 占比场景使用饼图/环形图，超 6 类已合并为「其他」
• 多指标综合评估使用雷达图，维度已归一化
• 表格视图的数值列已按颜色标注规范渲染
• 所有图片均通过 ECharts 在页面内动态渲染，未引用任何 PNG/JPG 等静态图片文件
• 长表格保持完整，不折叠、不拆分；超过 10 行的表格用滚动容器包裹，数据完整可滚动
• 图表高度按数据点数量设置：≤5 个用 200px，6-12 个用 280px，13+ 个用 340px

归因分析：

• 归因类卡片按数据重点分块，每块对应一个关键数据点或异常区间
• 每条归因包含触发原因 + 具体动作描述，无只写原因不写动作的归因条目

时间线：

• 分析中涉及业务事件时，已在 sections.json 末尾追加 "type": "timeline" 的 section
• 时间线事件按时间升序排列，事件类型与性质匹配
• 时间线为独立 section 条目，不在普通 tab 卡片内

数据准确性：

• 所有数字来自读取的数据文件，不得编造或推测
• 每个展示区域标注数据来源链接