Pinpoint Web 前端 PR 前 QA 关卡构建、测试与行为回归检查完整指南【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint导读本文讲解 Pinpoint 仓库中为 Web 前端 v3 定制的PR 前 QA 关卡qa-pr技能——一套在提交或推送前强制执行的构建、测试与行为回归检查流程。它服务于 Pinpoint APM 的 React 19 前端监控面板ServerMap 拓扑、散点/热力图、事务列表、Inspector 等。读完本文你将掌握如何用「变更识别 → 构建测试 → 行为 QA → Pinpoint 专项回归 → 判定输出」五步流程把线上缺陷拦截在合入之前并能理解每步检查背后对应的源码实现与项目架构依据。一、这份文档是什么定位、触发时机与执行者qa-pr是定义在 qa-pr/SKILL.md 中的一条 Claude Code 技能Skill其定位在文档头部声明得很清楚Pinpoint 프론트엔드 PR 전 QA 게이트. 빌드/테스트를 실행하고 변경된 코드에 대한 동작 QA를 수행합니다. 커밋하거나 PR을 올리기 전에 반드시 이 스킬을 먼저 실행하세요.Pinpoint 前端 PR 前 QA 关卡执行构建/测试并对变更代码做行为 QA。提交或提 PR 前必须先执行本技能。三个关键事实触发时机是强制的文档规定커밋하거나 푸시하기 전에 반드시 실행하세요提交或推送前必须执行并且QA 판정이 FAIL이면 문제를 해결하기 전까지 커밋하지 마세요判定为 FAIL 时在问题解决前不得提交。这条规则不是孤立的——项目级的 CLAUDE.md 中절대 위반 금지 규칙绝对不可违反的规则第 2 条同样写明커밋/푸시 전에 반드시 /qa-pr 스킬을 실행하세요git-workflow.md 也在커밋 전 QA 게이트一节重复了同样的要求。也就是说qa-pr是整个仓库 Git 工作流中不可绕过的质量闸门。执行主体是专用 Agent该技能通过.claude/agents/qa-engineer/qa-engineer.md中定义的qa-engineer代理执行并要求 QA 过程遵循该代理的思维方式、检查清单与输出格式。qa-engineer的角色描述是Pinpoint Frontend QA 전문가Pinpoint 前端 QA 专家它以测试者而非开发者的视角思考目标是프로덕션에 버그가 도달하기 전에 발견在缺陷进入生产环境之前发现。服务于真实前端代码库被检查的对象是 Pinpoint Web Frontend v3——README.md 所述的 React 19 单仓库monorepo包含apps/web主应用与packages/ui、packages/scatter-chart、packages/server-map、packages/datetime-picker四个核心包。二、第 1 步摸清变更范围QA 的第一步永远是先知道改了什么。技能要求执行以下两条命令git diff upstream/master --name-only git diff upstream/master --stat--name-only列出本次变更涉及的全部文件路径用于确定 QA 的检查范围--stat给出每个文件的增删行数统计用于评估改动规模与风险集中点。随后需要列出所有变更文件并总结修改内容。这一步的意义在于后续所有构建、测试与行为检查都要围绕这批文件展开而不是对全仓库做无差别回归。与这条命令配套的仓库约定是变更分支必须基于最新的upstream/master创建见 git-workflow.md 的强制分支工作流因此git diff upstream/master恰好能覆盖本次 PR 相对主干的全部差异。三、第 2 步构建与测试——第一道自动化关卡技能要求在识别变更后按顺序执行yarn build yarn test并且明确规定失败时立即停止并上报禁止在构建或测试失败的状态下提交실패 시 즉시 중단하고 보고하세요. 빌드나 테스트 실패 상태에서는 커밋하지 마세요。要理解这两条命令到底检查了什么需要看根目录 package.json 的脚本定义与 CLAUDE.md 的说明命令实际执行作用yarn buildyarn workspace pinpoint-fe/web buildTypeScript 严格模式类型检查 Vite 生产构建。CLAUDE.md 明确指出TypeScript가 첫 번째 QA 게이트TypeScript 是第一道 QA 关卡yarn testyarn workspaces run test遍历全部 workspace 包packages/*、apps/*执行各自的单元测试针对不同粒度仓库还提供了细化的测试命令# 只跑某个包 yarn workspace pinpoint-fe/ui test # 只跑某个测试文件 yarn workspace pinpoint-fe/ui jest path/to/file.test.ts测试规范见 rules/testing.md采用 Jest ts-jest preset jsdom 环境测试文件与源码同目录存放*.test.ts/*.test.tsx模块别名pinpoint-fe/ui/src/*解析到rootDir/src/*。另外仓库还维护了一组基于 Playwright 的 E2E 测试yarn workspace pinpoint-fe/web test:e2e每个页面都有对应的用例文件例如servermap.e2e.test.ts、scatterFullScreen.e2e.test.ts、transactionList.e2e.test.ts、inspector.e2e.test.ts位于 packages/ui/e2e/test它们与后续第 4 步的 Pinpoint 专项回归检查互为印证。qa-engineer代理对这两步的期望是分别报告构建与测试的通过/失败状态及错误输出——각각의 통과/실패 여부와 오류 출력을 보고합니다。四、第 3 步行为 QA——对变更代码做功能分析构建和测试通过只代表类型没错、既有断言没破并不代表功能真的对。第 3 步要求对每个变更的组件component、Hook、页面page做四轮功能分析。3a. 正向路径Happy Path正常数据下期望的行为是什么实现是否符合该期望追踪用户动作 → 状态变更 → UI 更新的完整链路。这条链路在qa-engineer的知识库中被明确为项目级数据流模式사용자 액션 → 아톰 업데이트 → React Query 리페치 → UI 업데이트 用户动作 → Jotai 原子更新 → React Query 重新拉取 → UI 更新见 qa-engineer.md 的데이터 흐름一节。文档特别提醒이 체인의 어느 링크라도 끊어지면 기능이 손상됨——这条链上任何一环断裂功能即告损坏。因此正向路径检查不是点一下看看而是沿着这条链逐环验证。3b. 边界情况Edge Cases对变更的 UI 组件逐项核对以下五个检查点空/null 数据API 返回空数组或 null 时渲染什么加载状态是否显示骨架屏/转圈动画快速加载时会不会闪烁错误状态API 失败/网络错误时是否向用户展示错误边界值日期范围、分页上限、大数据集。并发请求快速连点、多标签页切换。qa-engineer针对 Pinpoint 场景进一步细化了七条必须检查的特有边界这是第 3b 节检查清单在 Pinpoint 语境下的落地未选择应用application多数页面依赖已选应用未选择时渲染什么空时间范围from to或无效日期范围。无数据API 返回[]或{}——是否有正确的空状态大数据量ServerMap 超过 100 个节点、事务列表超过 1000 条——能否不崩溃地渲染快速导航页面间快速点击——过期请求与竞态条件。并发 API 调用多个 Hook 同时执行——加载/错误状态是否正确配置未加载configurationAtom填充完成之前页面就完成渲染。第 7 条对应的正是 InitialFetchOutlet.tsx 的职责它在渲染子路由之前先通过useGetConfiguration拉取配置并写入configurationAtomdata或configuration尚未就绪时直接返回null不渲染子页面从而避免配置未到、页面先画的错位配置拉取失败则navigate(APP_PATH.API_CHECK)重定向到/apiCheck检查页。3c. 状态完整性State IntegrityURL 参数是否正确反映 UI 状态from/to、application。页面刷新后状态是否保持URL 是真相的唯一来源。原子atom状态在页面导航之间是否泄漏确认清理逻辑。React Query 缓存在 mutation 之后是否还显示旧数据。这四条在源码里都有直接对应物URL 即真相searchParametersAtom见 atoms/searchParameters.ts保存application与searchParameters键值对而它的写入发生在InitialFetchOutlet的useEffect中——由useLocation()的pathname/search解析而来且依赖数组只含applicationName、serviceType、to、from四个字段。这就在结构上保证了URL 参数变化 → 原子更新的单向同步。导航间原子不泄漏InitialFetchOutlet用key{requestService}强制页面子树在 service 变化时整体 remount但qa-engineer的함정陷阱章节专门提醒아톰은 화면 remount로 지워지지 않는다原子不会随页面 remount 被清空——key只重置组件 state跨 service 的选择类原子如serverMapCurrentTargetAtom必须显式清理否则会带着上一个 service 的选择发请求。缓存不过期React Query 是所有服务端数据的获取层mutation 后需要使相关 queryKey 失效否则 UI 会继续展示旧数据。3d. 组件交互Component Interaction变更后的 props 是否满足所有父组件的调用点。事件处理器是否正确触发、且不会产生重复动作。无无限重渲染循环原子依赖变更、不稳定引用。qa-engineer总结了四条真实踩过的交互陷阱直接为这三个检查点提供判据陷阱现象判据不稳定的原子引用Object.fromEntries(searchParams)每次渲染都产生新对象直接放进useEffect依赖数组会触发无限循环清理函数缺失无清理的useEffect内存泄漏、陈旧回调渲染期间调用navigate()在 render 阶段直接调用路由跳转必须放进useEffect内部类型断言不一致Configuration Recordstring, string与Recordstring, unknown混用检查每个页面是否使用正确的 cast五、第 4 步Pinpoint 专项回归检查这是整套 QA 流程中最具项目特色的部分——四项针对 Pinpoint 核心页面的回归检查application/from/to 变更时ServerMap 仍能正常渲染ServerMap 是依赖 Cytoscape dagre 布局绘制的应用依赖拓扑图见 packages/server-map任何涉及查询参数、service 或路由的改动都可能影响它的数据加载。变更代码附近的散点图交互拖选、点击仍然可用散点图是基于 Canvas 的独立实现 packages/scatter-chart其拖拽选时间范围是 Pinpoint 核心交互之一。事务列表 / Inspector 导航未被破坏事务列表与 Inspector 页面的路由与查询参数联动是高频回归区。基于配置的功能仍然正确读取配置例如experimental.enableServiceMap这类由配置驱动的开关改动后必须确认开关读取逻辑没被破坏。这四项的深层依据散落在仓库的架构规则中。以配置驱动功能为例rules/service-map.md 记录了严格约定配置开关只能经由唯一入口useEnableServiceMap()屏幕内与getEnableServiceMap()渲染外读取严禁在业务代码里直接读configuration?.[experimental.enableServiceMap.value]——直接读取会导致屏幕显示与请求头携带的 service 不一致这类类型检查抓不住的错位。QA 在第 4 步检查설정 기반 기능이 여전히 설정을 올바르게 확인함配置驱动功能仍正确读取配置时依据的正是这套约定。同时仓库 E2E 测试目录packages/ui/e2e/test中按页面组织的servermap、scatterFullScreen、transactionList、inspector、realtimeServerMap、filteredMap等用例正好覆盖了本步的四项检查对象可以作为自动化补充。六、第 5 步输出回归摘要与 QA 判定完成全部检查后必须输出结构化回归摘要包含五项内容变更文件数量与清单执行的测试通过/失败构建通过/失败发现的行为问题按严重度列出QA 判定✅ PASS / ❌ FAIL / ⚠️ PASS WITH WARNINGS判定为 FAIL 或 PASS WITH WARNINGS 时必须列出合入前需要完成的具体整改动作。七、判定标准的支撑qa-engineer 的严重度分级与报告格式qa-pr技能要求 QA 过程遵循qa-engineer的检查清单与输出格式其中最重要的支撑是严重度三分法见 qa-engineer.md级别含义典型情形处理要求Critical阻断 PR功能完全不可用数据丢失或展示错误数据未捕获异常/白屏无限循环或内存泄漏必须修复Warning尽量在合入前修复空状态未处理只剩空白无加载状态UX 差正常使用中出现控制台报错用any掩盖真实类型问题的 cast建议修复Suggestion可转后续 Issue边界情况缺测试覆盖性能隐患不必要重渲染可访问性问题缺 aria 属性记录跟进QA 报告的输出格式也有明确规定분석된 변경 사항 / 빌드 / 테스트 / 발견 사항(Critical·Warning·Suggestion) / 판정五段式并且强调必须具体——파일 경로와 라인 번호를 포함하세요. 문제를 일으킬 수 있음 같은 모호한 표현은 사용하지 마세요必须包含文件路径与行号禁止使用可能引发问题这类模糊表述。qa-engineer的思考方式本身也值得 QA 执行者内化——它假定버그가 존재한다고 가정缺陷必然存在验证前不做无缺陷判断、구현이 아닌 동작을 테스트测试行为而非实现、사용자 관점에서 사고站在用户视角、회귀에 집중改动前能用的改动后必须还能用。这四条与qa-pr的五步流程构成了完整的态度 方法 输出闭环。八、把 QA 关卡嵌入日常提交流程qa-pr不是孤立的检查动作而是仓库 Git 工作流的一环。结合 git-workflow.md完整流程是提交前先确认分支git branch --show-current若在master上立即中止按git fetch upstream master git checkout -b branch-name upstream/master创建新分支——仓库规定任何情况都不允许直接向 master 提交。执行/qa-pr跑完上面五步判定为 FAIL 就停下修复。通过后做自检重读全部变更代码查逻辑正确性、排查console.log等调试残留、确认代码风格、追踪被改代码的调用方与消费方确认兼容、再次yarn build与yarn test确认通过。提交与推送commit message 使用[#issue_number] Description格式例如[#9520] Preserve timestamp during server map loading推送前先git rebase upstream/master。环境前提仓库要求 Node 22.13.1、Yarn 1.22.22见 package.json 的engines与packageManager字段。除 QA 用到的build/test外日常开发还有yarn devVite 开发服务器端口 3000/api/*代理到localhost:8080、yarn lint、yarn clean等命令可供配合使用。九、相关文件索引用途仓库路径qa-pr技能本体web-frontend/src/main/v3/.claude/skills/qa-pr/SKILL.md执行代理qa-engineerweb-frontend/src/main/v3/.claude/agents/qa-engineer/qa-engineer.md项目级规则含 /qa-pr 强制要求web-frontend/src/main/v3/.claude/CLAUDE.mdGit 工作流与提交前自检web-frontend/src/main/v3/.claude/rules/git-workflow.md测试框架与模式约定web-frontend/src/main/v3/.claude/rules/testing.md配置驱动功能enableServiceMap回归要点web-frontend/src/main/v3/.claude/rules/service-map.mdURL → 原子同步的关键组件web-frontend/src/main/v3/apps/web/src/components/Layout/InitialFetchOutlet.tsx查询参数原子定义web-frontend/src/main/v3/packages/ui/src/atoms/searchParameters.ts根脚本build/test 定义web-frontend/src/main/v3/package.json按页面的 E2E 用例web-frontend/src/main/v3/packages/ui/e2e/test总结qa-pr是一条自动化检查 行为分析 项目专项回归 结构化判定的完整 PR 质量关卡。对维护者而言它是防止回归的守门员对贡献者而言它是把提交做扎实的检查清单。任何触碰 Pinpoint Web 前端的改动都值得在提交前按这套五步流程完整走一遍——尤其是第 4 步的 ServerMap、散点图、事务列表与配置开关回归它们正是这个 APM 监控面板最核心、也最容易悄悄出问题的部分。【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
