@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/settings/personal-team/account/__tests__/account-client.test.tsx

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// account-client 头像持久化竞态回归（TanStack 优化任务 12）。
+//
+// 旧实现在 updateAvatarFn 成功后才 setQueryData(['session']) 合并头像字段，
+// 且成功路径无 invalidate、无 cancelQueries：mutation 前已在途的 session
+// refetch（useSession staleTime 0 + refetchOnMount，挂载/聚焦频发）若在成功
+// 写缓存之后才 resolve，会把会话缓存写回保存前的旧值——头像字段丢失成永久
+// 回退。迁移为官方三段式后：onMutate cancelQueries + 快照 + 乐观合并、
+// onError 回滚 + toast、onSettled invalidate 对齐服务端真相。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('@/server/serverFns/user/avatar', () => ({
+  updateAvatarFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/auth/email-verification', () => ({
+  getEmailVerifiedStatusFn: vi.fn(),
+  resendVerificationEmailFn: vi.fn(),
+}))
+vi.mock('@/components/shared-kit/auth/auth-client', () => ({
+  useSession: vi.fn(() => ({ data: { user: { id: 'u1' } } })),
+}))
+
+import AccountClient from '../account-client'
+import { updateAvatarFn } from '@/server/serverFns/user/avatar'
+import { getEmailVerifiedStatusFn } from '@/server/serverFns/auth/email-verification'
+import { m } from '@/paraglide/messages.js'
+
+type SessionValue = { user?: Record<string, unknown> } | null
+
+const sessionBase: SessionValue = { user: { name: '旧名字', email: 'u@example.com' } }
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+/** 与 AccountClient 同 provider 的探针：制造可被 mutation 取消的在途 session refetch */
+function SessionProbe({ queryFn }: { queryFn: () => Promise<SessionValue> }) {
+  useQuery({ queryKey: ['session'], queryFn })
+  return null
+}
+
+const clients: QueryClient[] = []
+
+function renderAccount(queryFn: () => Promise<SessionValue>) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  })
+  clients.push(client)
+  render(
+    <QueryClientProvider client={client}>
+      <SessionProbe queryFn={queryFn} />
+      <AccountClient
+        initialAvatarConfig={null}
+        initialBgShape="square"
+        initialBgColor="#7c3aed"
+        user={{ name: '旧名字', email: 'u@example.com', createdAt: null }}
+      />
+    </QueryClientProvider>,
+  )
+  return client
+}
+
+const readAvatar = (client: QueryClient) =>
+  (client.getQueryData<SessionValue>(['session'])?.user?.avatarConfig ?? null) as
+    | Record<string, unknown>
+    | null
+
+beforeEach(() => {
+  // shouldAdvanceTime：让 RTL waitFor 的轮询 timer 走真实节奏；调度确定性仍由显式 advance 控制
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+  vi.mocked(updateAvatarFn).mockResolvedValue(undefined as never)
+  vi.mocked(getEmailVerifiedStatusFn).mockResolvedValue({ verified: true })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  // reset 而非 clear：mockClear 不清 mockImplementationOnce 队列，会泄漏到下一用例
+  vi.resetAllMocks()
+  clients.length = 0
+})
+
+describe('AccountClient 头像会话乐观更新（官方 onMutate 通道）', () => {
+  it('保存成功后在途 session refetch 迟到返回旧会话不覆盖头像字段，终态保留新值', async () => {
+    let sessionCalls = 0
+    const call2 = deferred<SessionValue>()
+    type UpdateAvatarResult = Awaited<ReturnType<typeof updateAvatarFn>>
+const mutation = deferred<UpdateAvatarResult>()
+    const call3 = deferred<SessionValue>()
+
+    vi.mocked(updateAvatarFn).mockImplementation(() => mutation.promise)
+
+    const client = renderAccount(() => {
+      sessionCalls++
+      if (sessionCalls === 1) return Promise.resolve(sessionBase)
+      if (sessionCalls === 2) return call2.promise
+      return call3.promise
+    })
+
+    await waitFor(() => expect(client.getQueryData(['session'])).toEqual(sessionBase))
+
+    // mutation 前触发一次 session refetch（在途、延迟返回保存前的旧会话）
+    void client.invalidateQueries({ queryKey: ['session'] })
+    await waitFor(() => expect(sessionCalls).toBe(2))
+
+    // 保存资料 → persistAvatar → 乐观合并头像字段进 session 缓存
+    fireEvent.click(screen.getByRole('button', { name: m.settings_profile_saveChanges() }))
+    await waitFor(() => expect(updateAvatarFn).toHaveBeenCalledTimes(1))
+    await waitFor(() => expect(readAvatar(client)).not.toBeNull())
+
+    // 服务端确认 → onSettled invalidate → 拉取服务端真相
+    await act(async () => {
+      mutation.resolve({ avatarConfig: null, bgShape: null, bgColor: null })
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    await waitFor(() => expect(sessionCalls).toBe(3))
+
+    // 竞态核心断言：在途 refetch 此刻才 resolve 保存前的旧会话（canceled，不得覆盖）
+    await act(async () => {
+      call2.resolve(sessionBase)
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    expect(readAvatar(client)).not.toBeNull()
+
+    call3.resolve({ user: { ...sessionBase.user, avatarConfig: { seed: 'x' }, bgColor: '#7c3aed' } })
+    await waitFor(() => {
+      expect(client.getQueryData<SessionValue>(['session'])?.user?.avatarConfig).toEqual({ seed: 'x' })
+    })
+  })
+
+  it('保存失败回滚快照（session 缓存不残留乐观头像字段）', async () => {
+    let sessionCalls = 0
+    const mutation = deferred<never>()
+    const truth = deferred<SessionValue>()
+    vi.mocked(updateAvatarFn).mockImplementation(() => mutation.promise as never)
+
+    const client = renderAccount(() => {
+      sessionCalls++
+      if (sessionCalls === 1) return Promise.resolve(sessionBase)
+      return truth.promise
+    })
+
+    await waitFor(() => expect(client.getQueryData(['session'])).toEqual(sessionBase))
+
+    fireEvent.click(screen.getByRole('button', { name: m.settings_profile_saveChanges() }))
+    await waitFor(() => expect(updateAvatarFn).toHaveBeenCalledTimes(1))
+    // onMutate 已乐观合并头像字段（mutation 挂起期间可观测）
+    await waitFor(() => expect(readAvatar(client)).not.toBeNull())
+
+    // 失败 → onError 回滚快照，乐观字段不留残留
+    mutation.reject(new Error('boom'))
+    await waitFor(() => expect(readAvatar(client)).toBeNull())
+
+    // onSettled invalidate 以服务端真相收尾
+    await waitFor(() => expect(sessionCalls).toBe(2))
+    truth.resolve(sessionBase)
+    await waitFor(() => {
+      expect(client.getQueryData<SessionValue>(['session'])).toEqual(sessionBase)
+    })
+  })
+})

package/src/components/settings/personal-team/account/account-client.tsx

@@ -29,7 +29,7 @@ import { useState, useCallback } from "react"
 import { type AvatarConfig, getRandomConfig } from "@/lib/avatar/avatar-config"
 import type { ShapeType } from "@allbluecn/kernel"
 import { toAvatarShape } from "@/components/shared-kit/avatars/avatar-shape"
-import { useQueryClient } from "@tanstack/react-query"
+import { useMutation, useQueryClient } from "@tanstack/react-query"
 import { updateAvatarFn } from "@/server/serverFns/user/avatar"
 import { toast } from '@/components/ui/toast'
 import { formatDate } from "@/lib/datetime"
@@ -59,17 +59,54 @@ export default function AccountClient({
   const [bgColor, setBgColor] = useState(initialBgColor)
   const queryClient = useQueryClient()
   const timezone = useTimezone()
-  const persistAvatar = useCallback(async (config: AvatarConfig, shape: string, color: string) => {
-    try {
-      await updateAvatarFn({ data: { avatarConfig: config, bgShape: toAvatarShape(shape) ?? "square", bgColor: color } })
+  // 官方乐观更新三段式（TanStack Query Optimistic Updates 指南）：
+  // onMutate —— cancelQueries 取消在途 session refetch（useSession staleTime 0 且
+  //             refetchOnMount，挂载/聚焦常触发；防其迟到返回保存前的旧会话把刚写入
+  //             的头像字段冲掉——旧实现成功写缓存后无 invalidate，被覆盖即成永久回退）+
+  //             快照 + 乐观写；onError —— 回滚快照 + toast；onSettled —— invalidate
+  //             对齐服务端真相（失败路径同样兜底纠偏）。
+  // ['session'] 内联字面量与 auth-client.ts 的 useSession / user-menu 的 resetQueries 同键，
+  // 该 key 尚无 queryOptions 工厂（收敛属查询键治理任务，不在本任务范围）。
+  const persistAvatarMutation = useMutation({
+    mutationFn: (vars: { config: AvatarConfig; shape: string; color: string }) =>
+      updateAvatarFn({
+        data: {
+          avatarConfig: vars.config,
+          bgShape: toAvatarShape(vars.shape) ?? "square",
+          bgColor: vars.color,
+        },
+      }),
+    onMutate: async (vars) => {
+      await queryClient.cancelQueries({ queryKey: ['session'] })
+      const previousSession = queryClient.getQueryData<{
+        user?: Record<string, unknown>
+      } | null>(['session'])
       queryClient.setQueryData(['session'], (old: { user?: Record<string, unknown> } | null) =>
-        old ? { ...old, user: { ...old.user, avatarConfig: config, bgShape: shape, bgColor: color } } : old,
+        old
+          ? { ...old, user: { ...old.user, avatarConfig: vars.config, bgShape: vars.shape, bgColor: vars.color } }
+          : old,
       )
-    } catch (err) {
+      return { previousSession }
+    },
+    onError: (err, _vars, ctx) => {
+      if (ctx?.previousSession !== undefined) {
+        queryClient.setQueryData(['session'], ctx.previousSession)
+      }
       console.error("Failed to persist avatar:", err instanceof Error ? err.message : String(err))
       toast.error(m.settings_profile_avatarSaveFailed())
+    },
+    onSettled: () => {
+      void queryClient.invalidateQueries({ queryKey: ['session'] })
+    },
+  })
+
+  const persistAvatar = useCallback(async (config: AvatarConfig, shape: string, color: string) => {
+    try {
+      await persistAvatarMutation.mutateAsync({ config, shape, color })
+    } catch {
+      // onError 已 toast + 回滚；维持既有「保存失败不阻断后续成功 toast」行为
     }
-  }, [queryClient])
+  }, [persistAvatarMutation])
 
   const handleSaveAvatar = async (config: AvatarConfig, newBgShape: string, newBgColor: string) => {
     setAvatarConfig(config)

package/src/components/settings/personal-team/team/team-client.tsx

@@ -20,9 +20,6 @@ import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
 import { toast } from "@/components/ui/toast"
 import { useResource } from "@/components/billing/use-resource"
 import {
-  listTeamMembersFn,
-  listTeamInvitationsFn,
-  listTeamUsersFn,
   createTeamInvitationFn,
   refreshTeamInvitationLinkFn,
   revokeTeamInvitationFn,
@@ -36,6 +33,14 @@ import {
   leaveTeamFn,
   clearExpiredInvitationsFn,
 } from "@/server/serverFns/team"
+import {
+  TEAM_INVITATIONS_QUERY_KEY,
+  TEAM_MEMBERS_QUERY_KEY,
+  TEAM_USERS_QUERY_KEY,
+  teamInvitationsQueryOptions,
+  teamMembersQueryOptions,
+  teamUsersQueryOptions,
+} from "@/lib/queries/team"
 import { Button } from "@/components/ui/button"
 import {
   Card,
@@ -85,22 +90,15 @@ export default function TeamClient({ user }: TeamClientProps) {
   const seats = useResource("seats")
   const guestSeats = useResource("guestSeats")
 
-  const { data: members = [], isLoading: membersLoading } = useQuery({
-    queryKey: ["teamMembers"],
-    queryFn: () => listTeamMembersFn(),
-  })
+  const { data: members = [], isLoading: membersLoading } = useQuery(teamMembersQueryOptions())
 
   const { data: inviteData } = useQuery({
-    queryKey: ["teamInvitations"],
-    queryFn: () => listTeamInvitationsFn(),
+    ...teamInvitationsQueryOptions(),
     enabled: members.length > 0,
   })
   const invitations = inviteData?.invitations ?? []
 
-  const { data: teamUsers = [] } = useQuery({
-    queryKey: ["teamUsers"],
-    queryFn: () => listTeamUsersFn(),
-  })
+  const { data: teamUsers = [] } = useQuery(teamUsersQueryOptions())
 
   const isOwner = members.length > 0
   const teamOwner = teamUsers.find((u) => u.seatType === "owner")
@@ -109,9 +107,9 @@ export default function TeamClient({ user }: TeamClientProps) {
   const isInAnyTeam = isOwner || isMember
 
   const invalidate = () => {
-    void qc.invalidateQueries({ queryKey: ["teamMembers"] })
-    void qc.invalidateQueries({ queryKey: ["teamInvitations"] })
-    void qc.invalidateQueries({ queryKey: ["teamUsers"] })
+    void qc.invalidateQueries({ queryKey: TEAM_MEMBERS_QUERY_KEY })
+    void qc.invalidateQueries({ queryKey: TEAM_INVITATIONS_QUERY_KEY })
+    void qc.invalidateQueries({ queryKey: TEAM_USERS_QUERY_KEY })
   }
 
   const createInviteMutation = useMutation({
@@ -278,8 +276,8 @@ export default function TeamClient({ user }: TeamClientProps) {
   const handleRefreshLink = async (expiresInDays?: number) => {
     const days = expiresInDays ?? 7
     const result = await refreshTeamInvitationLinkFn({ data: { expiresInDays: days } })
-    void qc.invalidateQueries({ queryKey: ["teamInvitations"] })
-    void qc.invalidateQueries({ queryKey: ["teamMembers"] })
+    void qc.invalidateQueries({ queryKey: TEAM_INVITATIONS_QUERY_KEY })
+    void qc.invalidateQueries({ queryKey: TEAM_MEMBERS_QUERY_KEY })
     return {
       id: result.invitationId,
       email: undefined,
@@ -369,7 +367,7 @@ export default function TeamClient({ user }: TeamClientProps) {
 
   useEffect(() => {
     if (isMember) {
-      void qc.invalidateQueries({ queryKey: ["teamUsers"] })
+      void qc.invalidateQueries({ queryKey: TEAM_USERS_QUERY_KEY })
     }
   }, [isMember, qc])
 

package/src/components/shared-kit/list-kit/__tests__/frozen-header.test.ts

@@ -18,72 +18,241 @@
 import { describe, it, expect } from "vitest";
 import { computeFrozenHeader } from "../frozen-header";
 
-// 平铺行布局（index → 行类型 → start）：
-//   0 grp0    0
-//   1 sub0   36
-//   2 story  80
-//   3 grp1  200
-//   4 sub1  236
+// 双层扁平行布局（index → 行类型 → start/size），组头/子组头高 36：
+//   0 G1     0/36      ← 内容盒坐标系原点
+//   1 S1     36/36
+//   2 row    72/84
+//   3 row   156/84
+//   4 G2    240/36
+//   5 S2    276/36
+//   6 row   312/84
 const measurements = [
-  { start: 0 },
-  { start: 36 },
-  { start: 80 },
-  { start: 200 },
-  { start: 236 },
+  { start: 0, size: 36 },
+  { start: 36, size: 36 },
+  { start: 72, size: 84 },
+  { start: 156, size: 84 },
+  { start: 240, size: 36 },
+  { start: 276, size: 36 },
+  { start: 312, size: 84 },
 ];
-const groupHeaderIndexes = [0, 3];
-const subGroupHeaderIndexes = [1, 4];
-const parentGroupOfSub = new Map<number, number>([
+const groupIndexes = [0, 4];
+const subIndexes = [1, 5];
+const parentOfSub = new Map<number, number>([
   [1, 0],
-  [4, 3],
+  [5, 4],
 ]);
 
 const compute = (scrollTop: number) =>
-  computeFrozenHeader(scrollTop, measurements, groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub);
+  computeFrozenHeader(scrollTop, measurements, {
+    groupIndexes,
+    subIndexes,
+    parentGroupOfSub: parentOfSub,
+    pad: 0,
+    subPinTop: 36,
+  });
+
+describe("computeFrozenHeader（双层：主组头 + 子组头）", () => {
+  it("首屏（scrollTop 0）：首个主组头容器坐标恰为 0，边界不留容差地吸附", () => {
+    // 与 kanban 五轮裁决一致：容器坐标恰好 0 时吸附层与在流组头像素重合（零跳变）
+    expect(compute(0)).toEqual({
+      group: { index: 0, offset: 0 },
+      sub: { index: 1, offset: 0 },
+    });
+  });
+
+  it("组内滚动未出区段：双层均吸附 offset 0", () => {
+    expect(compute(50)).toEqual({
+      group: { index: 0, offset: 0 },
+      sub: { index: 1, offset: 0 },
+    });
+  });
 
-describe("computeFrozenHeader", () => {
-  it("首屏（未滚动）激活第一个主组、无子组", () => {
-    expect(compute(0)).toEqual({ groupIdx: 0, subIdx: null });
+  it("子组头吸附位在主组头正下方（subPinTop=36）：坐标 37 未越过不吸附", () => {
+    // 子组头 start=36 在 scrollTop=-1 时容器坐标 37 > 36 —— 只测 scrollTop>=0 域：
+    // 用一个 start 更大的布局验证「未到吸附位不渲染副本」
+    const far = [
+      { start: 0, size: 36 },
+      { start: 100, size: 36 },
+    ];
+    const r = (scrollTop: number) =>
+      computeFrozenHeader(scrollTop, far, {
+        groupIndexes: [0],
+        subIndexes: [1],
+        parentGroupOfSub: new Map([[1, 0]]),
+        pad: 0,
+        subPinTop: 36,
+      });
+    // 子组头容器坐标 = 100 - st + 0；吸附位 36 → st = 64 越过
+    expect(r(63)?.sub).toBeNull();
+    expect(r(63)?.group).toEqual({ index: 0, offset: 0 });
+    expect(r(64)?.sub).toEqual({ index: 1, offset: 0 });
   });
 
-  it("组内滚动但未到子组头：仍激活主组、无子组", () => {
-    expect(compute(20)).toEqual({ groupIdx: 0, subIdx: null });
+  it("子组头被下一个子组头逐像素顶出（offset = 下一个头上缘容器坐标 - 72）", () => {
+    // 单组布局：G(0) S1(36) S2(200) —— S1 被 S2 顶出
+    const one = [
+      { start: 0, size: 36 },
+      { start: 36, size: 36 },
+      { start: 200, size: 36 },
+    ];
+    const r = (scrollTop: number) =>
+      computeFrozenHeader(scrollTop, one, {
+        groupIndexes: [0],
+        subIndexes: [1, 2],
+        parentGroupOfSub: new Map([
+          [1, 0],
+          [2, 0],
+        ]),
+        pad: 0,
+        subPinTop: 36,
+      });
+    // S2 上缘容器坐标 = 200 - st；触及 S1 底边（36+36=72）开始上推 → st = 128
+    expect(r(100)?.sub).toEqual({ index: 1, offset: 0 });
+    expect(r(128)?.sub).toEqual({ index: 1, offset: 0 });
+    expect(r(136)?.sub).toEqual({ index: 1, offset: -8 });
+    // S2 越过吸附位（st=164）时 S1 恰被完全顶出（-36，隐入主组头层之下）
+    expect(r(164)?.sub).toEqual({ index: 2, offset: 0 });
+  });
+
+  it("组切换边界：旧组头被顶出至恰好完全离场（offset=-36），新组头零跳变就位", () => {
+    // G2.start=240：scrollTop=240 时 G2 越过容器顶边成为活跃组头
+    expect(compute(240)).toEqual({
+      group: { index: 4, offset: 0 },
+      sub: { index: 5, offset: 0 },
+    });
+    // 切换前一瞬（scrollTop=239）：G1 被顶出 offset = 240-239-36 = -35
+    expect(compute(239)?.group).toEqual({ index: 0, offset: -35 });
+    // 子组头随区段结束边界一起滑出：offset = 240-239-72 = -71
+    expect(compute(239)?.sub).toEqual({ index: 1, offset: -71 });
   });
 
-  it("滚动到子组头：激活该子组", () => {
-    expect(compute(36)).toEqual({ groupIdx: 0, subIdx: 1 });
+  it("主组头被下一个主组头顶出（offset = G2 上缘容器坐标 - 36）", () => {
+    // G2 上缘容器坐标 = 240 - st；触及 G1 底边（36）开始上推 → st = 204
+    expect(compute(204)?.group).toEqual({ index: 0, offset: 0 });
+    expect(compute(212)?.group).toEqual({ index: 0, offset: -8 });
+    expect(compute(230)?.group).toEqual({ index: 0, offset: -26 });
   });
 
-  it("start == scrollTop + 1 边界：+1 容差视为已到达", () => {
-    expect(compute(35)).toEqual({ groupIdx: 0, subIdx: 1 });
+  it("子组头随区段结束（下一个主组头）滑出，与主组头同步离场", () => {
+    // scrollTop=212：G2 上缘容器坐标 28；G1 顶出 -8；S1 顶出 28-72 = -44
+    expect(compute(212)?.sub).toEqual({ index: 1, offset: -44 });
   });
 
-  it("跨到第二个主组：子组重置为 null（不属于该主组）", () => {
-    expect(compute(200)).toEqual({ groupIdx: 3, subIdx: null });
+  it("主组头切换后子组头归属门：新组头下方不得钉旧组子组头", () => {
+    // scrollTop=241：G2/S2 均活跃；旧 S1（start 36）测量上早已越过但归属 G1
+    const r = compute(241);
+    expect(r.group).toEqual({ index: 4, offset: 0 });
+    expect(r.sub).toEqual({ index: 5, offset: 0 });
   });
 
-  it("第二主组内滚动到其子组头：激活对应子组", () => {
-    expect(compute(236)).toEqual({ groupIdx: 3, subIdx: 4 });
+  it("新组头尚无越过吸附位的子组头：sub 为 null（不钉旧组的子组头）", () => {
+    // 构造 G2 与其子组头间距大的布局：G2 越过时 S2 未到吸附位
+    const sparse = [
+      { start: 0, size: 36 },
+      { start: 36, size: 36 },
+      { start: 240, size: 36 },
+      { start: 400, size: 36 },
+    ];
+    const r = computeFrozenHeader(241, sparse, {
+      groupIndexes: [0, 2],
+      subIndexes: [1, 3],
+      parentGroupOfSub: new Map([
+        [1, 0],
+        [3, 2],
+      ]),
+      pad: 0,
+      subPinTop: 36,
+    });
+    expect(r.group).toEqual({ index: 2, offset: 0 });
+    // 旧 S1（index 1）归属 G0 ≠ 活跃 G2 → 排除；新 S3（index 3，start 400）未越过
+    expect(r.sub).toBeNull();
   });
 
-  it("滚过末尾：冻结组头停在最后一个主组及其子组", () => {
-    expect(compute(10000)).toEqual({ groupIdx: 3, subIdx: 4 });
+  it("滚过末尾：双层吸附头停在最后一层（无下一个顶出源，offset 恒 0）", () => {
+    expect(compute(10000)).toEqual({
+      group: { index: 4, offset: 0 },
+      sub: { index: 5, offset: 0 },
+    });
   });
 
-  it("子组头属于其他主组时不激活（parent 判定生效）", () => {
-    // st=236 时索引 1（start 36）虽已越过，但它属于 group0，不应被选
-    expect(compute(236)?.subIdx).toBe(4);
+  it("负数 scrollTop（overscroll）钳制为 0：首个组头吸附 offset 0", () => {
+    expect(compute(-5)).toEqual({
+      group: { index: 0, offset: 0 },
+      sub: { index: 1, offset: 0 },
+    });
   });
 
-  it("测量缺失的组头被忽略；全部缺失时返回 null", () => {
-    expect(computeFrozenHeader(100, [{ start: 0 }], [0, 3], [1, 4], parentGroupOfSub)).toEqual({
-      groupIdx: 0,
-      subIdx: null,
+  it("测量缺失的组头被跳过；全部缺失时两层均为 null", () => {
+    const sparse = [{ start: 0, size: 36 }];
+    const r = computeFrozenHeader(10000, sparse, {
+      groupIndexes: [0, 4],
+      subIndexes: [1, 5],
+      parentGroupOfSub: parentOfSub,
+      pad: 0,
+      subPinTop: 36,
     });
-    expect(computeFrozenHeader(0, [], [0, 3], [1, 4], parentGroupOfSub)).toBeNull();
+    expect(r.group).toEqual({ index: 0, offset: 0 });
+    // index 1 无测量 → 跳过；index 5 无测量 → 跳过
+    expect(r.sub).toBeNull();
+    expect(
+      computeFrozenHeader(0, [], { groupIndexes: [0], subIndexes: [1], parentGroupOfSub: new Map() }),
+    ).toEqual({ group: null, sub: null });
+  });
+
+  it("无任何组头（groupIndexes/subIndexes 空）：两层均 null", () => {
+    expect(
+      computeFrozenHeader(100, measurements, {
+        groupIndexes: [],
+        subIndexes: [],
+        parentGroupOfSub: new Map(),
+      }),
+    ).toEqual({ group: null, sub: null });
   });
 
-  it("负数 scrollTop（overscroll）不崩且激活首个主组", () => {
-    expect(compute(-5)).toEqual({ groupIdx: 0, subIdx: null });
+  it("pad 参数（看板 p-2 口径）：阈值整体平移，S≤7 不吸附、S=8 吸附", () => {
+    // kanban 列内布局：首个子组头 start 0（内容盒原点），pad 8
+    const kanban = [
+      { start: 0, size: 28 },
+      { start: 28, size: 84 },
+      { start: 200, size: 28 },
+    ];
+    const r = (scrollTop: number) =>
+      computeFrozenHeader(scrollTop, kanban, {
+        groupIndexes: [],
+        subIndexes: [0, 2],
+        parentGroupOfSub: new Map(),
+        pad: 8,
+        subPinTop: 0,
+      });
+    for (let s = 0; s <= 7; s++) expect(r(s)).toEqual({ group: null, sub: null });
+    expect(r(8)).toEqual({ group: null, sub: { index: 0, offset: 0 } });
+    expect(r(50)).toEqual({ group: null, sub: { index: 0, offset: 0 } });
+  });
+
+  it("顶出量逐像素变化：offset 随 scrollTop 线性变化（消费方 state 比较必须含 offset）", () => {
+    const o1 = compute(210).group?.offset;
+    const o2 = compute(211).group?.offset;
+    expect(o1).toBe(-6);
+    expect(o2).toBe(-7);
+    expect(o1).not.toBe(o2);
+  });
+
+  it("subPinTop 缺省 0（单层直接吸附容器顶边，看板口径）", () => {
+    const r = computeFrozenHeader(40, measurements, {
+      groupIndexes: [],
+      subIndexes: [1],
+      parentGroupOfSub: new Map(),
+      pad: 0,
+    });
+    // 子组头 start 36 <= scrollTop 40 → 吸附 offset 0
+    expect(r).toEqual({ group: null, sub: { index: 1, offset: 0 } });
+    expect(
+      computeFrozenHeader(35, measurements, {
+        groupIndexes: [],
+        subIndexes: [1],
+        parentGroupOfSub: new Map(),
+        pad: 0,
+      }).sub,
+    ).toBeNull();
   });
 });