---
name: bi-report-generation
description: 将 BI 数据分析结果组织成可视化 HTML 报告。当分析完成、需要生成报告时调用。
---
# 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 |

  ```json
  [
    {
      "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 | 跨主题核心结论摘要（多主题场景使用）     |

**调用示例**：

```bash
# 多主题
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 卡片内

**数据准确性**：

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