内容
# R1 Dash Master
一款构建 **可导入的RUCKUS One Data Studio仪表盘** 的MCP服务器，基于简单的声明式规范。输出是一个`.zip`文件，可通过 **Data Studio → 设置 → 导入仪表盘** 导入。纯离线生成 — 无需R1 API凭证。
Data Studio是基于Apache Druid后端（`deployment: ALTO`）的Apache Superset。本工具编码了反向工程的数据集目录和图表/查询语法，以便您（或代理）可以构建有效的仪表盘，而无需学习Superset内部机制或猜测字段名称。
## 工具
- **`list_datasets()`** — 所有18个R1数据集（内部名称、立方体名称、ID、计数）。
- **`describe_dataset(name)`** — 一个数据集的精确指标 + 维度名称。
- **`validate_spec(spec)`** — 在构建之前检查规范是否符合目录要求。
- **`build_dashboard(spec, filename?)`** — 生成可导入的`.zip`文件（写入`out/`）。
## 规范格式
```jsonc
{
"title": "网络智能", // 通用 — 绝不能特定于租户（包可以在EC之间移植）
// tenant_id: 可选 — 省略它。导入会自动映射到目标EC（租户）。仅在需要硬绑定租户时包含。
"time_range": "上周", // 所有图表的默认时间范围
"rows": [ // 每一行 = 图表列表；一行中的宽度总和 ≤ 12
[ {chart}, {chart} ]
]
}
```
图表：
```jsonc
{
"type": "大数字" | "大数字趋势" | "折线图" | "条形图" | "面积图" | "散点图" | "饼图" | "表格"
| "仪表盘" | "热力图" | "漏斗图" | "数据透视表" | "混合图" | "树形图" | "气泡图",
"stacked": true, // 仅限条形图/面积图：堆叠系列
"x": "apMac", // 折线图/条形图/面积图/散点图：可选维度 x 轴（默认 __time）
// 数据透视表： "rows": ["zoneName"], "columns": ["radio"], "metrics": [...]
// 混合图： "metrics": [...] （条形图）+ "metrics_b": [...] （折线图）+ 可选 "groupby"/"groupby_b","format_b"
// 树形图： "id": "apName", "parent": "apModel", "name": "apName", "metric": "..."
// 气泡图： "entity": "apName", "x": <metric>, "y": <metric>, "size": <metric> （x/y/size 为指标）
// 漏斗图/仪表盘/热力图： "metric" （单个）+ "groupby" （维度列表；热力图使用第一个维度作为Y轴）
"dataset": "binnedSessions", // 内部名称，来自 list_datasets
"title": "...", "width": 1-12,
"metric": "用户流量（总量）" // 大数字/饼图；字符串 = 已保存的指标
| {"sql": "1.0*SUM(a)/SUM(b)", "label": "速率"}, // 或自定义SQL（比率/百分比）
"metrics": [ ... ], // 折线图/表格（相同格式的列表）
"groupby": ["radio"],
"filter": ["radio","5"] | [["radio","5"],["zoneName","X"]],
"time_range": "昨天", // 可选的图表级覆盖
"format": ".1%", // d3 数字格式（速率 -> ".1%"）
"percent_of_total": ["流量（总量）"], // 表格：列总和占比列
"row_limit": 25
}
```
## 布局和交叉筛选（设计约定）
Data Studio仪表盘是 **可交叉筛选的**：单击任何图表中的值（例如，某个场馆的表格）会将整个仪表盘筛选为该值；清除它会移除筛选。因此，**将场馆和AP表格/图表放在顶部** — 它们兼作交互式筛选控件。推荐顺序：KPI行 → 场馆（和AP）表格 → 下方的详细图表。构建工具保留规范中的行顺序，因此按此顺序排列`rows`。
## 语法说明（注意事项）
- **字段名称是精确且特定于数据集的。** `radio` 而不是 `Radio`；`Unique Client MAC Count` 而不是 "Unique Client Count"；`User Traffic(Total)` （无空格） 在 `sessionsSummary` 中，而 `User Traffic (Total)` （有空格） 在 `binnedSessions` 中。`validate_spec` 会捕获已保存的指标/维度拼写错误。
- **自定义SQL指标引用原始列** （例如 `successCount`），而不是显示指标名称，并且整数除法向下取整 — 始终使用 `1.0 *` （或 `100.0 *`）。参见目录中的 `raw_columns`。
- **速率 vs 占比：** 真实的速率 = SQL指标 + `.1%` 格式。`percent_of_total` （表格 `percent_metrics`）表示“占列总和的百分比”（贡献），而不是“格式化为百分比”。
- 仪表盘 **可在EC之间转换** — 保持标题通用，交换 `tenant_id`。
## 命令行界面（无需MCP）
```bash
python3 builder.py examples/network_intelligence.json out/network_intelligence_IMPORT.zip
```
## 作为MCP运行
```bash
pip install -r requirements.txt
python3 server.py
```
然后在MCP客户端配置中注册（命令：`python3`，参数：`["/home/alek/src/r1_dash_master/server.py"]`）。
## 示例与画廊
- **`examples/*.json`** — 源规范，用于驱动MCP/构建工具和学习规范格式。
- **`gallery/*.zip`** — 预构建的、**可导入的**仪表盘。由于包是无租户的，因此它们会自动映射到您导入它们的EC。获取一个 → Data Studio → 设置 → 导入仪表盘。当前集合：executive_overview, capacity_rf, connection_health, network_intelligence, switch_health, chart_gallery.
- 随时使用以下命令重新生成画廊： **`./build_gallery.sh`** （保持zip文件同步）。
## 状态
目录：19个数据集中有18个已映射（AP警报和控制器库存仅适用于SmartZone，在R1中不可用）。
可视化（15）：大数字，大数字趋势，折线图，条形图，面积图，散点图，饼图，表格，仪表盘，热力图，漏斗图，数据透视表，混合图，树形图，气泡图。查询语法：已保存的 + 自定义SQL指标，占总和的百分比，维度 + 时间筛选，d3格式。内置交叉筛选（单击图表值以筛选仪表盘）。暂无：显式仪表盘级原生筛选栏；剩余的可视化（树图，旭日图，箱线图，雷达图，瀑布图，图形，柱状图，日历热力图，桑基图，平滑/阶梯折线图）；自动导入（需要分析后端API — 通过UI导入zip文件）。
