## 仪表板构建的关键指南 * 理想情况下，不要跳过第 1 阶段（仪表板设计技能），因为这可以确保构建过程更加顺利。如果用户只想构建它，请首先解释设计阶段的价值。检查阶段 1 中是否存在任何现有的“/spec”目录。如果有，请使用它来指导您的构建。 * 使用您的本机工具来很好地理解数据，特别是当您构建自定义图表或使用特定选择器时。 * 如果用户需要示例，只需复制[示例应用程序]() 并运行它。不要包含您自己的数据或更改示例。 * 第一次执行下面提到的任何脚本时，可能需要一段时间来安装依赖项。在采取任何鲁莽行动之前要做好相应的计划。 * 完成所有步骤后在仪表板上进行迭代时，不要忘记下面的要点，特别是关于规范合规性和更新以及终端处理：始终保持所有规范最新，并始终在每次迭代后检查终端输出是否干净。 * 执行此技能中的所有脚本以及您将创建的“app.py”，使用“uv run .py”或“uv run app.py” - 这将确保您使用正确的依赖项和版本。 * **绝对不要** 在运行仪表板应用程序的终端中键入任何命令（包括 `sleep`、`echo` 或其他任何命令），即使您使用 `isBackground=true` 启动它。这将终止仪表板进程。仪表板启动需要时间 - 要有耐心并让它不受干扰地运行。 ## 规范文件：记录决策重要提示：每个步骤都会在“spec/”目录中生成一个规范文件，以记录推理、启用协作并允许在将来的会话中恢复。如果项目根目录中尚不存在“spec/”目录，则创建该目录。 ## 第 1 步：构建仪表板 1.您必须始终复制[示例应用程序]()并对其进行修改 - 这可以确保更少的错误！ 2. 通过执行架构获取脚本来调查 Vizro 模型。始终对您需要的所有模型执行此操作 - 不要假设您知道它。像这样执行脚本：“uv run ./scripts/get_model_json_schema.py ...”，其中“”是您要获取其架构的模型的名称。您可以通过调用[概述脚本]()来概述可用的内容，如下所示：`uv run ./scripts/get_overview_vizro_models.py`。这将打印出所有可用的模型及其简要说明。 3. 通过更改复制的[示例应用程序]() 来构建仪表板配置。重要提示：通常普通的情节表达图表是不够的，因为它们太简单了。在这种情况下，请参阅[自定义图表指南]()来创建更复杂的图表。这些必须添加到 python 应用程序中的正确部分。从仪表板应用程序中的“Graph”模型调用自定义图表函数。 4. 使用“uv run .py”运行仪表板应用程序 **关键**：运行此命令后，请勿在该终端中运行任何其他命令。仪表板需要一些时间才能启动（有时需要 10-30 秒） 5. 您必须读取终端以检查是否有任何错误，但不要在其中输入“sleep”等命令。修复您遇到的任何警告甚至更重要的错误。仅当您看到仪表板正在运行时，才通知用户。启动仪表板后，切勿在该终端中运行任何命令。 6. 当您迭代时，无需终止仪表板，因为我们使用的是调试模式。只需保存文件，它就会自动重新加载。偶尔检查终端是否有任何故障。一旦失败，需要重新启动仪表板。 ### 优化和常见错误 * **颜色** ：始终尊重设计阶段的颜色决定（`spec/3_visual_design.yaml`）。使用 Vizro 调色板（“from vizro.themes import Palettes”）而不是通用的绘图色标。这在自定义图表中特别容易出错。 * **数据加载** ：对于需要数据刷新（数据库、API）或性能优化的仪表板，请参阅[数据管理指南]()了解静态数据与动态数据、缓存和最佳实践。 * **KPI 卡** ：使用 `kpi_card()` 进行简单指标，使用 `kpi_card_reference()` 进行比较。当越低越好（成本、错误）时，请使用“reverse_color=True”。切勿将“kpi_card”或“kpi_card_reference”作为自定义图表或将 KPI 卡重新构建为自定义图表，而是使用“Figure”模型中内置的“kpi_card”和“kpi_card_reference”（从“vizro.figures”导入）。仅当 KPI 卡严格不可能时才接受例外，例如动态将文本显示为 KPI 卡时。 ### 所需输出：spec/4_implementation.yaml 在继续步骤 2 之前保存此文件： #spec/4_implementation.yaml 实施：应用程序文件：<名称>.py 数据文件： - [使用的数据文件列表] data_type: static/dynamic # DataFrames 为静态，data_manager 函数为动态数据源： - 名称：[数据源名称] 类型：csv/数据库/api/函数缓存：真/假 fresh_strategy：[如果是动态的：缓存超时或刷新触发] 规范合规性： follow_specs：真/假偏差： -spec_item：[指定的内容] 实际：[实施了什么] 原因：[为什么偏差是必要的] 自定义图表： - 名称：[函数名称] 目的：[它的作用] ### 验证清单在继续步骤 2 之前，请根据规范文件进行验证： * 如果规范存在，则实现 `spec/1_information_architecture.yaml`、`spec/2_interaction_ux.yaml` 和 `spec/3_visual_design.yaml` 中的所有规范 * 您已阅读仪表板应用程序的终端输出以了解错误和警告，启动应用程序后您尚未在终端中输入任何命令 * 任何偏差都记录在“spec/4_implementation.yaml”中 ## 步骤 2：测试（可选）这需要 Playwright MCP 服务器正在运行。如果不可用，请通知用户并跳过此步骤。寻找“mcp__*playwright__*”工具。进行以下测试时，请随时返回步骤 1 修复您发现的任何问题，然后返回此处。 ### 基本测试流程 1. 导航到仪表板 URL 2. 点击浏览所有页面 3. 检查控制台是否有错误使用： playwright:browser_navigate(url="http://localhost:8050") 使用： playwright:browser_click(element="页面名称", ref="...") 使用：剧作家：browser_console_messages（） ### 高级测试流程 1. 截取每个页面的屏幕截图，与规格（尤其是线框图）进行比较 2. 记录任何差异需要检查的重要事项： * 折线图可读，不会因缺乏聚合而混乱 * 图表清晰易读，不会因布局而被压扁 ### 所需输出：spec/5_test_report.yaml 保存此文件以完成项目： #spec/5_test_report.yaml 测试：发射：成功：真/假网址：http://localhost:8050 错误：[] 导航： all_pages_work：真/假问题：[] 控制台：无错误：真/假发现错误：[] 屏幕截图_测试：执行：真/假已测试页面：[] 差异： - 页面：[页面名称] 问题：[视觉问题描述] 固定：真/假备注：[修正细节或未修正的原因] 满足要求：真/假仪表板就绪：真/假 ### 完成时间 * 仪表板启动没有错误，没有控制台错误 * 用户确认满足要求 * 此阶段 2 中的所有规范文件均保存在 `spec/` 目录中 ** ** ## 参考文件文件|何时阅读 ---|--- [data_management.md]() |优化：数据加载模式、静态与动态、缓存、数据库、API [custom_charts_guide.md]() |第 1 步：当plotlyexpress 不够时创建复杂的自定义图表 [example_app.py]() |第 1 步：仪表板实施的启动模板

仪表板构建

包含技能