review-report

审查 Power BI 报表

对 Power BI 报表进行结构化评估，为开发人员和顾问提供可执行的反馈。报表审查会评估报表是否有效、构建是否完善，以及是否真正有人使用。输出结果是一份按优先级排列的发现清单，并附有具体建议。

请注意，此技能适用于以下三种场景之一：

1. 开发中的报表：此场景更关注报表内容、结构、组织方式和性能，并以准确收集的需求为依据。
2. 测试中的报表：此场景可能会结合用户反馈，或检查 Power BI / Fabric 中已部署报表的基本信息。
3. 使用中的报表：这是理想场景，重点在于使用情况；成功的最终定义是报表是否有人使用、有权访问报表的人中有多少百分比在过去 28 天内访问过报表，以及访问频率如何。效果不佳的报表无人使用，或者使用率会下降。

在场景 2-3 中，你仍然可以对报表内容 / 结构提供反馈，但应优先处理其他事项。

适用场景

在进行报表审查、审计或健康检查时启用。常见触发条件：

• 在发布或交接前审查报表质量
• 评估现有报表是否值得维护
• 识别工作区中的优化机会
• 评估报表设计和数据呈现效果
• 调查报表性能问题

审查维度

全面的报表审查会评估六个维度。并非每次审查都需要涵盖全部六个维度——根据用户需求确定范围。

1. 使用情况与采用情况

衡量报告价值最客观的信号。 无论设计质量如何，没人查看的报告都会成为维护负担。

使用 scripts/ 中的脚本获取使用数据：

# Workspace overview (views, rank, page views, load times)
python3 scripts/get_report_usage.py -w <workspace-id>

# Add Tier 3 cross-workspace last-visited timestamps via the undocumented DataHub V2 API
# Useful for the "is this report being used at all" question without tenant admin role
python3 scripts/get_report_usage.py -w <workspace-id> --include-datahub

# Single report deep-dive (daily views, per-viewer breakdown, page views by day)
python3 scripts/get_report_detail.py -w <workspace-id> -r <report-id>

# Distribution audit (who has access, through what channels)
python3 scripts/get_report_distribution.py -w <workspace-id> -r <report-id>

筛选查看者： 从采用情况指标中排除非使用者。服务主体（类型为 App）、报告开发人员以及 IT／支持人员会抬高查看者数量并扭曲覆盖范围。查看 references/usage-metrics.md，了解识别方法；查看 references/distribution.md，了解如何通过 Microsoft Graph API 解析安全组和通讯组列表。

评估使用情况信号：

• 受众覆盖率是最重要的指标：在过去 7、28 和 60 天内，有权限的用户中实际查看过报告的比例是多少？查看 references/distribution.md，了解如何计算覆盖率以及如何解读数据
• 查看趋势： 查看量是稳定、增长还是下降？使用滚动 7D 平均值（参见 references/usage-metrics.md）
• 页面查看分布： 查看是否集中在某个页面，还是分散在整个报告中？认定某个页面未使用前，请先确认它是否是工具提示／钻取目标（这类页面通常不会被直接查看），并通过 pbir pages list 确认是否可访问
• 最后访问时间： 最近一次有人访问报告是什么时候？Tier 1（Admin Activity Events，滚动 30 天，需要管理员角色）是官方途径。Tier 3 DataHub V2 的 lastVisitedTimeUTC 字段（--include-datahub）是跨工作区的非管理员备用方案；请告知用户该字段未有文档说明，且可能失效
• 加载时间： P50 和 P90 加载时间是否符合受众预期？查看 references/performance.md，了解如何解读

不要使用随意设定的阈值来判断是否“健康”或“值得关注”；这完全取决于报告的受众、用途和生命周期阶段。面向 3 位分析师的报告与面向 300 位高管的报告，预期有所不同。得出结论前，应使审查窗口与报告的更新频率相匹配；查看 references/usage-interpretation.md，了解对新版 Usage Metrics 报告的常见误读，以及停用／保留／重新设计的决策框架。

订阅不等于查看。 电子邮件订阅会发送报告快照，但不会生成查看事件。检查 admin/reports/{id}/subscriptions（需要 Fabric Admin），查看有效订阅者。查看次数为 0 但存在有效订阅的报告，说明有人在被动使用。

使用滚动 7 天平均值分析查看趋势。每日原始计数波动较大。将当前 7D 平均值与前一个 7D 平均值进行比较，以判断趋势。查看 references/usage-metrics.md，了解计算方法。

关键见解： 查看次数为 0 并不一定代表报告不好。报告可能刚发布、具有季节性、通过订阅使用，或用于遥测未捕获的嵌入式场景。请结合最后访问时间戳进行核对。如果可以使用管理员权限，请优先采用 Tier 1 管理员 Activity Events 数据流；否则可使用 Tier 3 DataHub V2 方案，但要说明该方案未有文档说明。

权限： Tier 1（WABI）需要任意工作区角色。Tier 2（模型）需要工作区 Contributor 或更高角色。检查分发和订阅需要 Fabric Admin（租户级权限）。完整权限矩阵见 references/usage-metrics.md。

如需进一步了解使用情况指标数据集的架构和可用表，请参阅 usage-metrics-dataset/。

2. 设计与布局

评估视觉设计和信息架构。请参阅 pbi-report-design 技能，了解详细指南。参考：Data Goblins 报告检查清单。

检查清单：

• 页面标题清晰且具有描述性
• 视觉元素间距一致（视觉元素之间及页边距之间的间隔相等）
• 遵循细节渐进原则（关键绩效指标位于左上方，详细信息位于右下方）
• 有意且无障碍地使用颜色（不滥用颜色，也不为色盲用户使用红色和绿色）
• 字体、字号和格式在整个报告中保持一致
• 视觉元素数量合理（每页大致最多 12–15 个，具体取决于复杂程度）
• 没有空白视觉元素（所有视觉元素都已绑定字段）
• 已应用主题（不是默认 Power BI 主题）
• 图表坐标轴从零开始（除非有意采用其他起点）
• 所有视觉元素均已配置默认排序
• 选择窗格中的视觉对象已清晰标注（分组并使用描述性名称）
• 面向相关受众时，已提供移动布局
• 已配置视觉对象标头（不需要向下钻取或钻取时应禁用）
• 已配置交互（有意设置交叉筛选／突出显示，而非使用默认设置）
• 对于性能敏感的页面，已考虑切片器的“应用”按钮
• 需要时，各页面之间已同步切片器

3. 数据模型绑定

评估报告与底层语义模型之间的连接。

检查清单：

• 报告连接到已发布的语义模型（“精简报告”），而非嵌入自己的模型（“厚报告”）
• 所有字段绑定均指向模型中现有的列／度量值
• 谨慎使用扩展度量值（精简报告度量值），且仅用于报告专属逻辑
• 没有失效或孤立的字段引用
• 在视觉对象中恰当使用度量值和列（聚合上下文）
• 视觉对象级别没有启用单独筛选器

4. 性能

评估报告加载时间和视觉复杂度。运行性能审计脚本：

python3 scripts/performance_audit.py -w <workspace-id> -r <report-id>

有关百分位数的解读、根据视觉对象字段绑定推断 DAX 查询以及常见反模式，请参阅 references/performance.md。

**关键指标：**P50 和 P90 加载时间、每页视觉对象数量、扩展度量值数量。视觉对象数量只是参考指标；每个视觉对象的查询成本才是真正的影响因素。有关完整的成本模型、如何解读 Performance Analyzer 导出文件、DirectQuery 报告层的调优手段以及交互／导航审计，请参阅 references/performance-audit.md。请先阅读成本模型，再应用严格的视觉对象数量阈值。

5. 报告元数据与治理

评估报告的治理状况。请参阅 references/report-metadata.md。

检查清单：

• 精简报告（连接到已发布的模型，而非嵌入厚模型）
• 背书状态适合其受众（生产环境使用“已认证”，团队使用“已推广”）
• 如果租户策略要求，已应用敏感度标签
• 如果位于生产工作区中，则已纳入部署管道
• 通过工作区应用或组织应用分发（而非直接链接或“发布到 Web”）
• 通过安全组授予访问权限，而非单独授予个人用户
• 消费者仅拥有查看权限（查看者角色），仅开发人员拥有编辑权限
• 已审查导出到 Excel 的使用方式是否存在数据治理风险（请参阅 references/export-to-excel.md）

6. 无障碍、标准与文档

评估报告是否符合无障碍、组织标准和文档要求。

无障碍：

大多数无障碍检查都可以针对 PBIR 文件静态执行；只有焦点遍历和屏幕阅读器播报需要实时报告。完整流程请参阅 references/accessibility-audit.md：几何布局／对齐审查、选项卡顺序核对、静态检查（替代文本、装饰性项目、仅用颜色编码）、SVG 度量值检查、脚本视觉检查和移动设备就绪情况。

检查清单摘要：

• 所有数据视觉对象均提供替代文本（包括 SVG 度量值承载对象和脚本视觉对象）
• 装饰性项目已从选项卡序列中移除（tabOrder = -1）
• 选项卡顺序符合几何阅读顺序（从上到下、从左到右）
• 不存在仅用颜色编码的情况（应搭配形状、字形或文本）
• 颜色对比度符合 WCAG 2.1 AA（文本为 4.5:1，UI 元素为 3:1）
• 字号清晰易读（数据最小 9 pt，标签最小 12 pt）
• 面向使用者的页面提供移动布局
• 已通过实时键盘 Tab 遍历验证（无法通过文件确认）

标准：

• 如治理政策有要求，已应用敏感度标签
• 遵循命名约定（报告名称、页面名称、视觉对象标题）
• 已提供供用户报告问题或提交反馈的链接
• 已全面测试筛选器组合

文档（用于交接／生产）：

• 用途说明：报告回答哪些业务问题？
• 已明确目标受众和用户细分群体
• 已记录特殊功能（视觉对象级筛选器、隐藏切片器、书签、自定义视觉对象）
• 已明确支持人员和流程
• 已备妥面向业务用户的培训／采用材料

审查工作流

步骤 1：确定范围

明确用户希望审查什么。询问：

• 审查单个报告，还是整个工作区？
• 哪些维度最重要？（使用情况、设计、性能，还是全部？）
• 是否有促使此次审查的具体问题？
• 应将发现记录在哪里？（临时记录、agent-docs、obsidian 笔记本、wiki 等）

步骤 1a：确定范围和访问权限

询问用户：

• 他们是否有权访问底层语义模型？
• 他们是报告和模型的开发者，还是只负责其中一项？

如果语义模型也在审查范围内，请并行使用 semantic-model 技能。许多报告问题（视觉对象缓慢、(Blank) 值、字段缺失）都源于模型。有关在报告中显现的模型问题，请参阅 references/best-practices.md。

步骤 1b：确定报告生命周期阶段

如果报告仅在本地使用或尚未发布，请询问用户：

"这是一份仍在开发、尚无用户的报告，一份由部分目标用户参与测试的报告，还是一份已经分发、应当已有活跃使用和价值产出的报告？"

这决定了哪些维度适用：

阶段	是否有使用数据？	审查内容
开发	否	设计、数据模型绑定、性能、无障碍、结构
测试	部分	以上全部内容 + 确认测试人员确实在进行测试（测试受众的查看数据）
生产	是	所有维度，包括完整的使用情况、分发和导出分析

提醒用户：报告的成败取决于它是否被使用并创造业务价值。可以主动审查设计、性能和结构，但使用数据是唯一能客观衡量报告是否发挥作用的指标。完善的需求收集有助于提高采用率，但无法保证一定成功。

如果报告仅在本地使用，请询问已发布版本位于何处（或将发布到何处）。使用指标需要 Power BI 服务中存在已发布的报告。

步骤 2：收集数据

运行使用情况脚本获取定量数据。导出或检查报告定义，进行定性评估。

步骤 3：评估

使用上述清单逐项检查相关维度。根据严重程度为每项发现评分：

• 严重：功能损坏、存在安全风险，或完全未使用却占用容量的报表
• 高：影响用户的性能问题、重大设计违规、缺少数据绑定
• 中：设计不一致、中等程度的性能问题、部分无障碍访问缺陷
• 低：细节润色、样式偏好、优化机会

步骤 4：报告发现

以结构化摘要的形式呈现发现。优先列出影响最大的发现。

格式：

REPORT REVIEW: <Report Name>
===============================

USAGE SIGNAL
  Views (30d): 47  |  Viewers: 8  |  Rank: #3/22
  Top pages: Overview (60%), Detail (30%), Trends (10%)
  Load time P50: 3.2s  |  P90: 7.1s

CRITICAL
  - [Performance] P90 load time exceeds 7s due to 14 visuals on Overview page

HIGH
  - [Design] No page titles on 2 of 3 pages
  - [Binding] 3 visuals have broken field references

MEDIUM
  - [Design] Inconsistent margins (24px left, 32px right)
  - [Accessibility] Missing alt text on 5 data visuals

LOW
  - [Design] Default theme applied; consider custom theme
  - [Standards] Report name uses spaces instead of hyphens

先决条件

运行使用情况脚本前，请确保：

• Azure CLI 已完成身份验证：如有需要，运行 az login
• fab CLI 已完成身份验证：如有需要，运行 fab auth login（用于分发脚本）
• 已安装 Python requests 包：uv pip install requests

参考资料

• references/usage-metrics.md —— 所有使用情况数据 API 的完整文档（官方和未公开）
• references/usage-interpretation.md —— 正确解读现代 Usage Metrics；退役／保留／重新设计决策框架
• references/distribution.md —— 所有报表访问路径及其审计方法
• scripts/get_report_usage.py —— 工作区级使用情况概览
• scripts/get_report_detail.py —— 单个报表深度分析（按日、按查看者、按页面）
• scripts/get_report_distribution.py —— 分发审计（ACL、应用、发布到 Web）
• scripts/performance_audit.py —— 加载时间和视觉复杂度分析
• references/performance.md —— 百分位数解读、根据视觉元数据推断 DAX 查询
• references/performance-audit.md —— 查询成本模型、Performance Analyzer 导出、DirectQuery 调优、交互／导航审计
• references/accessibility-audit.md —— 对齐／Tab 顺序审计、静态无障碍检查、SVG／脚本／移动设备检查
• references/report-metadata.md —— 厚／薄模型、背书、敏感度、管道、模型属性
• references/export-to-excel.md —— 导出活动分析、数据治理影响
• references/best-practices.md —— 数据可视化原则、图表选择、颜色、交互设计
• usage-metrics-dataset/ —— 导出的 Usage Metrics 数据集（TMDL 架构 + 报表定义）

相关技能

• semantic-model —— 语义模型设计与审查的配套技能（模型属于审查范围时并行运行）
• pbi-report-design —— 详细的报表设计指南和布局规则
• modifying-theme-json —— 主题编写、合规审计、格式推广
• deneb-visuals、python-visuals、r-visuals、svg-visuals —— 特定视觉对象的审查标准（现已归入 custom-visuals 插件；通过 claude plugin install custom-visuals@power-bi-agentic-development 添加）