dashboards

仪表板

仪表板由整个组织共享——没有私人仪表板，因此你添加或更改的任何内容，所有人都能看到。每个仪表板都包含按顺序排列的卡片：

字段	含义
measure	一个数值指标，需使用完整限定名称：crm_deals.amount。
segmentId	卡片统计其行数的细分，或——
filter	卡片自己的条件（细分筛选语法）。两者不可同时使用。
joinPaths	条件或分组所读取的其他每个立方体的关联路径：{ "crm_companies": "crm_deals.crm_companies" }。
breakdown	可选维度：卡片显示其排名靠前的分组，而非单个数字。
visualization	分组的显示方式：bars（默认）、columns、donut、table。没有 breakdown 时绝不要发送此字段：无论此处设置什么，没有分组的卡片都只显示一个数字。
title	显示该内容，而不是指标名称。
position	卡片在仪表板上的顺序，按升序排列。

硬性规则：没有 breakdown 时绝不要填写 visualization。 没有分组的卡片只显示一个数字，无论其 visualization 设置为何。若用户要求图表（条形图、柱状图、圆环图），却没有指定拆分字段，请询问要使用哪个字段，并在用户回答前不要写入任何内容。

卡片存储的是问题，而不是答案。如何选择指标、确定范围并计算其值，属于指标技能——添加卡片或报告卡片内容前，请先阅读该技能。

调用工具

// Dashboards
api_read   { "resource": "dashboards", "params": { "fields": "id,name,description" } }
api_write  { "resource": "dashboards", "data": { "name": "Sales", "description": "…" } }
api_write  { "resource": "dashboards", "id": "<dashboard id>", "data": { "name": "…" } }
api_delete { "resource": "dashboards", "id": "<dashboard id>" }

// Cards — flat, not under the dashboard: list ONE dashboard's with a filter
api_read   { "resource": "dashboard-cards", "params": { "filter": "dashboardId == \"<dashboard id>\"", "pageSize": 200 } }
api_read   { "resource": "dashboard-cards", "id": "<card id>" }
api_write  { "resource": "dashboard-cards", "data": { "dashboardId": "…", "measure": "…" } }
api_write  { "resource": "dashboard-cards", "id": "<card id>", "data": { "title": "…" } }
api_delete { "resource": "dashboard-cards", "id": "<card id>" }

记录始终放在 data 下。仪表板按从旧到新排列——第一个是用户打开时看到的仪表板；卡片按 position 返回。 api_details({ resource: "dashboard-cards", operation: "create" }) 是请求正文的权威依据。读取需要 Viewer 权限；任何写入都需要 Member 权限——若返回 403，表示用户的角色无权更改仪表板。

读取仪表板

按名称查找（filter: "name == \"Sales\""），列出其中的卡片，然后按照指标技能的说明，计算用户关注的每张卡片的值——根据 segmentId 或 filter 确定范围，从细分路径中获取关联提示，然后使用卡片的 joinPaths；从 breakdown 获取分组。报告每张卡片的 title（或指标的标题）、其值，以及统计所依据的对象。

图表需要分组

当用户想要条形图、柱状图、圆环图或“可视化图表”时——无论是新建卡片还是修改现有卡片——都要同时发送 breakdown 和 visualization，绝不要只发送 visualization：即使成功保存，卡片仍只会显示一个数字（标题中提到分组也不会改变这一点）。根据用户的描述选择维度（如“按销售管道”“按阶段”）；如果用户没有指定维度，请从 meta 中提供两到三个合适的维度并询问，不要自行选择，且在用户回答前不要写入任何内容。声称卡片显示图表前，请检查读回的数据是否已设置 breakdown。

添加卡片

1. 列出仪表板中的卡片。 如果已有范围相同的同一指标，请指向它，而不是再添加一张重复卡片。

2. 使用指标技能选择指标和范围：一个数值型指标；以该指标所属立方体为根的分段、条件，或不设范围；每个读取其他立方体的操作都要指定一条连接路径；不要对指标或行数很多的立方体设置条件。

3. 编写配置。 dashboardId 和 measure 为必填项；根据需要添加 segmentId 或 filter、joinPaths、breakdown、visualization、title。省略 position 即追加到末尾。只有指定了 breakdown 才能添加 visualization；如果用户要求图表但没指定字段，请停在这里并询问要用哪个字段（见上文）。

   服务端会检查仪表板和分段是否存在、指标是否为数值型指标、分解字段是否为维度、每个条件是否指定了存在的 member，以及分段和筛选条件是否没有同时设置——400 会一次列出所有问题；请全部修正，不要原样重发。 服务端不会检查分段的根、指标条件、扇出或 joinPaths：这些配置仍可成功保存，但应用会将卡片显示为不可用。

4. 重新读取并计算其值，让用户知道卡片会显示什么——并立即发现问题卡片，而不是等用户发现。

修改卡片

只发送要更改的字段。null 可清除 title、segmentId、breakdown、visualization；filter 和 joinPaths 会整体替换，因此请从最新读取结果开始修改。

• 筛选条件 → 分段：{ "segmentId": "…", "filter": {} }。 分段 → 筛选条件：{ "segmentId": null, "filter": { … } }。
• 移除其他立方体上的条件或分解字段：同时移除对应的 joinPaths 条目，除非卡片上还有其他内容读取该立方体。
• 重新排序：将 position 设为新相邻项之间的值（1 和 2 之间为 1.5）。
• 移动：设置 dashboardId；省略 position 即移至末尾。

服务端只会检查更新中指定的内容：仅重命名不会触发对其余内容的重新验证。

卡片不可用或显示不正确的原因

卡片所依赖的模型和分段会发生变化——系统不会自动修复它们，而且即使某个分段或立方体仍被卡片使用，也可以将其删除。读取卡片（及其分段），然后按应用中的顺序检查：

1. 指标已删除 — measure 不在 meta 中。
2. 分段已删除 — segmentId 无法解析。
3. 字段已删除 — 条件中的成员（卡片条件或动态分段条件）、分解字段，或静态分段的 segment_… 立方体不在 meta 中。
4. 条件设在指标上 — 位于卡片筛选条件或动态分段筛选条件中。
5. 连接路径已删除 — joinPaths 或分段路径中的某一跳已不再由模型声明。
6. 条件设在扇出字段上 — 条件位于行数很多的立方体上。

可通过更新修复（改为指向重命名后的成员、移除条件、切换范围），或说明模型需要如何更改。如果没有任何问题标记，但数值看起来不对，可能是连接路径选错、静态分段未重新快照、字符串值与存储值拼写不同、分解字段存在扇出，或数据过期（metadata.lastRefreshTime）。

创建、重命名和删除仪表板

• 创建：name（1–255 个字符），可选的 description。先检查是否已有同名项；如果有，请先询问。所有人都能看到它——不要只为试用而创建。
• 重命名：仅修改 name / description。
• 删除卡片：说明要删除的卡片（标题或指标、范围、仪表板），并征得同意。
• 删除仪表板：会删除仪表板上的所有卡片。列出这些卡片，告知用户数量和具体内容，并说明整个组织都会失去这些卡片，然后就删除此仪表板明确征求同意。

删除后无法撤销。即使是你在失败尝试中自行创建的卡片或仪表板，也不例外——请说明情况，并在删除前征求同意。