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. 曖昧さを解消する — 不足分についてまとめて1回のフォローアップ、最大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 を読みます — 主要ファイルへの 「どのような種類の変更か？」 ルーティングテーブルです。
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	dashboard の @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 の前に必須): checklist §8 + hogli build:openapi + checklist §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