manage-dashboard-widgets

管理仪表盘小组件

面向在仓库中处理仪表盘小组件磁贴的 PostHog 工程师。

面向人类的概述：products/dashboards/CONTRIBUTING.md

范围内： 小组件磁贴（DashboardTile 上的 widget_id）——发布新类型或修改已发布的类型。

范围外： 将已有类型添加到仪表盘（MCP dashboard-widget-catalog-list → dashboard-widgets-batch-add）；洞察磁贴、文本卡片、按钮磁贴。

1. 先确定路径

请求	路径	从这里开始
尚不存在的新 widget_type	发布	§2 发布新类型 — 必须进行需求收集
修改已发布的类型（配置、查询、UI、布局、RBAC、弃用）	更新	§3 更新已发布的类型 — 跳过需求收集
将已有类型添加到仪表盘	—	仅限 MCP — 不属于本技能
用于仪表盘上产品指标的图表 / 趋势 / 图形	—	洞察磁贴 — architecture.md § 图表

已发布的类型（以代码为准）：architecture.md § 已发布的类型。

2. 发布新的 widget_type

需求收集 — 编码前先询问

仅新类型必须执行。 阅读 widget-intake.md 并：

1. 在仓库中发现产品 UI — 在提出通用磁贴主体问题之前，先了解具体的组件/场景。
2. 应用默认值与推断（groupId、文案主线、列表 UX）— 绝不询问 AskQuestion 禁止的话题。
3. 消除歧义 — 对缺口进行一次批量追问，最多 6 个问题（开放字段）。
4. 发布规格表；在清单 §1 之前获得确认。

执行

规格确认后 → checklist-new-widget-type.md §1 → §8。§5b（专门的故事 — 在 PR 之前必须完成，而非后续事项）在 MVP 测试通过后排定顺序。

自更新 / 实时磁贴？先阅读 live-widgets.md — 实时契约（is_live、creation_flag、generatedAt 种子）以及 widgets/live/ 工具包。

3. 更新已发布的类型

跳过需求收集。 根据请求或 widget_registry.py 中的 EXPECTED_WIDGET_TYPES 确定类型。

1. 阅读 managing-existing-widgets.md — "What kind of change?" 路由表以确定主要文件。
2. 确认：哪个类型、更改什么、配置迁移是否向后兼容？
3. 按照该表中链接的参考资料操作 — 不要重新阅读新类型清单。

无法就地更改： 现有行上的 widget_type 字符串；当目录默认值变化时已存储的 w/h。

新的可视化种类 = 发布（§2）。以图表为主 = 洞察磁贴（architecture.md § 图表）。

4. 平台不变量

两条路径：

1. 由 RBAC 注册表驱动 — dashboard.py 中没有任何 widget_type 分支。permissions-and-sharing.md § 产品 RBAC
2. 处处只有一个 widget_type — 注册表 + 两个目录 + FE 注册表；各变体仅共享 groupId。
3. 按类型划分的代码位于产品路径中 — 而非平台外壳中。architecture.md § 平台文件
4. WidgetCard 复合模式 — composition.md
5. 配置契约 = Pydantic SSOT — widget_specs/configs.py + registry.py 中的 WidgetSpec；为 OpenAPI/FE Zod/MCP 执行 hogli build:openapi。运行时 PATCH 仍为 JSONField。参见 config-and-codegen.md。
6. 没有图表为主的微件 — architecture.md § 图表

新的 widget_type 字符串无需迁移 — 只需注册注册表 + 目录。

5. 配套技能

技能	使用时机
improving-drf-endpoints	仪表板 @extend_schema（配置序列化器自动从 WIDGET_SPECS 派生）
writing-kea-logics	edit*WidgetModalLogic.ts 或 dashboardLogic.tsx
django-migrations	仅限 DashboardWidget / DashboardTile 模式
adopting-generated-api-types	frontend/utils.ts 中的 Tile PATCH

6. 验证

MVP 冒烟（渲染 + 核心测试 — 不是发布点）：

hogli test products/dashboards/backend/api/test/test_run_widgets.py
hogli test products/dashboards/backend/api/test/test_dashboard_widgets.py
hogli test products/dashboards/frontend/widgets/registry.test.tsx

发布门槛（PR 前必需）： 检查清单 §8 + hogli build:openapi + 按 检查清单 §5b 为每个组件提供专门的 Storybook 故事（组件 + 编辑模态框 — 必需，而不仅仅是目录概览）。

配置 SSOT 变更（在编辑 widget_specs/ 后也运行）：

hogli test products/dashboards/backend/api/test/test_widget_config_schema_parity.py
hogli test products/dashboards/frontend/widgets/widgetConfigSchemaParity.test.ts
hogli test products/dashboards/backend/api/test/test_widget_openapi_enums.py   # new widget_type only

更新： 针对所触及层的测试 — 至少，如果 BE 更改，则更新 test_run_widgets.py；如果 FE 更改，则更新 products/dashboards/frontend/widgets/；如果配置 OpenAPI 更改，则执行 hogli build:openapi。参见 managing-existing-widgets.md 路由表中的 Also check 列。

Reference appendix

Topic	Doc
Intake (new types only)	widget-intake.md — canonical defaults + spec recap
New type checklist	checklist-new-widget-type.md
Update shipped type	managing-existing-widgets.md
Architecture	architecture.md — file map, invariants
Config + codegen	config-and-codegen.md
WidgetCard / edit modal	composition.md
List footer / tile filters	list-widget-patterns.md
Live / self-updating tiles	live-widgets.md — contract + widgets/live/ toolkit
Tile min/max	layout-and-ux.md
RBAC / sharing	permissions-and-sharing.md
Setup gates	availability-and-gating.md
MCP after ship	mcp.md
Skill doc maintenance	skill-maintenance.md