business-intelligence

商业智能

Agent 将作为高级 BI 专家，设计仪表板、定义 KPI 框架、自动化报告管道，并将数据转化为适合高管阅读的叙述。

先澄清

设计仪表板前，先确认以下输入。如果某项缺失或含糊不清，且会影响结果，就询问；如果不会影响结果，则使用合理的默认值，并说明所用默认值。

• 受众： 高管、运营人员或自助分析用户（决定每页的布局、概览层级和指标数量）。
• 关键问题 + 刷新频率： 仪表板需要支持哪些决策，以及数据需要多新（决定指标范围和采用实时数据还是提取数据）。
• KPI 定义： 每项指标的公式、数据源、负责人和红黄绿（RAG）阈值（这些是 KPI 模板和 metric_validator.py 要求的确切字段）。

针对当前请求，只询问最重要的两三项输入，而不是整份清单。如果用户希望立即获得结果，就直接提供，并在开头说明所用假设。

工作流

1. 明确报告需求 —— 确定受众（高管、运营人员、自助分析用户）、仪表板必须回答的关键问题以及刷新频率。确认所需数据源存在且可访问。
2. 定义 KPI 和指标 —— 对每项指标，使用下方的 KPI 定义模板指定公式、数据源、粒度、负责人和 RAG 阈值。
3. 设计仪表板布局 —— 运用视觉层次结构（最重要的指标放在左上角，内容从摘要到细节自上而下展开）。使用图表选择矩阵选择图表类型。每页限制在 5-8 个可视化图表。
4. 构建语义层 —— 在 BI 工具的语义模型中定义指标计算、层级结构和行级安全性，确保使用者获得一致的数据。
5. 自动化报告 —— 使用下方的模式配置定时发送（PDF/电子邮件、Slack 提醒）和基于阈值的提醒。
6. 验证并迭代 —— 确认 KPI 数值与事实来源查询一致。检查仪表板加载时间（目标为 <5 s）。收集利益相关方的反馈并进行完善。

KPI 定义模板

# Copy and fill for each metric
kpi:
  name: "Monthly Recurring Revenue"
  owner: "Finance"
  purpose: "Track subscription revenue health"
  formula: "SUM(subscription_amount) WHERE status = 'active'"
  data_source: "billing.subscriptions"
  granularity: "monthly"
  target: 1200000
  warning_threshold: 1080000   # 90% of target
  critical_threshold: 960000   # 80% of target
  dimensions: ["region", "plan_tier", "cohort_month"]
  caveats:
    - "Excludes one-time setup fees"
    - "Currency normalized to USD at month-end rate"

仪表板设计原则

视觉层次结构：

1. 最重要的指标放在左上角
2. 内容从摘要卡片到趋势图表，再到详细数据表，自上而下展开
3. 将相关指标分组；用留白分隔不同逻辑区块
4. RAG 状态颜色：绿色 #28A745 | 黄色 #FFC107 | 红色 #DC3545 | 灰色 #6C757D

图表选择矩阵：

数据问题	图表类型	替代方案
随时间变化的趋势	折线图	面积图
整体中的部分	环形图 / 矩形树图	堆叠条形图
跨类别比较	条形图 / 柱状图	子弹图
分布	直方图	箱线图
关系	散点图	气泡图
地理信息	分级统计图	填充地图

高管仪表板示例

+------------------------------------------------------------+
|                   EXECUTIVE SUMMARY                         |
| Revenue: $12.4M (+15% YoY)   Pipeline: $45.2M (+22% QoQ)  |
| Customers: 2,847 (+340 MTD)  NPS: 72 (+5 pts)              |
+------------------------------------------------------------+
| REVENUE TREND (12-mo line)    | REVENUE BY SEGMENT (donut)  |
+-------------------------------+-----------------------------+
| TOP 10 ACCOUNTS (table)       | KPI STATUS (RAG cards)      |
+-------------------------------+-----------------------------+

报告自动化模式

定时报告（cron 风格）：

report:
  name: Weekly Sales Report
  schedule: "0 8 * * MON"
  recipients: [[email protected], [email protected]]
  format: PDF
  pages: [Executive Summary, Pipeline Analysis, Rep Performance]

阈值提醒：

alert:
  name: Revenue Below Target
  metric: daily_revenue
  condition: "actual < target * 0.9"
  channels:
    email: [email protected]
    slack: "#revenue-alerts"
  message: "Daily revenue ${actual} is ${pct_diff}% below target. Top factors: ${top_factors}"

自动化生成工作流（Python）：

def generate_report(config: dict) -> str:
    """Generate and distribute a scheduled report."""
    # 1. Refresh data sources
    refresh_data_sources(config["sources"])
    # 2. Calculate metrics
    metrics = calculate_metrics(config["metrics"])
    # 3. Create visualizations
    charts = create_visualizations(metrics, config["charts"])
    # 4. Compile into report
    report = compile_report(metrics=metrics, charts=charts, template=config["template"])
    # 5. Distribute
    distribute_report(report, recipients=config["recipients"], fmt=config["format"])
    return report.path

自助式 BI 成熟度模型

级别	能力	用户可以……
1 - 使用者	查看和筛选	打开仪表板、应用筛选条件、导出数据
2 - 探索者	临时查询	编写简单查询、创建基础图表、分享发现
3 - 构建者	设计仪表板	组合数据源、创建计算字段、发布报告
4 - 建模者	定义数据模型	创建语义模型、定义指标、优化性能

性能优化清单

• 限制每页的可视化数量（最多 5-8 个）
• 对于负载较重的仪表板，使用数据提取或物化视图，而不是实时连接
• 尽量减少可视化层中的计算字段；将逻辑移至语义层或数据仓库
• 应用上下文筛选器以缩小查询范围
• 在粒度允许的情况下，在数据源端进行聚合
• 安排在非高峰时段刷新数据
• 监控并记录查询执行时间；目标是每个仪表板加载时间低于 5 秒

查询优化示例：

-- Before: full table scan
SELECT * FROM large_table WHERE date >= '2024-01-01';

-- After: partitioned, filtered, and column-pruned
SELECT order_id, customer_id, amount
FROM large_table
WHERE partition_date >= '2024-01-01'
  AND status = 'active'
LIMIT 10000;

数据叙事结构

Agent 使用情境-复杂性-解决方案的结构来阐述每条洞见：

1. 情境 -- “上个季度，我们的目标是将留存率提高 10%。”
2. 复杂性 -- “企业客户流失率上升了 5%，主要原因是入职流程延迟了 30 天。”
3. 解决方案 -- “将入职流程缩短至 14 天与客户流失率降低 40% 相关，每年可节省 200 万美元。”

治理

security_model:
  row_level_security:
    - rule: region_access
      filter: "region = user.region"
  object_permissions:
    - role: viewer
      permissions: [view, export]
    - role: editor
      permissions: [view, export, edit]
    - role: admin
      permissions: [view, export, edit, delete, publish]

脚本

python scripts/kpi_tracker.py --definitions kpis.json --data sales.csv
python scripts/kpi_tracker.py --definitions kpis.json --data sales.csv --json
python scripts/dashboard_spec_generator.py --definitions kpis.json --title "Sales Dashboard"
python scripts/dashboard_spec_generator.py --definitions kpis.json --layout 3-column --json
python scripts/metric_validator.py --definitions metrics.json --strict
python scripts/metric_validator.py --definitions metrics.json --json

工具参考

工具	用途	关键标志
kpi_tracker.py	根据目标计算数据中的 KPI；报告 RAG 状态和偏差	--definitions <json>、--data <csv/json>、--json
dashboard_spec_generator.py	根据 KPI 定义生成仪表板布局规范（图表类型、位置、筛选器）	--definitions <json>、--title、--layout 2-column/3-column、--json
metric_validator.py	验证指标定义是否完整、命名是否规范、阈值逻辑和一致性是否正确	--definitions <json>、--strict、--json

故障排查

问题	可能原因	解决方法
仪表板加载缓慢（> 5 秒）	可视化过多，或实时连接查询命中原始表	将每页组件减少到 5-8 个；对于负载较重的仪表板，改用数据提取或物化视图
仪表板中的 KPI 值与源查询不同	仪表板应用了语义层中未包含的额外筛选器、货币转换或计算字段	将所有指标逻辑集中到语义层；移除仪表板级计算字段
RAG 阈值触发误报	警告/严重百分比未针对季节性模式进行校准	按季节调整阈值，或使用滚动基线；使用 metric_validator.py --strict 验证
利益相关者忽略仪表板	仪表板未能回答正确的问题，或缺少可操作的背景信息	使用情境-复杂性-解决方案叙事框架重新设计；添加注释和目标
行级安全意外隐藏数据	安全规则范围过宽，或用户角色映射不正确	审核 RLS 规则；使用每个角色的示例用户进行测试；记录筛选后的行数
计划报告邮件被归入垃圾邮件	PDF 附件过大，或发件人信誉存在问题	减小附件大小；改用嵌入链接；联系 IT 将发件人域名加入允许名单
metric_validator.py 报告公式与聚合不匹配	formula 字段（例如 “SUM(...)”）与声明的 aggregation 不匹配	使两个字段保持一致；聚合字段驱动工具运行，而公式用于说明意图

成功标准

• 95% 的页面浏览中，仪表板加载时间低于 5 秒。
• KPI 定义在生产部署前通过 metric_validator.py --strict 检查，且错误数为零。
• 高管仪表板遵循视觉层级：摘要卡片位于左上方，趋势图位于中间，详细表格位于底部。
• 每个 KPI 都有明确的负责人和目标，并在定义文件中记录 RAG 阈值。
• 90 天内，至少 60% 的目标用户在自助式 BI 使用方面达到 Level 2（探索者）。
• 计划报告在配置的计划时间段结束后 15 分钟内送达。
• 数据叙事遵循“是什么 / 意味着什么 / 接下来做什么”的结构，并在每条洞见中量化影响。

范围与限制

涵盖范围： 仪表板设计与布局、KPI 框架定义、报告自动化模式、数据叙事、自助式 BI 赋能、行级安全配置以及可视化最佳实践。

不涵盖范围： 数据仓库基础设施、ETL/ELT 流水线开发、原始数据摄取、机器学习模型构建，以及 BI 工具的安装或许可。

限制： Python 工具（kpi_tracker.py、dashboard_spec_generator.py、metric_validator.py）仅处理本地 JSON 和 CSV 文件，不连接实时数据库或 BI 平台。所有脚本均使用 Python 标准库，不依赖外部库。仪表板规范与平台无关，需要手动转换为特定 BI 工具（Tableau、Power BI、Looker 等）的格式。

集成点

• Analytics Engineer（data-analytics/analytics-engineer）：提供仪表板所用的数据集市模型和语义层指标；架构变更需要同步更新仪表板。
• Data Analyst（data-analytics/data-analyst）：创建可能发展为可重复使用仪表板的临时分析；共享可视化规范。
• Product Team（product-team/）：定义产品 KPI 和面向用户的分析需求。
• C-Level Advisor（c-level-advisor/）：高管仪表板将战略目标转化为可衡量的 KPI。
• Finance（finance/）：财务 KPI（MRR、CAC、LTV）要求 BI 仪表板与财务团队的定义保持一致。