PostHog 前端路由定位指南从代码出发的 QA 路由映射方法论【免费下载链接】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 前端规模庞大如何为一次改动精准定位可运行的页面路由是浏览器 QA 中最容易踩坑的一环。本文基于 .agents/skills/qa-frontend/references/route-finding.md 整理出一套以源码为唯一事实来源source of truth的路由定位流程核心 App 场景走appScenes.ts→scenes.ts→urls.*三层溯源产品级场景走manifest.tsx清单映射并配套rg兜底搜索与coverage_gap兜底机制。读完本文你将能在一分钟内把一个组件/逻辑/钩子文件映射到 1~3 个真实可测的路由并安全处理动态路由参数。核心原则读代码找路由不依赖生成器与硬编码表route-finding.md开篇即给出整个方法论的第一原则通过阅读代码定位路由Find routes by reading the code不要依赖任何生成的辅助工具或硬编码路由表Do not depend on a generated helper or a hardcoded route table。这条原则的实践含义是PostHog 前端不存在一张URL → 组件的总表可以直接查询路由关系散布在场景注册、路由表、URL 构造器与产品清单四个层面。机械地搜索某个 URL 字符串往往得到的是旧版本残留或死代码唯有顺着导入链import chain追踪组件 → 场景 → 路由表达式的映射关系才能拿到当前真实生效的映射。这一原则也贯穿本文后续所有章节每次定位都以阅读源码为起点搜索工具rg只是辅助手段。Core App 路由核心场景的三层溯源对于frontend/src/scenes/scene/...目录下的改动文件即核心 App 场景文档给出了三步溯源流程。第一步在appScenes.ts中查找场景导入frontend/src/scenes/appScenes.ts是场景注册表它将Scene枚举的每个键映射到实际的组件文件通过动态import()实现按需加载。例如// frontend/src/scenes/appScenes.ts export const appScenes: RecordScene | string, () any { ...productScenes, [Scene.Cohort]: () import(./cohorts/Cohort), [Scene.Dashboards]: () import(./dashboard/dashboards/Dashboards), [Scene.Insight]: () import(./insights/InsightScene), // ... }从源码结构看appScenes还通过...productScenes合并了所有产品的场景productScenes由~/productScenes提供这意味着核心场景与产品场景在此汇合为后续两类路由定位提供了统一入口。当你改动了一个场景文件例如frontend/src/scenes/cohorts/Cohort.tsx时第一步就是确认该文件被哪个Scene.*键引用。第二步在scenes.ts中确认Scene.Name路由条目frontend/src/scenes/scenes.ts是场景配置与路由的核心枢纽包含三块关键内容场景配置sceneConfigurations为每个场景声明projectBased、organizationBased、name、layout、iconType等元数据路由表routes将 URL 表达式映射为[Scene, sceneName]二元组重定向表redirects处理历史 URL 的兼容转发。路由表条目形如见 scenes.tsexport const routes: Recordstring, [Scene | string, string] { [urls.dashboards()]: [Scene.Dashboards, dashboards], [urls.dashboard(:id)]: [Scene.Dashboard, dashboard], [urls.featureFlag(:id)]: [Scene.FeatureFlag, featureFlag], [urls.personByUUID(*, false)]: [Scene.Person, personByUUID], // ... 末尾通过 ...productRoutes 合并产品路由 }第三步优先使用具体的urls.*路由表达式或字面路由字符串文档强调优先采用scenes.ts中具体的urls.*路由表达式或字面路由字符串而不是从记忆或 UI 猜测 URL。原因在于urls对象定义于 frontend/src/scenes/urls.ts是 URL 的唯一权威构造器路由表完全以urls.*的返回值为键二者天然同源// frontend/src/scenes/urls.ts export const urls { ...productUrls, project: (id: string | number, path ): string /project/${id} path, eventDefinitions: (): string /data-management/events, eventDefinition: (id: string | number): string /data-management/events/${id}, sqlEditor: ({ query, view_id, ... } {}): string { /* 组装 URLSearchParams */ }, // ... }urls.ts头部注释urls.ts明确列出新增前端 URL 的完整流程在urls.ts加 URL 函数 → 在sceneTypes.ts加Scene枚举 → 在scenes.ts加场景配置与路由映射 → 在appScenes.ts加场景导入且要求与后端AutoProjectMiddleware同步路径。理解这一四步注册 后端同步约定后路由定位就变成了逆向执行该流程。关于动态路由scenes.ts中大量使用:id、:shortId、:groupTypeIndex这类占位符例如urls.dashboard(:id)、urls.insightEdit(:shortId as InsightShortId)、urls.groups(:groupTypeIndex)它们由 kea-router 在运行时解析为真实参数。定位路由时务必保留占位符形式不要臆造具体 ID。Product 路由产品清单驱动的映射PostHog 采用模块化产品架构产品级前端代码位于products/product/frontend/scenes/SceneName/...。这类改动的路由定位走manifest.tsx清单查看products/product/manifest.tsx每个产品如products/actions、products/ai_observability、products/feature_flags等都有一个manifest.tsx文件声明ProductManifest类型的清单对象。以products/actions/manifest.tsx为实例manifest.tsxexport const manifest: ProductManifest { name: Actions, urls: { createAction: (): string /data-management/actions/new, action: (id: string | number): string /data-management/actions/${id}, actions: (): string /data-management/actions, }, scenes: { Actions: { name: Actions, import: () import(./frontend/pages/Actions), projectBased: true, // ... }, Action: { name: Action, import: () import(./frontend/pages/Action), projectBased: true, // ... }, }, routes: { /data-management/actions: [Actions, actions], /data-management/actions/new: [NewAction, actionNew], /data-management/actions/:id: [Action, action], }, // fileSystemTypes、treeItemsNew、treeItemsMetadata 等 }匹配场景目录到清单scenes导入当改动的文件位于products/product/frontend/scenes/SceneName/时在对应产品的manifest.tsx中查找scenes.SceneName条目其import字段即指向该场景的实际组件。例如改动products/actions/frontend/pages/Action.tsx即可在manifest.tsx的scenes中找到Action场景。使用清单routes条目manifest.routes直接给出该场景可用的 URL 模式键与场景名/路由名值例如/data-management/actions/:id对应Action场景。这一步与核心场景第三步殊途同归最终都以具体的 URL 表达式作为测试入口。从源码结构看产品的manifest最终会被聚合并注入核心路由体系frontend/src/scenes/scenes.ts末尾的...productRoutesscenes.ts、...productConfigurationscenes.ts以及appScenes.ts的...productScenesappScenes.ts三处合并共同完成产品路由表、产品场景配置、产品场景注册的接入这也解释了为什么两类路由在运行时是无缝统一的。共享前端代码的路由选择策略改动文件若位于frontend/src/lib/、frontend/src/queries/、frontend/src/types/等共享前端区域或某个产品下的共享前端目录route-finding.md给出的策略是搜索导入关系用rg查找谁 import 了这个改动面changed surface挑选 1~3 个可见场景从引用方中选出最能实际演练该改动行为的 1~3 个路由作为测试目标而不是试图覆盖所有引用方。这一策略的本质是代表性采样共享代码被大量场景引用QA 的价值在于用少量高信号high-signal路由验证行为而非穷举。选出的场景应同时满足两个条件① 真实引用了被改动代码② 在 UI 中可导航到达可见保证后续能通过浏览器实际执行。兜底搜索rg关键词检索当上述结构化路径无法快速定位时route-finding.md建议使用rg进行关键词搜索搜索面包括被改动的组件、钩子或逻辑名component / hook / logic name例如改动useDashboardItems就搜useDashboardItems附近的urls.引用在引用方源码中顺藤摸瓜找到对应的urls.*调用字面路由字符串如/data-management/actions这种直接字符串产品清单的routes与treeItems条目manifest.tsx中的routes直接给 URLtreeItemsMetadata/treeItemsNew如 manifest.tsx则揭示该页面在侧边导航中的位置有助于确认页面是否可见、如何从 UI 进入。兜底搜索的边界同样清晰短暂搜索后仍无法明确路由映射时不要靠猜转入下一节的coverage_gap机制。兜底机制coverage_gap与动态路由占位符无法映射时记录coverage_gap如果经过上述步骤含rg兜底仍无法确定路由文档要求记录一个coverage_gap目标coverage gap target并说明哪个文件无法映射which file could not be mapped检查了哪些上下文what context was checked例如查过哪些导入、搜过哪些关键词、核对过哪些清单条目。coverage_gap在 QA 流程中属于与browser、visual并列的测试用例类型参见 .agents/skills/qa-frontend/SKILL.md 中测试计划的kind: browser|visual|coverage_gap它允许 QA 如实报告未能覆盖而不是用猜测的路由制造虚假的测试结果。这是整套方法论中证据优先、杜绝臆造精神的最直接体现。动态路由保留占位符不臆造 ID文档对动态路由给出两条明确纪律不为动态路由臆造 IDDo not fabricate IDs for dynamic routes在测试计划中保留:id、:runId、:sourceId等占位符形式不要编造一个可能不存在的对象 ID用现有对象或最小安全本地数据需要真实参数时优先从 UI 中选取已存在的对象仅当确有必要时才创建最小的安全本地数据minimal safe local data来驱动测试。结合scenes.ts源码可以看到这类占位符的实际形态urls.dashboard(:id)、urls.experiment(:id, :formMode)、urls.replaySingle(:id)、urls.site(:url)等路由键中的:xxx段就是 kea-router 待解析的运行时参数测试计划中应保持这种模板化写法。实战速查五步定位工作流将全文方法论收敛为可直接执行的五步判定文件归属改动在frontend/src/scenes/下走 Core App 流程在products/product/frontend/下走 Product 流程在共享目录则先搜导入再选场景核心场景溯源appScenes.ts找场景导入 →scenes.ts找Scene.Name路由条目与配置提取路由表达式优先取scenes.ts路由表中的urls.*表达式或字面字符串动态参数保留:id等占位符产品场景溯源读products/product/manifest.tsx匹配scenes导入取routes条目必要时参考treeItems确认导航入口兜底与记录仍无结果则用rg搜组件名、urls.引用、字面路由与清单条目再无法映射则记录coverage_gap说明未映射文件与已检查上下文绝不猜 ID。结语PostHog 的路由体系将URL 构造urls、路由注册routes、场景加载appScenes/产品manifest.scenes三件事分层解耦route-finding.md的定位方法论正是对这一分层结构的逆向运用。对前端 QA 而言坚持读代码、取表达式、留占位符、如实报告覆盖缺口四条纪律既能显著提升路由定位的准确率也能保证每个测试用例都有真实可执行、可复现的落点让 QA 结果经得起审阅。【免费下载链接】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 前端路由定位指南：从代码出发的 QA 路由映射方法论
PostHog 前端路由定位指南从代码出发的 QA 路由映射方法论【免费下载链接】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 前端规模庞大如何为一次改动精准定位可运行的页面路由是浏览器 QA 中最容易踩坑的一环。本文基于 .agents/skills/qa-frontend/references/route-finding.md 整理出一套以源码为唯一事实来源source of truth的路由定位流程核心 App 场景走appScenes.ts→scenes.ts→urls.*三层溯源产品级场景走manifest.tsx清单映射并配套rg兜底搜索与coverage_gap兜底机制。读完本文你将能在一分钟内把一个组件/逻辑/钩子文件映射到 1~3 个真实可测的路由并安全处理动态路由参数。核心原则读代码找路由不依赖生成器与硬编码表route-finding.md开篇即给出整个方法论的第一原则通过阅读代码定位路由Find routes by reading the code不要依赖任何生成的辅助工具或硬编码路由表Do not depend on a generated helper or a hardcoded route table。这条原则的实践含义是PostHog 前端不存在一张URL → 组件的总表可以直接查询路由关系散布在场景注册、路由表、URL 构造器与产品清单四个层面。机械地搜索某个 URL 字符串往往得到的是旧版本残留或死代码唯有顺着导入链import chain追踪组件 → 场景 → 路由表达式的映射关系才能拿到当前真实生效的映射。这一原则也贯穿本文后续所有章节每次定位都以阅读源码为起点搜索工具rg只是辅助手段。Core App 路由核心场景的三层溯源对于frontend/src/scenes/scene/...目录下的改动文件即核心 App 场景文档给出了三步溯源流程。第一步在appScenes.ts中查找场景导入frontend/src/scenes/appScenes.ts是场景注册表它将Scene枚举的每个键映射到实际的组件文件通过动态import()实现按需加载。例如// frontend/src/scenes/appScenes.ts export const appScenes: RecordScene | string, () any { ...productScenes, [Scene.Cohort]: () import(./cohorts/Cohort), [Scene.Dashboards]: () import(./dashboard/dashboards/Dashboards), [Scene.Insight]: () import(./insights/InsightScene), // ... }从源码结构看appScenes还通过...productScenes合并了所有产品的场景productScenes由~/productScenes提供这意味着核心场景与产品场景在此汇合为后续两类路由定位提供了统一入口。当你改动了一个场景文件例如frontend/src/scenes/cohorts/Cohort.tsx时第一步就是确认该文件被哪个Scene.*键引用。第二步在scenes.ts中确认Scene.Name路由条目frontend/src/scenes/scenes.ts是场景配置与路由的核心枢纽包含三块关键内容场景配置sceneConfigurations为每个场景声明projectBased、organizationBased、name、layout、iconType等元数据路由表routes将 URL 表达式映射为[Scene, sceneName]二元组重定向表redirects处理历史 URL 的兼容转发。路由表条目形如见 scenes.tsexport const routes: Recordstring, [Scene | string, string] { [urls.dashboards()]: [Scene.Dashboards, dashboards], [urls.dashboard(:id)]: [Scene.Dashboard, dashboard], [urls.featureFlag(:id)]: [Scene.FeatureFlag, featureFlag], [urls.personByUUID(*, false)]: [Scene.Person, personByUUID], // ... 末尾通过 ...productRoutes 合并产品路由 }第三步优先使用具体的urls.*路由表达式或字面路由字符串文档强调优先采用scenes.ts中具体的urls.*路由表达式或字面路由字符串而不是从记忆或 UI 猜测 URL。原因在于urls对象定义于 frontend/src/scenes/urls.ts是 URL 的唯一权威构造器路由表完全以urls.*的返回值为键二者天然同源// frontend/src/scenes/urls.ts export const urls { ...productUrls, project: (id: string | number, path ): string /project/${id} path, eventDefinitions: (): string /data-management/events, eventDefinition: (id: string | number): string /data-management/events/${id}, sqlEditor: ({ query, view_id, ... } {}): string { /* 组装 URLSearchParams */ }, // ... }urls.ts头部注释urls.ts明确列出新增前端 URL 的完整流程在urls.ts加 URL 函数 → 在sceneTypes.ts加Scene枚举 → 在scenes.ts加场景配置与路由映射 → 在appScenes.ts加场景导入且要求与后端AutoProjectMiddleware同步路径。理解这一四步注册 后端同步约定后路由定位就变成了逆向执行该流程。关于动态路由scenes.ts中大量使用:id、:shortId、:groupTypeIndex这类占位符例如urls.dashboard(:id)、urls.insightEdit(:shortId as InsightShortId)、urls.groups(:groupTypeIndex)它们由 kea-router 在运行时解析为真实参数。定位路由时务必保留占位符形式不要臆造具体 ID。Product 路由产品清单驱动的映射PostHog 采用模块化产品架构产品级前端代码位于products/product/frontend/scenes/SceneName/...。这类改动的路由定位走manifest.tsx清单查看products/product/manifest.tsx每个产品如products/actions、products/ai_observability、products/feature_flags等都有一个manifest.tsx文件声明ProductManifest类型的清单对象。以products/actions/manifest.tsx为实例manifest.tsxexport const manifest: ProductManifest { name: Actions, urls: { createAction: (): string /data-management/actions/new, action: (id: string | number): string /data-management/actions/${id}, actions: (): string /data-management/actions, }, scenes: { Actions: { name: Actions, import: () import(./frontend/pages/Actions), projectBased: true, // ... }, Action: { name: Action, import: () import(./frontend/pages/Action), projectBased: true, // ... }, }, routes: { /data-management/actions: [Actions, actions], /data-management/actions/new: [NewAction, actionNew], /data-management/actions/:id: [Action, action], }, // fileSystemTypes、treeItemsNew、treeItemsMetadata 等 }匹配场景目录到清单scenes导入当改动的文件位于products/product/frontend/scenes/SceneName/时在对应产品的manifest.tsx中查找scenes.SceneName条目其import字段即指向该场景的实际组件。例如改动products/actions/frontend/pages/Action.tsx即可在manifest.tsx的scenes中找到Action场景。使用清单routes条目manifest.routes直接给出该场景可用的 URL 模式键与场景名/路由名值例如/data-management/actions/:id对应Action场景。这一步与核心场景第三步殊途同归最终都以具体的 URL 表达式作为测试入口。从源码结构看产品的manifest最终会被聚合并注入核心路由体系frontend/src/scenes/scenes.ts末尾的...productRoutesscenes.ts、...productConfigurationscenes.ts以及appScenes.ts的...productScenesappScenes.ts三处合并共同完成产品路由表、产品场景配置、产品场景注册的接入这也解释了为什么两类路由在运行时是无缝统一的。共享前端代码的路由选择策略改动文件若位于frontend/src/lib/、frontend/src/queries/、frontend/src/types/等共享前端区域或某个产品下的共享前端目录route-finding.md给出的策略是搜索导入关系用rg查找谁 import 了这个改动面changed surface挑选 1~3 个可见场景从引用方中选出最能实际演练该改动行为的 1~3 个路由作为测试目标而不是试图覆盖所有引用方。这一策略的本质是代表性采样共享代码被大量场景引用QA 的价值在于用少量高信号high-signal路由验证行为而非穷举。选出的场景应同时满足两个条件① 真实引用了被改动代码② 在 UI 中可导航到达可见保证后续能通过浏览器实际执行。兜底搜索rg关键词检索当上述结构化路径无法快速定位时route-finding.md建议使用rg进行关键词搜索搜索面包括被改动的组件、钩子或逻辑名component / hook / logic name例如改动useDashboardItems就搜useDashboardItems附近的urls.引用在引用方源码中顺藤摸瓜找到对应的urls.*调用字面路由字符串如/data-management/actions这种直接字符串产品清单的routes与treeItems条目manifest.tsx中的routes直接给 URLtreeItemsMetadata/treeItemsNew如 manifest.tsx则揭示该页面在侧边导航中的位置有助于确认页面是否可见、如何从 UI 进入。兜底搜索的边界同样清晰短暂搜索后仍无法明确路由映射时不要靠猜转入下一节的coverage_gap机制。兜底机制coverage_gap与动态路由占位符无法映射时记录coverage_gap如果经过上述步骤含rg兜底仍无法确定路由文档要求记录一个coverage_gap目标coverage gap target并说明哪个文件无法映射which file could not be mapped检查了哪些上下文what context was checked例如查过哪些导入、搜过哪些关键词、核对过哪些清单条目。coverage_gap在 QA 流程中属于与browser、visual并列的测试用例类型参见 .agents/skills/qa-frontend/SKILL.md 中测试计划的kind: browser|visual|coverage_gap它允许 QA 如实报告未能覆盖而不是用猜测的路由制造虚假的测试结果。这是整套方法论中证据优先、杜绝臆造精神的最直接体现。动态路由保留占位符不臆造 ID文档对动态路由给出两条明确纪律不为动态路由臆造 IDDo not fabricate IDs for dynamic routes在测试计划中保留:id、:runId、:sourceId等占位符形式不要编造一个可能不存在的对象 ID用现有对象或最小安全本地数据需要真实参数时优先从 UI 中选取已存在的对象仅当确有必要时才创建最小的安全本地数据minimal safe local data来驱动测试。结合scenes.ts源码可以看到这类占位符的实际形态urls.dashboard(:id)、urls.experiment(:id, :formMode)、urls.replaySingle(:id)、urls.site(:url)等路由键中的:xxx段就是 kea-router 待解析的运行时参数测试计划中应保持这种模板化写法。实战速查五步定位工作流将全文方法论收敛为可直接执行的五步判定文件归属改动在frontend/src/scenes/下走 Core App 流程在products/product/frontend/下走 Product 流程在共享目录则先搜导入再选场景核心场景溯源appScenes.ts找场景导入 →scenes.ts找Scene.Name路由条目与配置提取路由表达式优先取scenes.ts路由表中的urls.*表达式或字面字符串动态参数保留:id等占位符产品场景溯源读products/product/manifest.tsx匹配scenes导入取routes条目必要时参考treeItems确认导航入口兜底与记录仍无结果则用rg搜组件名、urls.引用、字面路由与清单条目再无法映射则记录coverage_gap说明未映射文件与已检查上下文绝不猜 ID。结语PostHog 的路由体系将URL 构造urls、路由注册routes、场景加载appScenes/产品manifest.scenes三件事分层解耦route-finding.md的定位方法论正是对这一分层结构的逆向运用。对前端 QA 而言坚持读代码、取表达式、留占位符、如实报告覆盖缺口四条纪律既能显著提升路由定位的准确率也能保证每个测试用例都有真实可执行、可复现的落点让 QA 结果经得起审阅。【免费下载链接】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），仅供参考