PostHog 仪表盘系统全景从领域模型到多渲染表面Placement的前后端所有权地图【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthogPostHog 的仪表盘Dashboard并不是一个只存在于标准仪表盘页面的功能——同一份仪表盘数据会在标准页面、项目主页、功能标志详情页、群组/用户详情页、公开分享链接、导出打印等多种“渲染表面”上呈现。本文基于 PostHog 仓库中仪表盘技能的参考文档 surfaces-and-ownership.md结合其上下文 managing-dashboards/SKILL.md 与真实源码完整梳理仪表盘领域的领域模型划分、DashboardPlacement前端放置契约、前后端文件的“所有权地图”以及 API 契约变更的标准流程。读完本文你将能够准确判断一个仪表盘改动应落在哪些文件、哪些渲染表面必须逐一验证以及如何安全地执行序列化器/视图集级别的 API 契约变更。一、从领域模型开始谁拥有什么数据文档要求任何仪表盘改动都应“从领域模型开始”Start from the domain model其核心结论是四个模型各自拥有不同的数据职责改动前必须先判断你要动的状态属于哪一层Dashboard模型拥有项目作用域的元数据仪表盘过滤器filters、变量variables、分享状态sharing state、限制级别restriction_level以及与磁贴tile的关系。DashboardTile模型拥有一条磁贴关系以及每个断点breakpoint的布局 JSON。一个磁贴恰好是一个insight、文本卡片text card、按钮button或部件widget之一。DashboardTemplate存储的是可复制的仪表盘定义它不是一个活的仪表盘。仪表盘 widget 使用独立的模型widget 相关的改动应走manage-dashboard-widgets这条独立技能线。Dashboard 模型元数据与可见性从源码 dashboard.py 可以完整印证文档中“Dashboard 拥有什么”的说法filters models.JSONField(defaultdict)与variables models.JSONField(...)承载仪表盘级过滤器和变量restriction_level默认值为RestrictionLevel.EVERYONE_IN_PROJECT_CAN_EDIT与“限制级别”归 Dashboard 所有对应旧的share_token/is_shared字段已被标记为 DEPRECATED注释明确写着“use the new sharing relation instead”当前分享状态由独立的SharingConfiguration关系承载is_sharing_enabled属性dashboard.py从sharingconfiguration_set读取——这正是文档中 “sharing state” 的落地方式模型还定义了网格间距档位DASHBOARD_GRID_SPACING_GAPStight 8px / condensed 12px / standard 16px / relaxed 32px / wide 48px和布局压缩模式LayoutCompactionvertical / horizontal / stable说明布局几何参数也归 Dashboard 层管辖软删除通过deleted字段加自定义DashboardManager实现默认查询集自动exclude(deletedTrue)需要包含已删除行时用objects_including_soft_deleted。CreationMode.UNLISTED产品内嵌的“隐藏”仪表盘文档特别强调的一点是产品创建的非公开unlisted仪表盘必须纳入检查范围。Dashboard.CreationMode.UNLISTED只是让这些仪表盘从常规列表中隐藏但并不会移除任何仪表盘规则。源码中该枚举定义及其注释dashboard.py给出了典型场景class CreationMode(models.TextChoices): DEFAULT default, Default TEMPLATE (template, Template) # 由预定义模板创建 DUPLICATE (duplicate, Duplicate) # 从另一个仪表盘复制 UNLISTED (unlisted, Unlisted (product-embedded)) # Product dashboards (e.g. AI observability) - hidden from general lists, # accessed via tag queries即 AI observability 等产品内嵌仪表盘使用unlisted模式创建通过 tag 查询访问。对工程实践的含义是任何基于“仪表盘列表”做假设的改动列表接口、列表页 UI、批量操作都要意识到存在一个不在列表里但依然完整受权限、过滤器、布局规则约束的仪表盘集合。DashboardTile 模型一个磁贴恰好一个内容dashboard_tile.py 精确实现了文档中“一个磁贴恰好是 insight、text、button 或 widget 之一”的约束且用双重手段保证数据库层build_unique_relationship_check((insight, text, button_tile, widget))生成CheckConstraint约束名dash_tile_exactly_one_related_object同时针对每个 (dashboard, 内容) 组合建立了部分唯一约束unique_dashboard_insight、unique_dashboard_text等。应用层clean()方法显式校验“related_fields ! 1 就抛 ValidationError”并规定刷新相关字段filters_hash、refreshing、refresh_attempt、last_refresh只允许出现在 insight 磁贴上。磁贴的其余字段也印证了“每断点布局 JSON 归磁贴所有”layouts models.JSONField(defaultdict)其结构形如{sm: {h: 3, w: 4, x: 0, y: 2, minH: 3, minW: 3}, xs: {...}}——可以推断sm/xs等键就是文档所指的 breakpoint。排序工具函数sort_tiles_by_layout按 (y, x, id) 排序id 作为兜底 tiebreak 以避免数据库返回顺序的随机性。此外save()中会自动从dashboard.team_id回填team_id该字段被反规范化以便该表能通过 HogQL 暴露——HogQL 打印器会对每张 Postgres 表注入WHERE team_id ctx.team_id这与技能主文档中“保持仪表盘与磁贴数据团队作用域化”的规则相呼应。DashboardTemplate 模型模板不是活仪表盘dashboard_templates.py 证实了“DashboardTemplate存储可复制的仪表盘定义它不是活仪表盘”模板的磁贴内容是一整个 JSON 字段tiles models.JSONField(...)而非对DashboardTile表的外键引用dashboard_filters、variables同样是 JSON 快照模板有独立的作用域枚举Scopeteam/organization/global/feature_flag以及availability_contexts例如general、onboarding与is_featured等分发字段团队内模板名唯一unique_template_name_per_team约束模型内置了两个硬编码的“Product analytics”模板legacy_signup_template()旧版 DEFAULT_APP 种子与default_signup_template()新版注册默认布局含 TEXT/INSIGHT/BUTTON 混合磁贴与 sm/xs 双断点布局源码注释说明系统假设该模板始终存在、不会等待从模板仓库导入。功能标志的用量仪表盘则由feature_flag_template(feature_flag_key)生成——这正是后文FeatureFlag渲染表面的数据来源。二、渲染表面DashboardPlacement 前端放置契约文档给出的核心规范是使用DashboardPlacement作为前端放置契约frontend placement contract即任何在前端渲染仪表盘 UI 的组件都必须显式声明自己处于哪个放置位置并按该位置执行对应行为。Placement要求的行为Dashboard完整的已认证仪表盘。可能可用编辑能力。ProjectHomepage与Builtin仪表盘内容渲染在另一个已认证的产品表面中。检查操作可见性与可用宽度。Public公开分享。只读。不得暴露作者信息、文件夹、私有配置或强制刷新操作。Export导出渲染。不得添加交互控件也不得假设有浏览器用户会话。FeatureFlag与Group嵌入式仪表盘上下文。检查宿主页面、URL 状态、权限与刷新行为。前端枚举的实际定义DashboardPlacement枚举定义于 frontend/src/types.ts其成员比文档表格更完整——文档表只挑了改动决策中最关键的一批实际枚举还包含若干产品内嵌表面export enum DashboardPlacement { Dashboard dashboard, // When on the standard dashboard page CustomerAnalytics customer-analytics, // When embedded on the customer analytics page ProjectHomepage project-homepage, // When embedded on the project homepage FeatureFlag feature-flag, Public public, // When viewing the dashboard publicly Export export, // When the dashboard is being exported (alike to being printed) Person person, // When the dashboard is being viewed on a person page Group group, // When the dashboard is being viewed on a group page Builtin builtin, // Dashboard built into product UI with external controls provided by parent context DataOps data-ops, // When embedded on the data ops scene dashboard tab }仓库中已有大量组件以此契约分支行为例如FeatureFlag.tsx 以DashboardPlacement.FeatureFlag渲染功能标志用量面板数据来自feature_flag_templateGroupDashboardCard.tsx 在群组详情页以DashboardPlacement.Group嵌入仪表盘ExporterDashboardScene.tsx 以DashboardPlacement.Export驱动导出渲染。这说明放置契约不是纸面约定而是贯穿组件树的真实分派依据。每个表面的行为差异要点结合文档表格各表面的关键差异可以归纳为Dashboard标准页功能全集编辑是否可用取决于restriction_level与 RBAC对应 dashboardLogic.tsx 承载的场景状态与 DashboardItems.tsx 的主布局。ProjectHomepage/Builtin内容被嵌入另一个已认证产品表面。两条检查项必须落实——操作可见性编辑、分享等入口可能应隐藏和可用宽度宿主容器比标准页窄布局断点与栅格宽度都要按实际宽度计算。Builtin的枚举注释还补充了一条语义外部控件由父上下文提供。Public公开分享表面。只读必须屏蔽作者authorship、文件夹、私有配置以及“强制刷新”这类依赖登录态会话的操作。Export导出渲染等价于“打印”。不允许出现交互控件按钮、下拉、刷新按钮等也不能假设存在浏览器用户会话——从源码结构看该表面由 Exporter.tsx 与ExporterDashboardScene.tsx承载运行在无登录态的导出管线中。FeatureFlag/Group嵌入在产品详情上下文里。必须检查宿主页面功能标志详情页、群组页、URL 状态宿主路由的参数如何映射到仪表盘过滤器/变量、权限宿主页面可见是否等同于仪表盘可见与刷新行为嵌入表面通常不应沿用标准页的自动刷新策略。技能主文档 SKILL.md 的“请求路由”一节进一步要求编码前必须对七个表面——已认证仪表盘、公开分享、嵌入式、导出、产品内嵌、模板、仪表盘列表与项目主页——逐一记录affected/unaffected/not applicable。这可以理解为对本文所述放置契约的工程化落地先做表面影响面分析再动手改代码。三、所有权地图改动落在哪些文件文档给出的所有权地图Ownership map规定了各关注点的“责任文件”这是避免改动散落错层的关键领域文件模型dashboard.py、dashboard_tile.py、dashboard_templates.py仪表盘端点dashboard.pyAPI模板端点dashboard_templates.py产品路由routes.py场景状态dashboardLogic.tsx主布局DashboardItems.tsx、tileLayouts.ts共享/导出宿主ExporterDashboardScene.tsx、Exporter.tsx上表全部路径均经核实存在于当前仓库。结合技能主文档的代码地图还可以补全两条相邻边界布局几何与磁贴尺寸约束的辅助逻辑在 dashboardUtils.ts刷新默认值与共享安全钳制在 refresh_policy.py。理解所有权地图的实践价值在于模型层改动新增字段、约束、软删除语义归products/dashboards/backend/models/三个文件并伴随 Django 迁移契约层改动序列化器、视图集动作归api/dashboard.py或api/dashboard_templates.py产品对外路由注册在routes.py前端状态改动归dashboardLogic.tsxKea logic负责场景状态、刷新与布局持久化布局渲染改动归DashboardItems.tsxtileLayouts.ts——前者是主布局容器后者负责断点几何计算共享与导出宿主改动归 exporter 目录下的两个文件不要试图在标准仪表盘场景里“顺手”修共享渲染。这种分层与文档第二节的“跨层实现”规则一致当持久化契约改变时产品模型、序列化器、API 动作与生成类型要一起改数据查找与变更必须走仪表盘所属的 team 作用域旧行与旧布局 JSON 要当作版本化输入来保护。四、API 契约变更的标准流程文档最后规定了当改动触及序列化器或视图集时必须执行的流程添加或更新请求与响应 schemarequest and response schema运行hogli build:openapi重新生成 OpenAPI 输出在前端代码中使用生成的 API 类型而不是手写的类型定义同时测试 API 端点与 UI 契约不要直接编辑生成的文件Do not edit generated files directly。仓库中可以直接验证这一流程的接线OpenAPI 任务定义在 hogli.yaml 中包括build:openapi-schema、build:openapi-types等任务见 hogli.yaml。技能主文档的配套技能表也印证了这条链路的分工improving-drf-endpoints负责视图集/序列化器契约与 OpenAPI 输出adopting-generated-api-types负责在前端消费变更后的生成类型django-migrations负责模型 schema 变更。测试边界的对应要求见 SKILL.md 第 5 节的清单——其中“序列化器变更后的 API schema 与生成类型”是显式的必测边界之一。对 Agent 或工程师的实际约束可以概括为三点生成文件永远只读它是 schema 的编译产物前端不得在生成类型之外私自定义仪表盘 DTO任何序列化器字段变更都必须能回答“哪个表面会渲染这个字段、公开/导出表面是否会因此泄露内部信息”——这与第二节中Public表面的“不得暴露私有配置”要求是同一条安全边界的两个侧面。五、小结一张表看懂决策顺序把整份文档压缩成可执行的决策顺序先定位数据所有者要改的状态在Dashboard、DashboardTile还是DashboardTemplatewidget 归另一条技能线再列出渲染表面用DashboardPlacement枚举逐一确认 affected/unaffected特别注意UNLISTED产品内嵌仪表盘与导出/公开表面的只读约束按所有权地图选文件模型 →models/契约 →api/状态 →dashboardLogic.tsx布局 →DashboardItems.tsxtileLayouts.ts共享/导出 → exporter 场景触碰序列化器/视图集时走契约流程更新 schema →hogli build:openapi→ 前端消费生成类型 → 双端测试且绝不手改生成文件。这套“领域模型 → 渲染表面 → 文件所有权 → 契约流程”的骨架配合 SKILL.md 中的功能准入标准、变更契约清单与边界测试清单构成了 PostHog 仪表盘系统改动从设计到验证的完整路径本文引用的每一处实现事实都可以直接在对应仓库路径中复核。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PostHog 仪表盘系统全景：从领域模型到多渲染表面（Placement）的前后端所有权地图
PostHog 仪表盘系统全景从领域模型到多渲染表面Placement的前后端所有权地图【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthogPostHog 的仪表盘Dashboard并不是一个只存在于标准仪表盘页面的功能——同一份仪表盘数据会在标准页面、项目主页、功能标志详情页、群组/用户详情页、公开分享链接、导出打印等多种“渲染表面”上呈现。本文基于 PostHog 仓库中仪表盘技能的参考文档 surfaces-and-ownership.md结合其上下文 managing-dashboards/SKILL.md 与真实源码完整梳理仪表盘领域的领域模型划分、DashboardPlacement前端放置契约、前后端文件的“所有权地图”以及 API 契约变更的标准流程。读完本文你将能够准确判断一个仪表盘改动应落在哪些文件、哪些渲染表面必须逐一验证以及如何安全地执行序列化器/视图集级别的 API 契约变更。一、从领域模型开始谁拥有什么数据文档要求任何仪表盘改动都应“从领域模型开始”Start from the domain model其核心结论是四个模型各自拥有不同的数据职责改动前必须先判断你要动的状态属于哪一层Dashboard模型拥有项目作用域的元数据仪表盘过滤器filters、变量variables、分享状态sharing state、限制级别restriction_level以及与磁贴tile的关系。DashboardTile模型拥有一条磁贴关系以及每个断点breakpoint的布局 JSON。一个磁贴恰好是一个insight、文本卡片text card、按钮button或部件widget之一。DashboardTemplate存储的是可复制的仪表盘定义它不是一个活的仪表盘。仪表盘 widget 使用独立的模型widget 相关的改动应走manage-dashboard-widgets这条独立技能线。Dashboard 模型元数据与可见性从源码 dashboard.py 可以完整印证文档中“Dashboard 拥有什么”的说法filters models.JSONField(defaultdict)与variables models.JSONField(...)承载仪表盘级过滤器和变量restriction_level默认值为RestrictionLevel.EVERYONE_IN_PROJECT_CAN_EDIT与“限制级别”归 Dashboard 所有对应旧的share_token/is_shared字段已被标记为 DEPRECATED注释明确写着“use the new sharing relation instead”当前分享状态由独立的SharingConfiguration关系承载is_sharing_enabled属性dashboard.py从sharingconfiguration_set读取——这正是文档中 “sharing state” 的落地方式模型还定义了网格间距档位DASHBOARD_GRID_SPACING_GAPStight 8px / condensed 12px / standard 16px / relaxed 32px / wide 48px和布局压缩模式LayoutCompactionvertical / horizontal / stable说明布局几何参数也归 Dashboard 层管辖软删除通过deleted字段加自定义DashboardManager实现默认查询集自动exclude(deletedTrue)需要包含已删除行时用objects_including_soft_deleted。CreationMode.UNLISTED产品内嵌的“隐藏”仪表盘文档特别强调的一点是产品创建的非公开unlisted仪表盘必须纳入检查范围。Dashboard.CreationMode.UNLISTED只是让这些仪表盘从常规列表中隐藏但并不会移除任何仪表盘规则。源码中该枚举定义及其注释dashboard.py给出了典型场景class CreationMode(models.TextChoices): DEFAULT default, Default TEMPLATE (template, Template) # 由预定义模板创建 DUPLICATE (duplicate, Duplicate) # 从另一个仪表盘复制 UNLISTED (unlisted, Unlisted (product-embedded)) # Product dashboards (e.g. AI observability) - hidden from general lists, # accessed via tag queries即 AI observability 等产品内嵌仪表盘使用unlisted模式创建通过 tag 查询访问。对工程实践的含义是任何基于“仪表盘列表”做假设的改动列表接口、列表页 UI、批量操作都要意识到存在一个不在列表里但依然完整受权限、过滤器、布局规则约束的仪表盘集合。DashboardTile 模型一个磁贴恰好一个内容dashboard_tile.py 精确实现了文档中“一个磁贴恰好是 insight、text、button 或 widget 之一”的约束且用双重手段保证数据库层build_unique_relationship_check((insight, text, button_tile, widget))生成CheckConstraint约束名dash_tile_exactly_one_related_object同时针对每个 (dashboard, 内容) 组合建立了部分唯一约束unique_dashboard_insight、unique_dashboard_text等。应用层clean()方法显式校验“related_fields ! 1 就抛 ValidationError”并规定刷新相关字段filters_hash、refreshing、refresh_attempt、last_refresh只允许出现在 insight 磁贴上。磁贴的其余字段也印证了“每断点布局 JSON 归磁贴所有”layouts models.JSONField(defaultdict)其结构形如{sm: {h: 3, w: 4, x: 0, y: 2, minH: 3, minW: 3}, xs: {...}}——可以推断sm/xs等键就是文档所指的 breakpoint。排序工具函数sort_tiles_by_layout按 (y, x, id) 排序id 作为兜底 tiebreak 以避免数据库返回顺序的随机性。此外save()中会自动从dashboard.team_id回填team_id该字段被反规范化以便该表能通过 HogQL 暴露——HogQL 打印器会对每张 Postgres 表注入WHERE team_id ctx.team_id这与技能主文档中“保持仪表盘与磁贴数据团队作用域化”的规则相呼应。DashboardTemplate 模型模板不是活仪表盘dashboard_templates.py 证实了“DashboardTemplate存储可复制的仪表盘定义它不是活仪表盘”模板的磁贴内容是一整个 JSON 字段tiles models.JSONField(...)而非对DashboardTile表的外键引用dashboard_filters、variables同样是 JSON 快照模板有独立的作用域枚举Scopeteam/organization/global/feature_flag以及availability_contexts例如general、onboarding与is_featured等分发字段团队内模板名唯一unique_template_name_per_team约束模型内置了两个硬编码的“Product analytics”模板legacy_signup_template()旧版 DEFAULT_APP 种子与default_signup_template()新版注册默认布局含 TEXT/INSIGHT/BUTTON 混合磁贴与 sm/xs 双断点布局源码注释说明系统假设该模板始终存在、不会等待从模板仓库导入。功能标志的用量仪表盘则由feature_flag_template(feature_flag_key)生成——这正是后文FeatureFlag渲染表面的数据来源。二、渲染表面DashboardPlacement 前端放置契约文档给出的核心规范是使用DashboardPlacement作为前端放置契约frontend placement contract即任何在前端渲染仪表盘 UI 的组件都必须显式声明自己处于哪个放置位置并按该位置执行对应行为。Placement要求的行为Dashboard完整的已认证仪表盘。可能可用编辑能力。ProjectHomepage与Builtin仪表盘内容渲染在另一个已认证的产品表面中。检查操作可见性与可用宽度。Public公开分享。只读。不得暴露作者信息、文件夹、私有配置或强制刷新操作。Export导出渲染。不得添加交互控件也不得假设有浏览器用户会话。FeatureFlag与Group嵌入式仪表盘上下文。检查宿主页面、URL 状态、权限与刷新行为。前端枚举的实际定义DashboardPlacement枚举定义于 frontend/src/types.ts其成员比文档表格更完整——文档表只挑了改动决策中最关键的一批实际枚举还包含若干产品内嵌表面export enum DashboardPlacement { Dashboard dashboard, // When on the standard dashboard page CustomerAnalytics customer-analytics, // When embedded on the customer analytics page ProjectHomepage project-homepage, // When embedded on the project homepage FeatureFlag feature-flag, Public public, // When viewing the dashboard publicly Export export, // When the dashboard is being exported (alike to being printed) Person person, // When the dashboard is being viewed on a person page Group group, // When the dashboard is being viewed on a group page Builtin builtin, // Dashboard built into product UI with external controls provided by parent context DataOps data-ops, // When embedded on the data ops scene dashboard tab }仓库中已有大量组件以此契约分支行为例如FeatureFlag.tsx 以DashboardPlacement.FeatureFlag渲染功能标志用量面板数据来自feature_flag_templateGroupDashboardCard.tsx 在群组详情页以DashboardPlacement.Group嵌入仪表盘ExporterDashboardScene.tsx 以DashboardPlacement.Export驱动导出渲染。这说明放置契约不是纸面约定而是贯穿组件树的真实分派依据。每个表面的行为差异要点结合文档表格各表面的关键差异可以归纳为Dashboard标准页功能全集编辑是否可用取决于restriction_level与 RBAC对应 dashboardLogic.tsx 承载的场景状态与 DashboardItems.tsx 的主布局。ProjectHomepage/Builtin内容被嵌入另一个已认证产品表面。两条检查项必须落实——操作可见性编辑、分享等入口可能应隐藏和可用宽度宿主容器比标准页窄布局断点与栅格宽度都要按实际宽度计算。Builtin的枚举注释还补充了一条语义外部控件由父上下文提供。Public公开分享表面。只读必须屏蔽作者authorship、文件夹、私有配置以及“强制刷新”这类依赖登录态会话的操作。Export导出渲染等价于“打印”。不允许出现交互控件按钮、下拉、刷新按钮等也不能假设存在浏览器用户会话——从源码结构看该表面由 Exporter.tsx 与ExporterDashboardScene.tsx承载运行在无登录态的导出管线中。FeatureFlag/Group嵌入在产品详情上下文里。必须检查宿主页面功能标志详情页、群组页、URL 状态宿主路由的参数如何映射到仪表盘过滤器/变量、权限宿主页面可见是否等同于仪表盘可见与刷新行为嵌入表面通常不应沿用标准页的自动刷新策略。技能主文档 SKILL.md 的“请求路由”一节进一步要求编码前必须对七个表面——已认证仪表盘、公开分享、嵌入式、导出、产品内嵌、模板、仪表盘列表与项目主页——逐一记录affected/unaffected/not applicable。这可以理解为对本文所述放置契约的工程化落地先做表面影响面分析再动手改代码。三、所有权地图改动落在哪些文件文档给出的所有权地图Ownership map规定了各关注点的“责任文件”这是避免改动散落错层的关键领域文件模型dashboard.py、dashboard_tile.py、dashboard_templates.py仪表盘端点dashboard.pyAPI模板端点dashboard_templates.py产品路由routes.py场景状态dashboardLogic.tsx主布局DashboardItems.tsx、tileLayouts.ts共享/导出宿主ExporterDashboardScene.tsx、Exporter.tsx上表全部路径均经核实存在于当前仓库。结合技能主文档的代码地图还可以补全两条相邻边界布局几何与磁贴尺寸约束的辅助逻辑在 dashboardUtils.ts刷新默认值与共享安全钳制在 refresh_policy.py。理解所有权地图的实践价值在于模型层改动新增字段、约束、软删除语义归products/dashboards/backend/models/三个文件并伴随 Django 迁移契约层改动序列化器、视图集动作归api/dashboard.py或api/dashboard_templates.py产品对外路由注册在routes.py前端状态改动归dashboardLogic.tsxKea logic负责场景状态、刷新与布局持久化布局渲染改动归DashboardItems.tsxtileLayouts.ts——前者是主布局容器后者负责断点几何计算共享与导出宿主改动归 exporter 目录下的两个文件不要试图在标准仪表盘场景里“顺手”修共享渲染。这种分层与文档第二节的“跨层实现”规则一致当持久化契约改变时产品模型、序列化器、API 动作与生成类型要一起改数据查找与变更必须走仪表盘所属的 team 作用域旧行与旧布局 JSON 要当作版本化输入来保护。四、API 契约变更的标准流程文档最后规定了当改动触及序列化器或视图集时必须执行的流程添加或更新请求与响应 schemarequest and response schema运行hogli build:openapi重新生成 OpenAPI 输出在前端代码中使用生成的 API 类型而不是手写的类型定义同时测试 API 端点与 UI 契约不要直接编辑生成的文件Do not edit generated files directly。仓库中可以直接验证这一流程的接线OpenAPI 任务定义在 hogli.yaml 中包括build:openapi-schema、build:openapi-types等任务见 hogli.yaml。技能主文档的配套技能表也印证了这条链路的分工improving-drf-endpoints负责视图集/序列化器契约与 OpenAPI 输出adopting-generated-api-types负责在前端消费变更后的生成类型django-migrations负责模型 schema 变更。测试边界的对应要求见 SKILL.md 第 5 节的清单——其中“序列化器变更后的 API schema 与生成类型”是显式的必测边界之一。对 Agent 或工程师的实际约束可以概括为三点生成文件永远只读它是 schema 的编译产物前端不得在生成类型之外私自定义仪表盘 DTO任何序列化器字段变更都必须能回答“哪个表面会渲染这个字段、公开/导出表面是否会因此泄露内部信息”——这与第二节中Public表面的“不得暴露私有配置”要求是同一条安全边界的两个侧面。五、小结一张表看懂决策顺序把整份文档压缩成可执行的决策顺序先定位数据所有者要改的状态在Dashboard、DashboardTile还是DashboardTemplatewidget 归另一条技能线再列出渲染表面用DashboardPlacement枚举逐一确认 affected/unaffected特别注意UNLISTED产品内嵌仪表盘与导出/公开表面的只读约束按所有权地图选文件模型 →models/契约 →api/状态 →dashboardLogic.tsx布局 →DashboardItems.tsxtileLayouts.ts共享/导出 → exporter 场景触碰序列化器/视图集时走契约流程更新 schema →hogli build:openapi→ 前端消费生成类型 → 双端测试且绝不手改生成文件。这套“领域模型 → 渲染表面 → 文件所有权 → 契约流程”的骨架配合 SKILL.md 中的功能准入标准、变更契约清单与边界测试清单构成了 PostHog 仪表盘系统改动从设计到验证的完整路径本文引用的每一处实现事实都可以直接在对应仓库路径中复核。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考