修复 Flows/CDF 前端应用性能问题时使用（重渲染…

当 Flows/CDF 应用出现卡顿、重渲染、慢查询、包体积过大或内存泄漏时，用「先测基线→逐项定位并直接改代码→再测增量」的流程系统性修复性能问题。

适用场景

解决思路

1. 动手前先跑 `pnpm run build` 和 `pnpm run preview`，在 Chrome 中打开应用，记录 Lighthouse 性能分数，并用 React DevTools Profiler 录制一次交互，记下渲染时间最长和渲染次数最多的组件；记录基线数字，之后每个修复都与之对比。
2. 从 `src/App.tsx` 开始读组件树，用 `grep -rn --include="*.tsx" -E "value=\{\{|onClick=\{\(\)" src/` 搜索内联对象/数组与内联事件处理器模式。
3. JSX 内联对象/数组改用 `useMemo` 包裹（如 `const chartOptions = useMemo(() => ({ color: "red" }), []);` 后再传给 `<Chart options={chartOptions} />`），避免每次渲染产生新引用导致子组件重渲染。
4. 每次渲染都重建的事件处理器改用 `useCallback` 包裹（如 `const handleClick = useCallback(() => doSomething(id), [id]);`）。
5. Context value 每次渲染都变时用 `useMemo` 记忆化（如 `const ctxValue = useMemo(() => ({ user, sdk }), [user, sdk]);`）再传给 Provider。
6. 对接收稳定 props 的纯展示组件加 `React.memo`，但只加给 Profiler 确认存在不必要重渲染的组件，不要无差别包裹所有组件。
7. 用 `grep -rn --include="*.ts" --include="*.tsx" -E "instances\.(list|search|query|aggregate|retrieve)" src/` 以及针对 `.(assets|timeseries|events|files|sequences|relationships).(list|search|retrieve)` 的 grep 找出所有 DMS 实例 API 调用。
8. 读多写少的场景优先走 search/Elasticsearch 路径（`instances.query`/`instances.search`），不要用压 Postgres 的 `list`；把读密集 UI（表格、下拉、搜索结果）里的 `instances.list` 改写成等价的 `instances.query`，保留原过滤逻辑但改成 with/nodes/filter/limit/select 的 query 写法。
9. API 选择原则：`instances.query` 用于能映射到 Elasticsearch 的过滤读取（text、equals、range）；`instances.search` 用于全文/模糊搜索；`instances.retrieve` 用于按已知 external ID 取数；`instances.aggregate` 用于计数/直方图；`instances.list` 只在写入、同步或 query/search 无法表达语义时使用，若是读密集 UI 展示就改写成 `instances.query`。
10. 若工作区有 `semantic-knowledge/` 目录，查阅其中关于 search vs relational 路径、基数与物化取舍的说明。
11. LLM 硬性 gate：用 `grep -rn --include="*.ts" --include="*.tsx" -E "chat\.completions|agents/chat|useAtlasChat|openai|anthropic" src/` 检查；禁止对 DMS 行逐条 map 调用 completions，改为一次 `sendAgentMessage` 或 agent 资源（`integrate-fusion-agent`）；若必须逐条调用，上限 5、硬上限 50，按 `space:externalId:lastUpdatedTime` 缓存，且只能由用户主动触发。
12. 用 grep 找出数据拉取后的客户端过滤：`grep -rn --include="*.ts" --include="*.tsx" -B 5 "\.filter(" src/ | grep -B 5 "data\|items\|result\|response\|nodes"`，以及 `grep -rn --include="*.ts" --include="*.tsx" -E "\.(map|reduce|find|some|every)\(" src/hooks/ src/services/ src/api/`。
13. 把客户端 `.filter()` 的逻辑搬进 SDK 调用的 `filter` 参数（用 `and` 组合已有过滤条件），然后删掉 `.filter()` 调用。
14. 客户端过滤的具体修法：SDK 调用后对全量结果 `.filter()` → 移进请求的 `filter` 参数；DMS 查询缺少 properties 选择 → 加 `sources`/`properties` 只取需要的字段；先取全部再渲染子集 → 在 API 调用加 `limit` 和 `filter`；对已取数组做文本搜索 → 改用 SDK 的 `search` 端点。
15. 硬性规则：只要 API 支持该过滤条件，就立刻移到服务端；仅对极小本地状态（如缓存的 10 条用户偏好）允许客户端过滤；若 API 不支持该过滤，必须加代码注释说明原因。
16. 读所有 CDF SDK 调用（搜 `sdk.`、`client.`、`useQuery`、`useCogniteClient`），用 `(nextCursor|cursor|hasNextPage|fetchNextPage|offset|skip|page)` 和 `while.*cursor|while.*hasMore|while.*nextPage` 找出分页与全量拉取模式。
17. 分页/取数修法：未设 `limit` → 加 `limit: 100`（或实际页大小）；取了全部属性 → 加 `properties` 过滤只取必需字段；每次渲染都取数 → 移入 `useQuery`/`useMemo` 并保持依赖数组稳定；可并行却串行的请求 → 改成 `Promise.all` 或批量 SDK 方法；缺 `limit` → 按 UI 页大小（25/50/100）显式设置；大数据集用 offset 分页 → 换成基于 `nextCursor` 的 cursor 分页；fetch all 循环 → 用 TanStack Query 的 `useInfiniteQuery` 按需分页。
18. 把 while 循环一次性拉全量的写法替换为 `useInfiniteQuery`：`queryFn` 用 `pageParam` 作 cursor，`getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined`，并设置 `staleTime: 30_000`。
19. 把 offset 分页（`{ limit: 100, offset: page * 100 }`）换成 cursor 分页（`{ limit: 100, cursor: nextCursor }`）。
20. 用 grep 检查 API 调用频率：搜含 search/filter/query 的 `onChange|onInput|onSearch|onFilter` 输入、`debounce|useDebouncedValue|useDebounce`、`setInterval|refetchInterval|pollingInterval|refetchOnWindowFocus`、以及 `staleTime|cacheTime|gcTime|refetchOnMount|refetchOnWindowFocus`。
21. 搜索输入每次按键都发请求 → 加 `useDebouncedValue`（默认 300ms 延迟），把 debounced 值放进 `queryKey`，并用 `enabled: debouncedSearch.length > 0` 控制触发时机。
22. `useQuery` 没有 staleTime → 加 `staleTime: 30_000`（或合适值），避免每次挂载/窗口聚焦都重新取数。
23. 轮询间隔过短或无退避 → 把间隔设为 ≥30s，出错时指数退避；昂贵查询的 `refetchOnWindowFocus: true` → 改成 `false` 或加长 staleTime。
24. 多个组件重复发起相同并行请求 → 把 query 提升为共享 hook（如 `hooks/useAssets.ts` 导出 `useAssets()`），两个组件都从该 hook 导入。
25. 用 `grep -rn --include="*.tsx" -E "\.(map|forEach)\(" src/` 找列表渲染；对数据源可能超过 50 条的列表，把普通 `.map()` 换成虚拟化列表。
26. 若未安装先执行 `pnpm add @tanstack/react-virtual`，然后用 `useVirtualizer`（`count`、`getScrollElement` 返回容器 ref、`estimateSize: () => 48`）渲染：外层容器设固定高度与 `overflow: auto`，内层设 `getTotalSize()` 高度与 `position: relative`，每行绝对定位并用 `transform: translateY(${virtualRow.start}px)` 定位。
27. 读路由配置，找出首屏未展示却静态导入的重页面，改成 `React.lazy(() => import("./pages/ReportPage"))`，并在路由处用 `<Suspense fallback={<PageSkeleton />}>` 包裹。
28. 体量大的第三方组件（图表库、PDF 查看器、地图渲染器）不要做模块级导入，改为在需要它的组件内部动态 `import()`。
29. 用 `pnpm add -D rollup-plugin-visualizer` 安装可视化插件，临时在 `vite.config.ts` 中加入 `visualizer({ open: true, gzipSize: true, brotliSize: true })`，跑 `pnpm run build` 查看 treemap。
30. 对 gzip 后 >100 KB 且非必要首屏依赖的 chunk 做处理：完整 `lodash` → 改用 `lodash-es` 单函数导入或原生实现（`Array.prototype.map`、`Object.entries`、`structuredClone`）；`moment` → 改用 `date-fns` 或原生 `Intl.DateTimeFormat`；图表库未 tree-shake → 改用具名导入（如 `import { LineChart } from "echarts/charts"`）；只在某一处用的大库 → 用 `React.lazy` 或内联 `import()` 动态导入。
31. 分析完成后从 `vite.config.ts` 移除 visualizer 插件并执行 `pnpm remove rollup-plugin-visualizer`。
32. 用 `grep -rn --include="*.tsx" --include="*.ts" -A 10 "useEffect" src/` 找出 useEffect 中的订阅、定时器、事件监听；对每个 `addEventListener`、`setInterval`、`setTimeout`、`subscribe` 或 CDF streaming 连接补上 cleanup 函数。
33. 内存泄漏修法：无中止的 fetch → 加 `AbortController` 并在 cleanup 里 `controller.abort()`；定时器无清理 → return `clearInterval(id)`/`clearTimeout(id)`；事件监听无清理 → return `window.removeEventListener(...)`。
34. 修复后重跑 Step 1 相同的 Lighthouse 审计和 React Profiler，用表格报告 Before/After/Change（Lighthouse 性能分、LCP、Total Blocking Time、gzip 包体积、某组件在筛选变化时的渲染次数），并列出所有改动文件。
35. 若某一步没有带来改善，明确说明；不要编造数字。
36. 结束时列出每个改动文件的绝对路径和一行修复说明；若进一步提升需要服务端或基础设施改动（如 CDF 响应缓存、CDN 配置），单独标注为超范围建议。

适用边界 · 注意事项

• 目标是 Flows/CDF 应用之外的普通前端项目时不适用（依赖 CDF/DMS SDK 与 `instances.query`/`instances.search` 等 API）。
• 未先测量基线前不要盲目套用这些优化（技能要求先测基线、再改、再测增量）。
• 尚未用 Profiler 确认存在不必要重渲染时，不要无差别给所有组件加 `React.memo`。