databricks-app-design

数据应用设计

构建能清晰传达信息并编译为真实 AppKit 代码的 Databricks 数据与 AI 应用。本技能融合了两方面的知识，并将其落实到实现中：

• 构图——展示什么、抽象到什么程度、如何布局 → references/dashboard-patterns.md
• 标记规范——让可比较的内容看起来具有可比性；使用诚实的刻度；标注情景 → references/ibcs-notation.md
• 实现——应使用的确切 AppKit 组件、钩子和设计令牌 → references/appkit-cheatsheet.md

对于包脚本和项目本地 CLI 工具，请使用父级技能的包管理器选择方式和命令占位符。

没有指出实际组件的设计建议是不完整的。始终以组件方案收尾。

何时使用 / 何时不使用

• 使用场景：为自定义代码 Databricks App（AppKit/React）设计或评审数据界面——概览/KPI 页面、报告、指标/本体页面、差异分析、图表、表格和 Genie/NL 数据界面。
• 不适用场景：创作托管式 AI/BI (Lakeview) 仪表板（→ databricks-aibi-dashboards）、通用前端（表单、身份验证、设置、营销），或脚手架搭建/构建/部署（→ databricks-apps）。**如果用户只说“创建仪表板”/“构建仪表板”（没有 app / AppKit / React / 自定义代码相关信号），则指托管式 AI/BI (Lakeview) 仪表板 → 使用 databricks-aibi-dashboards，而不是本技能。**如果请求是“添加表单”“部署这个”或“构建 Lakeview / AI-BI 仪表板”，则不应触发本技能。
• 两者的关系：databricks-apps 负责构建/运行应用；本技能负责决定数据界面应呈现的样式，以及用哪些基础组件实现。

工作流

1. 明确框架——受众、决策/问题、刷新频率、设备、主要任务。用一句话说明。
2. 确定类型——从 dashboard-patterns.md 中选择最接近的类型（静态 / 分析型 / 杂志型 / 信息图型 / 仓库型 / 嵌入式迷你型）。说明选择。
3. 构建内容——选择内容与构图模式（数据抽象、元信息、布局、交互、颜色）。明确权衡：哪些内容被汇总、隐藏、分页或设为可交互，以及原因。
4. 应用标记规范——执行 ibcs-notation.md 中相关规则：标题传达信息、情景标记（实际/PY/计划/预测）、诚实的刻度、语义颜色。若图表术语存在冲突，以 IBCS 为准（参见该文件中的冲突说明）。
5. 映射到组件——将每个元素映射到确实由 @databricks/appkit / @databricks/appkit-ui 导出的基础组件（参见 appkit-cheatsheet.md）；绝不要引用 AppKit 未提供的组件。AppKit 没有预构建的 KPI/趋势/分布卡片——请遵循标记规范，使用基础组件组合实现。使用 colorPalette + 语义令牌，绝不硬编码十六进制颜色。使用 useAnalyticsQuery/queryKey + sql.* 参数绑定数据。
6. 覆盖各类状态——每个数据视图都必须处理加载 / 空 / 错误 / 部分数据状态（参见检查清单）。
7. 评审——运行两个参考文件中的检查清单；在评审意见开头指出影响理解或数据完整性最大的优先问题，并注明受影响的组件/文件。

必需状态与真实数据处理（数据应用不可妥协的要求）

• 加载中 → Skeleton；空状态 → Empty，并提供有用的后续操作；错误 → 显示行内消息，绝不能留下空白面板；部分数据/数据过时 → 显示已有内容 + 数据新鲜度说明。
• 每个 KPI 都要显示单位 + 时段 + 对比 + 数据新鲜度/来源（与指标定义保持一致；不要显示没有来源依据的数字）。
• 大型表格 → 使用服务端分页/排序/筛选，而不是在客户端处理超大结果集。
• 长时间运行的查询 → 提供乐观式加载 + 超时/错误体验。

AI / Genie 界面（“AI”部分）

**适用条件：**仅当应用包含 Genie / 聊天 / 自然语言 /“询问数据”界面时，才适用本节。对于没有对话输入的纯仪表板 / KPI / 报告应用，**跳过本节以及 references/genie-ai-trust.md。**若本节适用，则必须实现全部五项（代码见 references/genie-ai-trust.md）： 只有当用户能看到回答是如何生成的，以及它以谁的身份运行时，Genie/聊天/NL 回答才值得信任。“使用 GenieChat + 加载动画”远远不够——对于任何 Genie/聊天界面，都必须实现全部五项（从参考文件中准确复制代码片段）：

1. 身份 — 添加 /api/whoami 路由（使用真实的 x-forwarded-email/x-forwarded-user 标头），并通过 Badge 显示已登录用户。只有在接入 user_api_scopes: [dashboards.genie] 时，才能声称使用 OBO；否则应说明查询以应用的服务主体身份运行。
2. 生成的 SQL — 在可检查的“生成的 SQL” Card 中呈现 attachments[].query；绝不能隐藏回答的计算方式。
3. 流式传输/状态 — 反映 useGenieChat().status（streaming/error），绝不能只显示静止的加载动画。
4. 免责声明 — 每个回答都应附带一条持续显示的“AI 生成 — 请核实”提示。
5. 治理 + 状态 — 配置 genie() 空间 + 如实说明执行身份（用户范围时为 OBO，否则为服务主体）+ 处理空 / 错误 / 模糊状态（Empty、Alert）。

输出格式

设计提案：

## Direction
[Genre, audience, primary task, design intent.]
## Pattern & notation choices
- Composition: [data info, meta info, layout, interaction, color]
- Notation: [message, scenario marks, scales, semantic color]
## Component plan        ← the part that makes it buildable
- [element] → [AppKit component] (queryKey/props), [token/palette], states handled
## Tradeoffs & risks
[What's summarized/hidden/paginated/interactive; overload, scale, a11y, maintenance risks.]

**评审：**开篇指出最主要的理解 / 完整性问题，并注明对应的组件/文件，然后按影响程度列出发现，每项都要给出具体修复方法（需更改哪个组件/令牌/状态）。

反模式

• 产出没有组件规划的设计备忘录。
• 只说“使用语义颜色”，却不指出具体令牌/调色板。
• 指定 AppKit 未导出的组件（例如预制的 KpiCard）——应改用已发布的基础组件组合复合组件。
• 添加任务不需要的交互、页面或信息密度（对以模拟数据优先的应用过度设计）。
• 忽略加载/空/错误状态，或添加没有时效性/来源说明的 KPI。