bi-report-generation

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>"
    }
  ]