metabase-doctorlisted

# Metabase Doctor — 看板诊断与优化工作流 把"review 和优化 Metabase 看板"做成可重复、不漏步的流程。 **核心理念**：绝不轻信 SQL 字面意思，所有假设都用数据库实测验证。 --- ## 何时启用 - 用户说"review 看板 / 看看 dashboard 有没有问题 / 优化这张 card" - 用户贴 Metabase URL（`/dashboard/<id>` 或 `/question/<id>`）要求处理 - 用户报告"这个数字不对 / 这个列没意义 / 排序错了 / 没用筛选还是看到了其他数据" - 用户说"加个店铺/时间/SKU 筛选" - 用户说"列太多了，美化下" / "看不出哪个是重点" - 用户在已做完一轮后说"还有 X 列要改" → 直接进入第 4 步开始新一轮迭代 --- ## 前置依赖 至少满足以下之一： - **Metabase MCP**：工具名 `mcp__metabase__*`，能拉 dashboard 结构、跑 SQL - **Metabase REST API**：环境变量 `METABASE_URL` + `METABASE_API_KEY`，用 curl/Python 调 - **直连数据库**（可选）：跑 SQL 验证字段语义比 Metabase MCP 更快 工作目录建议有 `note.md` 用于跨会话沉淀（详见 references/sop.md）。 --- ## 标准 8 步流程 ### Step 1 — 定位 & 全量拉取 SQL 明确目标看板/card ID。**让用户给 URL 或 ID，不靠搜索关键词去猜**。 ```python # 1. 拉看板结构 GET /api/dashboard/<dash_id> # 拿 dashcards 列表 + tabs + parameters # 2. 每张 card 的 SQL GET /api/card/<card_id> # dataset_query.native.query 是真 SQL ``` 把所有 SQL 落到本地 `card_<id>.sql`，便于 diff 和回滚。**绝不**靠 `card/:id/query` 接口反推 SQL —— 它只返回数据。 详见 `references/sop.md`。 ### Step 2 — 字段语义验证（最关键的一步） **SQL 写什么 ≠ 字段就是什么意思**。逐张 card 找出每个非平凡字段，去数据库验证。 四类检查（详见 `references/known-pitfalls.md`）： 1. **字段注释** — `col_description((schema||'.'||table)::regclass, ordinal_position)` 2. **取值分布** — 不同分支/分组下的取值 3. **数学关系** — `total = a + b + c?` 是否成立 4. **唯一性** — 一对一还是一对多？ **经典陷阱模式**（每个都遇过真实案例）： - **聚合行混入明细行**：表里有 `channel='ALL'` 这种预聚合行 + `channel='A'/channel='B'` 明细行同时存在 → 漏过滤会双计/三计 - **字段含全时效但被并列展示**：`shipment_total = shipment_7d + shipment_8