dashboard-build

前提条件

需要 dashboard-design 技能提供的第 1 阶段规范文件：spec/1_information_architecture.md、spec/2_interaction_ux.md 和 spec/3_visual_design.md。如果这些文件不存在，请询问用户是先运行第 1 阶段，还是在没有规范文件的情况下继续。

指南

• 使用原生工具充分了解数据，尤其是在构建自定义图表或使用特定选择器时。
• 如果用户要求提供示例，只需复制示例应用并运行。不要加入自己的数据，也不要修改示例。
• 首次执行下文提到的任何脚本时，安装依赖可能需要一些时间。请做好相应安排，不要贸然采取行动。
• 完成所有步骤后迭代仪表板时，别忘了下文提到的要点，尤其是规范合规性、更新和终端处理方面：始终保持所有规范文件为最新，并在每次迭代后检查终端输出是否干净。
• 使用 uv run <script_name>.py 或 uv run app.py 执行此技能中的所有脚本以及你将创建的 app.py，以确保使用正确的依赖和版本。
• 绝对不要在运行仪表板应用的终端中输入任何命令（包括 sleep、echo 或其他任何命令），即使你以 isBackground=true 启动了该应用。这样会导致仪表板进程终止。仪表板启动需要时间，请耐心等待，不要干扰其运行。
• 第 2 步（测试）至关重要，切勿跳过。如果可用，请使用 Playwright MCP；否则，请使用环境中的任何浏览器自动化工具。

规范文件：记录决策

重要：每个步骤都会在 spec/ 目录中生成一个规范文件，用于记录推理过程、促进协作，并支持在未来会话中继续工作。如果项目根目录下尚无 spec/ 目录，请创建该目录。

第 1 步：构建仪表板

1. 必须始终复制示例应用，并在其基础上修改，以减少错误！
2. 通过执行架构获取脚本调查 Vizro 模型。对于需要使用的所有模型，必须始终执行此操作——不要自以为了解其架构。按如下方式执行脚本：uv run ./scripts/get_model_json_schema.py <model_name> <model_name2> ...，其中 <model_name> 是你想获取架构的模型名称（会将每个模型的完整 JSON 架构打印到 stdout）。你可以按如下方式调用概览脚本，了解可用模型：uv run ./scripts/get_overview_vizro_models.py（会将所有可用模型名称及其单行说明打印到 stdout）。
3. 修改复制的示例应用，构建仪表板配置。重要提示：普通的 Plotly Express 图表通常不够用，因为它们过于简单。在这种情况下，请参考自定义图表指南，创建更复杂的图表。这些图表必须添加到 Python 应用的正确部分。在仪表板应用中，通过 Graph 模型调用自定义图表函数。
4. 使用 uv run <your_dashboard_app>.py 运行仪表板应用。关键：运行此命令后，不要在该终端中运行任何其他命令。仪表板启动需要一些时间（有时需要 10-30 秒）。
5. 必须查看终端，检查是否有任何错误，但不要在其中输入 sleep 之类的命令。修复遇到的所有警告，尤其是错误。只有在确认仪表板已运行后，才能告知用户。启动仪表板后，绝不要在该终端中运行任何命令。
6. 进行迭代时，无需停止仪表板，因为我们使用的是调试模式。只需保存文件，它就会自动重新加载。偶尔检查终端，确认没有失败。如果运行失败，则需要重启仪表板。

优化和常见错误

• 颜色：对于 Plotly 图表和 KPI 卡片，不要在代码中添加颜色——Vizro 模板默认值会自动生效。只有当 spec/3_visual_design.md 中明确包含 ## Colors 章节时，才添加图表颜色。对于 AG Grid 单元格样式（条件格式、热力图），请使用 from vizro.themes import palettes, colors——切勿自行编造十六进制颜色值。请参阅 selecting-vizro-charts 技能。
• 数据加载：对于需要刷新数据（数据库、API）或进行性能优化的仪表板，请参阅数据管理指南，了解静态与动态数据、缓存和最佳实践。
• KPI 卡片：仅在 Figure 模型中使用内置的 kpi_card / kpi_card_reference。切勿将其重建为自定义图表（动态文本除外）。请参阅 selecting-vizro-charts 技能。
• 表格：仅使用带有 figure=dash_ag_grid(...) 的 vm.AgGrid。切勿使用 vm.Table / Dash DataTable，也切勿用 Plotly 伪造表格。有关两种规范模式以及 Dash-AG-Grid / JS-AG-Grid 知识映射，请参阅 example_ag_grid.py。
• 交互 / 操作：如需交叉筛选、交叉高亮、下钻或导出数据，请加载 wiring-vizro-actions 技能，并遵循 spec/2_interaction_ux.md 中的 ## Interactions 章节。

必需输出：spec/4_implementation.md

将 assets/4_implementation.md 中的模板复制到项目根目录下的 spec/4_implementation.md，填写占位符并保存，然后再继续执行步骤 2。

验证清单

继续执行步骤 2 之前，请根据规范文件进行核验：

• 如果存在规范文件，已实现 spec/1_information_architecture.md、spec/2_interaction_ux.md 和 spec/3_visual_design.md 中的所有规范
• 已阅读仪表板应用的终端输出，检查错误和警告；启动应用后未在终端中执行任何命令
• 已在 spec/4_implementation.md 中记录所有偏差

步骤 2：测试

此步骤对于生成无错误的仪表板至关重要。请勿跳过。

进行以下测试时，如果发现问题，请返回步骤 1 进行修复，然后再回到此处。

自动化代码验证

针对 app.py 运行以下验证脚本，以发现常见问题：

1. 颜色验证：uv run ./scripts/validate_colors.py .——检查是否存在绕过 Vizro 主题的硬编码颜色（color_discrete_map、十六进制代码、plot_bgcolor）。修复所有 FAIL。如果用户明确要求使用自定义颜色，请添加 --custom-colors-requested，跳过对 app.py 的颜色检查。
2. 聚合验证：uv run ./scripts/validate_aggregation.py .——检查柱状图 / 折线图是否通过 @capture("graph") 使用预聚合数据，而不是将原始明细行传入内联 px.bar / px.line。修复所有 FAIL。

浏览器测试

在运行中的仪表板中导航，以发现仅靠代码审查无法发现的问题：（1）启动时的控制台错误，（2）页面导航时的回调错误，以及（3）触发操作时出现的回调 500 错误——这些错误只有在用户实际点击交互式来源时才会出现，页面加载时不会出现。

1. 确定有哪些浏览器自动化工具可用：

   是否有 Playwright MCP 工具？ → 直接使用它们进行导航、点击页面并检查控制台。没有 Playwright MCP？ → 安装 Python 软件包，然后编写测试脚本。使用 uv pip install playwright && uv run playwright install --with-deps chromium——--with-deps 标志会安装 Chromium 所需的操作系统库；在精简 Linux 基础镜像（Docker、CI 运行器、开发容器）中，普通安装会因缺少共享库而无法启动，因此必须使用此标志。在 macOS/Windows 上使用也安全。如果磁盘上已经有 Chromium，则跳过安装——它的下载大小约为 170 MB。

2. 方法——批量处理错误，不要逐个循环处理。 遍历每个页面并在一轮中测试每个操作，将所有错误（控制台错误、网络 500 错误、回调失败、仪表板进程输出中的服务器回溯）收集到一个列表中。然后一次性修复所有错误，只重启仪表板一次，再重新遍历。要避免这样的陷阱：发现一个错误 → 修复 → 重启 → 发现下一个错误 → 修复 → 重启。每次重启都要花费约 30–60 秒，在仪表板完全正常之前，你的时间预算就会耗尽。

3. 使用选定的工具，在一轮遍历中完成以下检查：

   • 导航到仪表板 URL（例如，http://localhost:8050）。
   • 访问每个页面并读取浏览器控制台中的错误。不要遇到第一个错误就停下来——记录错误并继续检查。
   • 如果 app.py 中包含任何 actions=（交叉筛选、交叉高亮、下钻、导出），则在同一轮遍历中逐一测试：在应用中搜索 actions=，对于每处匹配项，点击相应的来源（散点图上的点、柱、AgGrid 中的行、导出 Button 等）。针对每项操作，记录：
     • 浏览器控制台中的任何 Callback error updating ... 消息，
     • _dash-update-component 上是否有任何网络 500 响应，
     • 操作预期的效果是否确实发生（show_in_url=True 时 URL 是否更新、目标筛选器是否变化、高亮是否应用、文件是否下载等）。
   • 另请检查仪表板进程输出（启动 app.py 的终端）中是否有服务器端回溯——当浏览器只显示通用回调错误时，这些回溯可以揭示根本原因。
   • 将收集到的故障分组，一次性修复所有问题，然后重启并重新执行此轮遍历。只有出现新错误时才重复。

高级测试流程

1. 为每个页面截屏，并与规格（尤其是线框图）进行比较
2. 记录所有差异

需要检查的重要事项：

• 折线图清晰易读，不会因缺少聚合而显得杂乱
• 图表清晰可读，不会因布局问题而被挤扁

必须的输出：spec/5_test_report.md

将 assets/5_test_report.md 中的模板复制到项目根目录下的 spec/5_test_report.md，填写占位内容并保存，以完成项目。

完成条件

• 验证脚本（validate_colors.py、validate_aggregation.py）均通过
• 仪表板启动时无错误，控制台无错误，页面导航时无回调错误
• 已在浏览器中点击 app.py 中的每个 actions=，并且都按预期生效且没有回调 500 错误
• 用户确认需求已满足
• 第 2 阶段的所有规格文件均已保存到 spec/ 目录中

参考文件

参考内容	加载时机
selecting-vizro-charts 技能	颜色、KPI 卡片、自定义图表、Plotly 约定
writing-vizro-yaml 技能	YAML 语法、组件模式、data_manager、注意事项
wiring-vizro-actions 技能	交叉筛选、交叉高亮、下钻、导出
data_management.md	静态与动态数据、缓存、数据库、API
custom_charts_guide.md	实现自定义 @capture("graph") 图表
example_app.py	仪表板实现的起始模板
example_ag_grid.py	标准 AG Grid 模式——编写任何 vm.AgGrid 之前都要阅读
validate_colors.py	自动检查 app.py 中的硬编码颜色
validate_aggregation.py	自动检查条形图/折线图中的预聚合