@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/views/timeline/mappers.ts

@@ -0,0 +1,506 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+/**
+ * 需求列表 → reui Gantt 数据的纯映射层（无 React、无 IO，全部可单测钉死）。
+ *
+ * 口径约定：
+ * - 半开区间：targetDate 含当天 ↔ event.end = targetDate 次日 00:00；
+ *   回写 fromGanttRangeToStoryDates 时 targetDate = end - 1 天。
+ * - 里程碑（零长度事件，start.getTime() === end.getTime()）三值判定：
+ *   仅 targetDate → 菱形；startDate === targetDate → 同为菱形；
+ *   startDate < targetDate → 条形；仅 startDate → 单日条形 end = start + 1。
+ * - 依赖方向：story.dependencies = 「以该 story 为 target 的边的 sourceId」，
+ *   只取 type === "BLOCKS"（SS/FF 不画）。
+ * - 汇总口径：ganttSummaryProgress 只看 event.data.story.state === "done"
+ *   占比（叶子 progress 不参与，单一口径）。
+ */
+
+import { parseDate, formatDateLocal } from "@/lib/datetime";
+import type {
+  GanttEvent,
+  GanttResource,
+} from "@/components/reui/gantt/gantt-types";
+import { STORY_STATES, type StoryState, type StoryPriority } from "../../constants";
+import type { StoryListItem } from "../../types";
+import type { GroupContext, GroupKey, GroupNode } from "../../display/types";
+// 分组语义单一来源：priority/assignee/labels/createdBy/project 的桶划分与
+// 标签/颜色解析全部复用 display/group-resolver（禁止重写分组语义）。
+// 注意：group-resolver 内部经 paraglide 解析哨兵组文案（unassigned/no-*），
+// mappers 自身不直接 import paraglide——无值文案的依赖只经此一条传递路径。
+import {
+  buildGroupMeta,
+  groupBy as groupStoriesBy,
+  groupUniverse,
+} from "../../display/group-resolver";
+
+/** 挂在 GanttEvent.data 上的业务载荷 */
+export interface StoryGanttData {
+  story: StoryListItem;
+}
+
+/** 任务依赖边（task 4 serverFn 返回的 shape；type 为字符串字面量） */
+export interface StoryDependencyEdge {
+  sourceId: string;
+  targetId: string;
+  type: string;
+}
+
+/**
+ * 状态 → 甘特条颜色。与 display/group-resolver.tsx 的 STATE_COLUMN_TINT
+ * 对齐同色相（todo=blue / in_progress=amber / done=green，同族关系由
+ * mappers.test.ts 锁定）；backlog / cancelled 无色相，取 muted 灰——
+ * 条形底以 color/20 透明度渲染，须用前景灰而非 --muted 表面色才可见。
+ * 值为 Tailwind 调色板 CSS 变量（条形实色，不需要 color-mix 淡化）。
+ */
+export const STORY_STATE_GANTT_COLOR: Record<StoryState, string> = {
+  backlog: "var(--muted-foreground)",
+  todo: "var(--color-blue-500)",
+  in_progress: "var(--color-amber-500)",
+  done: "var(--color-green-500)",
+  cancelled: "var(--muted-foreground)",
+};
+
+/**
+ * 优先级 → 甘特组节点颜色（CSS 变量色值，R-11）。与 display/group-resolver.tsx
+ * 的 PRIORITY_COLUMN_TINT 同色相（-600 同色号，同族关系由 mappers.test.ts
+ * 锁定——兼作 Tailwind v4 tree-shake 的保活哨兵）；low/none 无色相，取
+ * muted 灰（口径同 STORY_STATE_GANTT_COLOR 的无色相键）。禁止透传
+ * PRIORITY_COLOR（Tailwind 类串）——组节点 color 直接进内联样式/数据属性，
+ * 类串不是合法 CSS 色值。
+ */
+export const PRIORITY_GANTT_COLOR: Record<StoryPriority, string> = {
+  urgent: "var(--color-red-600)",
+  high: "var(--color-orange-600)",
+  medium: "var(--color-blue-600)",
+  low: "var(--muted-foreground)",
+  none: "var(--muted-foreground)",
+};
+
+/** 状态 → 完成度（0-100）：in_progress→50 / done→100 / 其他→0 */
+const STATE_PROGRESS: Record<StoryState, number> = {
+  backlog: 0,
+  todo: 0,
+  in_progress: 50,
+  done: 100,
+  cancelled: 0,
+};
+
+/**
+ * 甘特组节点资源 id 的统一形态（账本 R-1 裁决）：`${groupKey}:${node.key}`。
+ * 如 state:todo / priority:high / iteration:<id> / assignee:<userId>。
+ * 组 id 恒带维度前缀，与叶子行 id（story.id，不含冒号）空间不撞。
+ */
+export function ganttGroupResourceId(
+  groupKey: GanttGroupKey,
+  nodeKey: string,
+): string {
+  return `${groupKey}:${nodeKey}`;
+}
+
+/** state 分组组节点 id 的单一来源（内部对齐 R-1 统一形态；导出保留兼容既有调用） */
+export function storyStateResourceId(state: StoryState): string {
+  return ganttGroupResourceId("state", state);
+}
+
+/** 甘特分组键全集 = display GroupKey + iteration（iteration 为甘特专属维度） */
+export type GanttGroupKey = GroupKey | "iteration";
+
+/** 迭代基线（ghost band 数据）：调用方从 listIterationsFn 数据映射传入 */
+export interface IterationBaseline {
+  id: string;
+  start: Date;
+  end: Date;
+}
+
+/** iteration 维度「无迭代」哨兵组 key（命名随 group-resolver 的 no-* 哨兵惯例） */
+export const NO_ITERATION_KEY = "no-iteration";
+
+export interface GanttGroupOptions {
+  /**
+   * 分组上下文（用户/标签/项目元数据）。assignee/labels/createdBy/project
+   * 四键的组标签解析必需，缺失时抛错（拒绝静默回落层级树掩盖调用方缺陷）；
+   * state/priority/iteration 的分组不依赖 ctx。
+   */
+  ctx?: GroupContext;
+  /** iteration 维度的基线窗口全集（showEmptyGroups 时兼作零成员组的组域） */
+  iterations?: IterationBaseline[];
+  /**
+   * true 时与组域全集做并集补全零成员组（空 children、计数 0；组域序在前、
+   * 组域外观察组追加在后——交集语义会静默丢弃 ctx 缺失成员的需求）；
+   * 缺省维持非空组
+   */
+  showEmptyGroups?: boolean;
+  /**
+   * iteration「无迭代」组展示文案（调用方注入 paraglide 解析结果，
+   * 如 m.iterations_editor_none()）；未注入时回退哨兵 key 原文
+   * （mappers 是纯函数，不硬编码任何 locale 文案）。
+   */
+  noIterationLabel?: string;
+}
+
+function addDays(d: Date, n: number): Date {
+  const copy = new Date(d);
+  copy.setDate(copy.getDate() + n);
+  return copy;
+}
+
+/**
+ * story 日期 → 甘特区间；两个日期都缺失时返回 null（不产生事件）。
+ * 非法日期串返回 null（与 calendar/mappers 同口径）。里程碑（start===end）
+ * 零长度；倒挂数据（start > target）钳制为单日条形，保证 GanttEvent 的
+ * end >= start 不变量。
+ */
+function resolveStoryRange(
+  story: StoryListItem,
+): { start: Date; end: Date } | null {
+  const start = story.startDate ? parseDate(story.startDate) : null;
+  const target = story.targetDate ? parseDate(story.targetDate) : null;
+  // 防御：任一已存在的日期非法 → 整条不产出事件（与 calendar/mappers 同口径）
+  if (
+    (start && Number.isNaN(start.getTime())) ||
+    (target && Number.isNaN(target.getTime()))
+  ) {
+    return null;
+  }
+  if (start && target) {
+    if (start.getTime() === target.getTime()) {
+      return { start, end: start };
+    }
+    return { start, end: addDays(new Date(Math.max(start.getTime(), target.getTime())), 1) };
+  }
+  if (target) return { start: target, end: target };
+  if (start) return { start, end: addDays(start, 1) };
+  return null;
+}
+
+/**
+ * 需求列表 → 甘特事件。
+ * 依赖方向：T.dependencies = 以 T 为 target 的 BLOCKS 边的 sourceId
+ * （即「T 等待的前置 id 数组」；SS/FF 不画）。
+ * 无日期的 story 不产生事件（时间轴上无条形），但两种分组的资源树
+ * 都为它占行（state 组叶子 / none 层级节点），保证可见可点。
+ * resourceId = story.id：事件落在资源树的叶子行上（state 组的
+ * children 与 none 层级树叶子同以 story.id 为节点 id）。
+ */
+export function storyToGanttEvents(
+  stories: StoryListItem[],
+  edges: StoryDependencyEdge[],
+): GanttEvent<StoryGanttData>[] {
+  const events: GanttEvent<StoryGanttData>[] = [];
+  for (const story of stories) {
+    const range = resolveStoryRange(story);
+    if (!range) continue;
+    events.push({
+      id: story.id,
+      title: story.name,
+      start: range.start,
+      end: range.end,
+      progress: STATE_PROGRESS[story.state],
+      color: STORY_STATE_GANTT_COLOR[story.state],
+      readOnly: story.state === "cancelled",
+      resourceId: story.id,
+      dependencies: edges
+        .filter((e) => e.targetId === story.id && e.type === "BLOCKS")
+        .map((e) => e.sourceId),
+      data: { story },
+    });
+  }
+  return events;
+}
+
+/**
+ * 需求列表 → 甘特资源树。
+ * - groupBy="state"：按 STORY_STATES 顺序输出状态组节点（title = 「标签 (计数)」），
+ *   children = 该组需求的叶子行（id=story.id）——未排期需求同样占行。
+ * - groupBy="priority/assignee/labels/createdBy/project"：分组语义复用
+ *   display/group-resolver（groupBy/groupUniverse，禁止重写）；GroupNode →
+ *   组节点（id=ganttGroupResourceId、title=label 带计数、color=组色 CSS 值：
+ *   priority 走 PRIORITY_GANTT_COLOR，其余 muted，R-11）。
+ * - groupBy="iteration"：按 story.iteration 桶分（甘特专属维度，resolver 无此键），
+ *   组节点带 baselineStart/baselineEnd（来自 options.iterations）；无迭代组不设基线，
+ *   文案经 options.noIterationLabel 注入。
+ * - 其余（含 "none"）：parentId 层级树——父 story 为组节点、子 story 为叶子；
+ *   parentId 指向不存在 story 的孤儿与成环节点兜底挂根。
+ * options.showEmptyGroups=true 时各维度用组域并集补全零成员组（空 children、
+ * 计数 0；组域序在前、组域外观察组追加在后，不丢需求）。
+ */
+export function buildGanttResources(
+  stories: StoryListItem[],
+  groupBy: GanttGroupKey,
+  options: GanttGroupOptions = {},
+): GanttResource[] {
+  if (groupBy === "state") {
+    return buildStateGroups(stories, options.showEmptyGroups ?? false);
+  }
+  if (groupBy === "iteration") return buildIterationGroups(stories, options);
+  if (groupBy === "none") return buildHierarchyTree(stories);
+  return buildResolverGroups(stories, groupBy, options);
+}
+
+/** 叶子行节点（id=story.id，与事件 resourceId 对齐） */
+function storyLeafNode(story: StoryListItem): GanttResource {
+  return { id: story.id, title: story.name };
+}
+
+function buildStateGroups(
+  stories: StoryListItem[],
+  showEmpty: boolean,
+): GanttResource[] {
+  const groups: GanttResource[] = [];
+  // STORY_STATES 即 state 维度的组域全集（与 groupUniverse("state") 同一常量源），
+  // 序即枚举序；gantt 组色用 STORY_STATE_GANTT_COLOR（条形实色），非列 tint 色
+  for (const { value, label } of STORY_STATES) {
+    const members = stories.filter((s) => s.state === value);
+    if (members.length === 0 && !showEmpty) continue;
+    groups.push({
+      id: storyStateResourceId(value),
+      title: `${label()} (${members.length})`,
+      color: STORY_STATE_GANTT_COLOR[value],
+      // 叶子行承载每条需求（含未排期）：事件挂叶子 id，组可折叠
+      children: members.map(storyLeafNode),
+    });
+  }
+  return groups;
+}
+
+/** 组标签解析依赖 ctx 的键（缺 ctx 时抛错，拒绝静默回落） */
+const CTX_REQUIRED_KEYS: ReadonlySet<string> = new Set([
+  "assignee",
+  "labels",
+  "createdBy",
+  "project",
+]);
+
+/**
+ * GroupNode（group-resolver 产物）→ 甘特组节点：id=R-1 形态、title=label 带计数、
+ * color CSS 化（R-11）——priority 走 PRIORITY_GANTT_COLOR（与列 tint 同色相），
+ * 其余 resolver 键无组色语义统一 muted 灰；不用 node.color（resolver 产物是
+ * Tailwind 类串或 undefined，非合法 CSS 色值）。
+ */
+const NEUTRAL_GANTT_COLOR = "var(--muted-foreground)";
+
+function toGroupResource(
+  groupKey: Exclude<GanttGroupKey, "none" | "state" | "iteration">,
+  key: string,
+  node: GroupNode,
+): GanttResource {
+  return {
+    id: ganttGroupResourceId(groupKey, key),
+    title: `${node.label} (${node.items.length})`,
+    color:
+      groupKey === "priority"
+        ? (PRIORITY_GANTT_COLOR[key as StoryPriority] ?? NEUTRAL_GANTT_COLOR)
+        : NEUTRAL_GANTT_COLOR,
+    children: node.items.map(storyLeafNode),
+  };
+}
+
+/**
+ * priority/assignee/labels/createdBy/project → 组节点。
+ * 桶划分与标签/颜色全部来自 group-resolver 的 groupBy/groupUniverse 产物
+ * （GroupNode.label/color 已经由其内部 resolveGroupLabel/resolveGroupColor 解析）。
+ * showEmptyGroups 时与 groupUniverse 组域做**并集**（规范合并同 buildGroupMeta）：
+ * 组域序在前、组域外观察组（ctx 缺失成员：已退队仍被指派的 assignee、ctx 外
+ * project 等）追加在后——交集语义会把这些 story 从资源树整体静默丢弃；观察
+ * 节点元数据覆盖组域空组占位。组域为空的维度（labels/createdBy）维持观察序。
+ */
+function buildResolverGroups(
+  stories: StoryListItem[],
+  groupKey: Exclude<GanttGroupKey, "none" | "state" | "iteration">,
+  options: GanttGroupOptions,
+): GanttResource[] {
+  if (CTX_REQUIRED_KEYS.has(groupKey) && !options.ctx) {
+    throw new Error(
+      `buildGanttResources: groupBy="${groupKey}" 需要 options.ctx（组标签元数据），拒绝静默回落层级树`,
+    );
+  }
+  const ctx = options.ctx ?? { users: [], labels: [], projects: [] };
+  const nodes = groupStoriesBy(stories, groupKey, ctx);
+  const universe = options.showEmptyGroups ? groupUniverse(groupKey, ctx) : [];
+  if (universe.length === 0) {
+    return nodes.map((n) => toGroupResource(groupKey, n.key, n));
+  }
+  // buildGroupMeta：universe 先入、groups 覆盖 → Object.entries 的字符串键按
+  // 插入序枚举 = 「组域序在前 + 组域外残余追加」的并集序
+  const meta = buildGroupMeta(nodes, universe);
+  return Object.entries(meta).map(([key, node]) =>
+    toGroupResource(groupKey, key, node),
+  );
+}
+
+/**
+ * iteration → 组节点（甘特专属维度，group-resolver 无此键，桶划分在本地定义：
+ * key = story.iteration.id，无迭代归 NO_ITERATION_KEY 哨兵组）。
+ * 组名取成员自带的 story.iteration.name（同组共享；零成员组回退原始 id）；
+ * 无迭代组文案走 options.noIterationLabel 注入。基线来自 options.iterations
+ * （baselineStart/End 成对设置，ghost band 数据）；无迭代组不设基线。
+ */
+function buildIterationGroups(
+  stories: StoryListItem[],
+  options: GanttGroupOptions,
+): GanttResource[] {
+  const baselineById = new Map(
+    (options.iterations ?? []).map((i) => [i.id, i] as const),
+  );
+  const buckets = new Map<string, StoryListItem[]>();
+  const order: string[] = [];
+  const nameByKey = new Map<string, string>();
+  for (const story of stories) {
+    const key = story.iteration?.id ?? NO_ITERATION_KEY;
+    if (!buckets.has(key)) {
+      buckets.set(key, []);
+      order.push(key);
+    }
+    buckets.get(key)!.push(story);
+    if (story.iteration && !nameByKey.has(story.iteration.id)) {
+      nameByKey.set(story.iteration.id, story.iteration.name);
+    }
+  }
+  const toNode = (key: string, members: StoryListItem[]): GanttResource => {
+    const label =
+      key === NO_ITERATION_KEY
+        ? (options.noIterationLabel ?? NO_ITERATION_KEY)
+        : (nameByKey.get(key) ?? key);
+    const baseline = baselineById.get(key);
+    return {
+      id: ganttGroupResourceId("iteration", key),
+      title: `${label} (${members.length})`,
+      // iteration 无组色语义（含「无迭代」组），统一 muted 灰（R-11）
+      color: NEUTRAL_GANTT_COLOR,
+      // 基线成对设置（GanttResource 约定：set both or neither）
+      ...(baseline
+        ? { baselineStart: baseline.start, baselineEnd: baseline.end }
+        : {}),
+      children: members.map(storyLeafNode),
+    };
+  };
+  // 组域 = 调用方迭代清单 + 无迭代组（groupUniverse 无 iteration 域，以入参为
+  // 组域源）。showEmptyGroups 时与观察组做**并集**（与 resolver 五键同一策略）：
+  // 组域序在前、组域外残余（清单未覆盖的观察迭代，如基线未同步的历史迭代）
+  // 追加在后——交集会把这些组连同成员静默丢弃
+  const universeKeys = [
+    ...(options.iterations ?? []).map((i) => i.id),
+    NO_ITERATION_KEY,
+  ];
+  const universeSet = new Set(universeKeys);
+  const orderedKeys = options.showEmptyGroups
+    ? [...universeKeys, ...order.filter((k) => !universeSet.has(k))]
+    : order;
+  return orderedKeys.map((key) => toNode(key, buckets.get(key) ?? []));
+}
+
+function buildHierarchyTree(stories: StoryListItem[]): GanttResource[] {
+  const byId = new Map(stories.map((s) => [s.id, s]));
+  const childrenOf = new Map<string, StoryListItem[]>();
+  const roots: StoryListItem[] = [];
+  for (const story of stories) {
+    if (story.parentId && byId.has(story.parentId)) {
+      const list = childrenOf.get(story.parentId) ?? [];
+      list.push(story);
+      childrenOf.set(story.parentId, list);
+    } else {
+      // 根节点，或 parentId 指向不存在 story 的孤儿 → 挂根
+      roots.push(story);
+    }
+  }
+  const toNode = (story: StoryListItem): GanttResource => {
+    const kids = childrenOf.get(story.id) ?? [];
+    return {
+      id: story.id,
+      title: story.name,
+      children: kids.length > 0 ? kids.map(toNode) : undefined,
+    };
+  };
+  const nodes = roots.map(toNode);
+  // 成环防护：环上的 story 不可达自任何根，兜底平铺挂根
+  const seen = new Set<string>();
+  const walk = (node: GanttResource) => {
+    seen.add(node.id);
+    node.children?.forEach(walk);
+  };
+  nodes.forEach(walk);
+  for (const story of stories) {
+    if (!seen.has(story.id)) nodes.push({ id: story.id, title: story.name });
+  }
+  return nodes;
+}
+
+/**
+ * 组内完成度汇总（0-100）：events 中 data.story.state === "done" 占比 ×100。
+ * 空 events → null（无数据与 0% 区分）；叶子 progress 不参与（单一口径）。
+ */
+export function ganttSummaryProgress(p: {
+  resource: GanttResource;
+  events: GanttEvent<StoryGanttData>[];
+}): number | null {
+  if (p.events.length === 0) return null;
+  const doneCount = p.events.filter(
+    (e) => e.data?.story.state === "done",
+  ).length;
+  return (doneCount / p.events.length) * 100;
+}
+
+/**
+ * 乐观 override 叠加：storyId → 覆盖日期（date-only）。
+ * 比较必须两侧同切日键：服务端序列化是完整 ISO（"2026-10-02T00:00:00.000Z"），
+ * override 是 date-only（"2026-10-02"）——直接字符串比较恒不等，摘除分支
+ * 永不命中，拖拽过的行会在本组件生命周期内永久遮蔽刷新数据。
+ *
+ * 摘除/遮蔽判据：
+ * - 追平（日键相等）→ 摘除 override（返回原对象）；
+ * - 不同 且 无在途提交 → 服务端已独立越过 override（PeekPanel 改期/他人
+ *   改期/列表刷新带回新真值）→ 放弃 override，甘特立即跟随；
+ * - 不同 且 有在途提交（isPending 为 true）→ 继续遮蔽：此刻的 props 可能
+ *   是提交落库前的陈旧快照，放手会让条形弹回旧位。
+ */
+export function mergeStoryOverrides(
+  stories: StoryListItem[],
+  overrides: Map<string, { startDate: string; targetDate: string | null }>,
+  isPending?: (storyId: string) => boolean,
+): StoryListItem[] {
+  const dayKey = (v: string | null) => (v ? v.slice(0, 10) : null);
+  return stories.map((s) => {
+    const ov = overrides.get(s.id);
+    if (!ov) return s;
+    const caughtUp =
+      dayKey(s.startDate) === ov.startDate &&
+      dayKey(s.targetDate) === ov.targetDate;
+    // 追平，或服务端已越过 override 且无在途提交 → 摘除（返回原对象）
+    if (caughtUp || !isPending?.(s.id)) return s;
+    return { ...s, startDate: ov.startDate, targetDate: ov.targetDate };
+  });
+}
+
+/**
+ * 甘特区间 → story 日期回写。
+ * 零长度事件（start===end，菱形）→ { startDate: 当日, targetDate: 当日 }；
+ * 其余半开区间 → targetDate = end - 1 天（end 当天不含）。
+ */
+export function fromGanttRangeToStoryDates(
+  start: Date,
+  end: Date,
+): { startDate: string; targetDate: string } {
+  if (start.getTime() === end.getTime()) {
+    const day = formatDateLocal(start);
+    return { startDate: day, targetDate: day };
+  }
+  return {
+    startDate: formatDateLocal(start),
+    targetDate: formatDateLocal(addDays(end, -1)),
+  };
+}

package/src/components/story/views/timeline/sentinel-geometry.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// 无限滚动哨兵镜像几何（纯函数，timeline-view 的覆盖层哨兵消费）。
+//
+// 几何契约（custom 滚动条无布局空隙，viewport 铺满 timeline pane）：
+// - 覆盖层高 overlayH = topOffset + clientHeight（host 与 viewport 底缘齐平）；
+// - 可达 scrollTop 上限 maxScroll = scrollHeight - clientHeight；
+// - 内容末端的自然镜像 raw = topOffset + (scrollHeight - scrollTop)
+//   ⟹ raw ≥ topOffset + clientHeight = overlayH > overlayH - rowH 恒成立：
+//   自然镜像位置在全部滚动范围内都在覆盖层（overflow-hidden 裁剪盒）之外，
+//   哨兵行按 raw 摆放会被整体裁掉，IntersectionObserver 恒报不相交。
+//
+// 因此镜像必须上移一个行高：top = raw - rowH。
+// - 滚到最后一个 rowH 内（scrollTop > maxScroll - rowH）时行开始进入裁剪盒，
+//   恰好滚到底时行底边贴合覆盖层底缘（top = overlayH - rowH）→ 触发；
+// - 加载后 scrollHeight 增大 ⟹ top 增大、行整体退回裁剪盒之外 →
+//   intersection 复位，哨兵重新武装，不会挂载即连发。
+export function sentinelMirrorTop(input: {
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+  /** 哨兵行容器高（h-7 = 28px，恒定；调用方 effect 内缓存一次） */
+  rowH: number;
+  topOffset: number;
+}): number {
+  const { scrollTop, scrollHeight, clientHeight, rowH, topOffset } = input;
+  return topOffset + scrollHeight - scrollTop - rowH;
+}