dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/client/attribution/graph-options.ts

@@ -1,6 +1,7 @@
 import type { GraphData, GraphOptions, LayoutOptions } from '@antv/g6'
 import {
-  FAILURE_MODE_STYLE, isZombieEdge, nodeBoxOf, nodeShapeOf, nodeStyleOf, problemBadgeOf,
+  canvasScope,
+  FAILURE_REASON_STYLE, isZombieEdge, nodeBoxOf, nodeShapeOf, nodeStyleOf, problemBadgeOf,
   visibleEdges, visibleNodes,
   type AttributionEdge, type AttributionGraphData, type AttributionNode, type AttributionEdgeKind,
 } from './model.ts'
@@ -44,11 +45,15 @@ export interface G6AttributionData {
 
 const FONT = '"PingFang SC","Hiragino Sans GB","Microsoft YaHei",system-ui,sans-serif'
 
-/** 九种边各自的外观。层内边实线、跨层边点线，`refutes` 一律红色虚线（一等公民）。 */
+/** 十种边各自的外观。层内边实线、跨层边点线，`refutes` 一律红色虚线（一等公民）。 */
 const EDGE_STYLE: Record<AttributionEdgeKind, { stroke: string; lineWidth: number; lineDash?: number[] }> = {
   may_be_caused_by: { stroke: '#93b4f8', lineWidth: 1.6 },
   verified_by: { stroke: '#6b54cf', lineWidth: 1.3 },
   categorized_as: { stroke: '#c9b8ff', lineWidth: 1.2, lineDash: [5, 4] },
+  // `queries`（检查点 → 资产）与 `indexed_from`（资产 → 假设）是两条边，两端与回答的
+  // 问题都不同，所以外观也要能分开：同色同线型的话，图上分不清「这条假设落在哪张表上」
+  // 与「这条检查要去查哪张表」。
+  queries: { stroke: '#9ec2ff', lineWidth: 1.3, lineDash: [1, 3] },
   produces: { stroke: '#b96d14', lineWidth: 1.2, lineDash: [2, 3] },
   supports: { stroke: '#12875f', lineWidth: 1.4 },
   refutes: { stroke: '#b42318', lineWidth: 1.6, lineDash: [5, 4] },
@@ -57,11 +62,12 @@ const EDGE_STYLE: Record<AttributionEdgeKind, { stroke: string; lineWidth: numbe
   indexed_from: { stroke: '#9ec2ff', lineWidth: 1.2, lineDash: [2, 3] },
 }
 
-/** 边的中文读法。**九种必须全有** —— 图例是通过遍历这个表生成的，漏一种就是漏一段语义。 */
+/** 边的中文读法。**十种必须全有** —— 图例是通过遍历这个表生成的，漏一种就是漏一段语义。 */
 export const EDGE_KIND_LABEL: Record<AttributionEdgeKind, string> = {
   may_be_caused_by: '可能是原因',
   verified_by: '由…验证',
   categorized_as: '归类为',
+  queries: '要去查',
   produces: '产出',
   supports: '支持',
   refutes: '否定',
@@ -95,9 +101,40 @@ const BADGE_BASE = {
   backgroundStroke: '#e5e9f0',
   backgroundLineWidth: 1,
   backgroundRadius: 6,
-  padding: [3, 6, 3, 6],
+  // 动线视角里徽标画在**胶囊内部**（见 `laneNodeStyleFor`），所以它越矮越好：
+  // 高度直接吃掉标题那一行的地方。9px 字是最小可读档，上下内边距压到 1。
+  padding: [1, 5, 1, 5],
 }
 
+/**
+ * 节点**下方**徽标占掉的高度：徽标自身高（9px 字 + 上下内边距 ≈ 15）+ 它离节点下沿的距离（6）。
+ *
+ * **行距必须大于它。** 徽标挂在节点下方，而行距原来只有 4（面板）/ 8（全屏）——
+ * 于是下一行的节点正好压在上一行的徽标上：「复用 12」「3 min · 自动」「空区 · 无检查点」
+ * 全被盖掉一半，两行都读不出来。段底同样要留出这一段，否则最后一行照样被裁。
+ *
+ * 这一条是**几何契约**，所以 `laneLayoutOf` 直接用它，而不是各自写一个「差不多」的数：
+ * 徽标样式一改（字号 / 内边距 / offsetY），行距就得跟着改，否则重叠会悄悄回来。
+ */
+const BADGE_HEIGHT = 13
+
+/**
+ * 动线视角里徽标离节点**下沿内侧**的距离（负值 = 往胶囊里收）。
+ *
+ * 它原来是 `+10`（挂在节点**下方**），而那笔账在 380px 的面板里付不起：
+ * 徽标要占掉「徽标高 15 + 间距 10」≈ 25px 的净空，而面板五段加起来只有约 550px 预算、
+ * 14 行 —— 每行多 25px 就是 350px，直接翻倍。付不起的结果就是上一行的徽标被下一行的
+ * 节点压住（真机反馈的「都挤到一起了」）。
+ *
+ * 所以改成**画在胶囊内部的下沿**：行距不动、节点高度不动，重叠从几何上消失。
+ * 代价是标题收成一行（`labelMaxLines: 1`）并且让出下半部分给徽标 ——
+ * 完整标题在右侧详情卡里，那里有地方。
+ */
+const BADGE_GAP = -3
+
+/** 动线视角里标签要往上抬多少，给胶囊下沿的徽标腾地方。 */
+const LANE_LABEL_OFFSET_Y = -8
+
 /**
  * 一个节点的完整样式。
  *
@@ -108,7 +145,11 @@ const BADGE_BASE = {
  * 空区用「红色虚环 + 空区徽标」双重表达：只染灰不够 —— 维护者扫一眼时会把颜色
  * 读成失败模式配色，只有虚线会被读成「这里少了东西」。
  */
-export function nodeStyleFor(node: AttributionNode, gapIds: ReadonlySet<string>): Record<string, unknown> {
+export function nodeStyleFor(
+  node: AttributionNode,
+  gapIds: ReadonlySet<string>,
+  options: { dimmed?: boolean } = {},
+): Record<string, unknown> {
   const [width, height] = nodeBoxOf(node)
   const shape = nodeShapeOf(node)
   const isGap = gapIds.has(node.id)
@@ -150,7 +191,7 @@ export function nodeStyleFor(node: AttributionNode, gapIds: ReadonlySet<string>)
     // 假设节点会先命中 hypothesis 分支，写成 else-if 的话空区徽标永远不会出现，
     // 而空区恰恰总是假设节点。
     badges.push(isGap ? gapBadge : { ...BADGE_BASE, text: `复用 ${node.reuseCount ?? 0}`, placement: 'top', offsetY: -10 })
-  } else if (node.kind === 'check') {
+  } else if (node.kind === 'check_point') {
     badges.push({ ...BADGE_BASE, text: `${node.costMinutes ?? '?'} min · ${node.automation === 'auto' ? '自动' : '人工'}`, placement: 'bottom', offsetY: 10, fill: node.automation === 'auto' ? '#12875f' : '#b96d14' })
   } else if (isGap) {
     badges.push(gapBadge)
@@ -160,10 +201,106 @@ export function nodeStyleFor(node: AttributionNode, gapIds: ReadonlySet<string>)
     style.fillOpacity = 0.45
     style.labelOpacity = 0.55
   }
+  // 「其余节点降到 0.35」（§7.4 第 9 条）。徽标一起淡掉并且**去掉描边** ——
+  // 不淡的话，被点亮的那条链会被旁边一堆白底描边的小徽标压住，等于没点亮。
+  if (options.dimmed) {
+    style.fillOpacity = DIM_OPACITY
+    style.strokeOpacity = DIM_OPACITY
+    style.labelOpacity = DIM_OPACITY
+    if (badges.length > 0) {
+      style.badges = badges.map(badge => ({
+        ...badge,
+        fillOpacity: DIM_OPACITY,
+        backgroundFill: 'transparent',
+        backgroundStroke: 'transparent',
+        backgroundLineWidth: 0,
+      }))
+    }
+  }
+  return style
+}
+
+/** 未被点亮时的透明度。写在一处，画布与节点详情读同一个数。 */
+export const DIM_OPACITY = 0.35
+
+/**
+ * 动线视角里的节点样式：**胶囊，不是圆**。
+ *
+ * 关系视图里假设画成圆（圆的直径就是复用次数，那一段读的是「这块密不密」）。
+ * 动线视角读的是另一件事 ——「这条链走到哪」—— 所以每个节点都要能读出名字，
+ * 复用次数退成徽标上的一行字：`H1 上游分区未产出` + `复用 12`。
+ */
+export function laneNodeStyleFor(node: AttributionNode, gapIds: ReadonlySet<string>, options: {
+  size: [number, number]
+  dimmed?: boolean
+}): Record<string, unknown> {
+  const [width, height] = options.size
+  const isGap = gapIds.has(node.id)
+  const palette = nodeStyleOf(node)
+  const style: Record<string, unknown> = {
+    size: [width, height],
+    radius: 8,
+    fill: palette.fill,
+    stroke: isGap ? GAP_STROKE : palette.stroke,
+    lineWidth: isGap ? 2 : 1.5,
+    lineDash: isGap ? [4, 3] : undefined,
+    zIndex: node.layer === 'instance' ? 0 : 1,
+    // id 必须留在标签里：它是案例路径、排查清单与这个节点之间唯一的指认方式。
+    labelText: `${node.id} ${node.title}`,
+    labelPlacement: 'center',
+    labelFill: palette.text,
+    labelFontSize: 10.5,
+    labelFontFamily: FONT,
+    labelFontWeight: 600,
+    // 标签往上抬，把胶囊下半部分让给徽标（见 `LANE_LABEL_OFFSET_Y`）。
+    labelOffsetY: LANE_LABEL_OFFSET_Y,
+    labelWordWrap: true,
+    labelWordWrapWidth: width - 12,
+    // **一行。** 两行标题 + 一枚徽标装不进 36px 的胶囊；而两行标题装得下、
+    // 徽标挂在下面时，行距必须让出 25px —— 那笔账在 380px 的面板里付不起。
+    // 取舍写在 §7.7.1.3：动线视角保「不重叠 + 五段一眼看完」，完整标题归右侧详情卡。
+    labelMaxLines: 1,
+    labelTextOverflow: 'ellipsis',
+    cursor: 'pointer',
+  }
+
+  const badges: Array<Record<string, unknown>> = []
+  // 段头已经写了段的读法，所以徽标只留「这个节点最关键的那一格」：一段一个。
+  // 都堆上去的话，44px 高的胶囊会被三个徽标切成碎片。
+  if (node.kind === 'symptom') {
+    const problem = problemBadgeOf(node)
+    if (problem) badges.push({ ...BADGE_BASE, text: problem, placement: 'bottom', offsetY: BADGE_GAP, fill: '#96580f', backgroundStroke: '#f2ddb8' })
+  } else if (node.kind === 'hypothesis') {
+    badges.push(isGap
+      ? { ...BADGE_BASE, text: '空区 · 无检查点', placement: 'bottom', offsetY: BADGE_GAP, fill: GAP_STROKE, backgroundStroke: '#f0b7ad' }
+      : { ...BADGE_BASE, text: `复用 ${node.reuseCount ?? 0}`, placement: 'bottom', offsetY: BADGE_GAP, fill: palette.text, backgroundStroke: palette.stroke })
+  } else if (node.kind === 'check_point') {
+    badges.push({ ...BADGE_BASE, text: `${node.costMinutes ?? '?'} min · ${node.automation === 'auto' ? '自动' : '人工'}`, placement: 'bottom', offsetY: BADGE_GAP, fill: node.automation === 'auto' ? '#12875f' : '#b96d14' })
+  } else if (node.kind === 'evidence') {
+    const verdict = node.verdict === 'refutes' ? '否定' : node.verdict === 'supports' ? '支持' : '给不出结论'
+    badges.push({ ...BADGE_BASE, text: verdict, placement: 'bottom', offsetY: BADGE_GAP, fill: node.verdict === 'refutes' ? GAP_STROKE : '#12875f' })
+  } else if (isGap) {
+    badges.push({ ...BADGE_BASE, text: '空区 · 无检查点', placement: 'bottom', offsetY: BADGE_GAP, fill: GAP_STROKE, backgroundStroke: '#f0b7ad' })
+  }
+  if (badges.length > 0) style.badges = badges
+  if (options.dimmed) {
+    style.fillOpacity = DIM_OPACITY
+    style.strokeOpacity = DIM_OPACITY
+    style.labelOpacity = DIM_OPACITY
+    if (badges.length > 0) {
+      style.badges = badges.map(badge => ({
+        ...badge,
+        fillOpacity: DIM_OPACITY,
+        backgroundFill: 'transparent',
+        backgroundStroke: 'transparent',
+        backgroundLineWidth: 0,
+      }))
+    }
+  }
   return style
 }
 
-export function edgeStyleFor(edge: AttributionEdge): Record<string, unknown> {
+export function edgeStyleFor(edge: AttributionEdge, options: { labels?: boolean } = {}): Record<string, unknown> {
   const zombie = isZombieEdge(edge)
   const base = zombie ? ZOMBIE_STYLE : EDGE_STYLE[edge.kind]
   const style: Record<string, unknown> = {
@@ -180,6 +317,9 @@ export function edgeStyleFor(edge: AttributionEdge): Record<string, unknown> {
     labelBackgroundRadius: 4,
     labelPadding: [2, 4, 2, 4],
   }
+  // 动线视角里二十几条边并排成五段，标签会互相压成一片 —— 那一段的读法已经写在
+  // 段头（`orderHint`）上，边上只留箭头。关系视图没有段头，标签才是唯一读法。
+  if (options.labels === false) return style
   if (zombie) {
     style.labelText = `僵尸边 ${edge.staleDays} 天未走`
     style.labelFontSize = 9
@@ -195,44 +335,371 @@ export function edgeStyleFor(edge: AttributionEdge): Record<string, unknown> {
 /**
  * 模型 → G6 数据。
  *
- * `includeInstance` 默认 false：实例层随每次排查线性增长，展开它会把类型层挤成
- * 一堆小点 —— 而图谱视图要看的第一件事恰是类型层收不收敛。
+ * 位置分两种来源：关系视图用 `positions`（黄金角螺旋的确定性初始位置，再交给
+ * 力导向松弛）；动线视图用 `laneGeometry`（段位与段内顺序**完全**决定坐标）。
+ * 两者都不依赖随机数 —— 同一份数据刷新之后，空间记忆仍然成立（§7.2）。
  */
 export function toG6Data(
   data: AttributionGraphData,
-  options: { includeInstance?: boolean; gapIds: ReadonlySet<string>; positions?: Map<string, [number, number]> } = { gapIds: new Set() },
+  options: {
+    includeInstance?: boolean
+    gapIds: ReadonlySet<string>
+    positions?: Map<string, [number, number]>
+    /** 动线视角的段位坐标。给了它就用段位，`positions` 被忽略。 */
+    laneGeometry?: LaneGeometry
+    /** 被点亮的那条链之外的节点：透明度降到 0.35（§7.4 第 9 条）。 */
+    dimmedIds?: ReadonlySet<string>
+    /** 边上是否画标签。动线视角关掉（段头已经写了读法）。 */
+    edgeLabels?: boolean
+    /**
+     * 布局。它决定「哪些节点与边根本不进这张画布」——
+     * 动线视角不画没有段位的节点种类（`failure_reason`）与反向的 `indexed_from`
+     * （见 `canvasScope`）。
+     *
+     * **必填，没有默认值。** 给个默认会让调用方在不知情的情况下拿到「少画了东西」的
+     * 那张图 —— 而少画是静默的：节点就是不在那儿，没有任何报错。要哪一种，说清楚。
+     */
+    layout: 'line' | 'force'
+  },
 ): G6AttributionData {
-  const nodes = visibleNodes(data, options.includeInstance ?? false)
-  const edges = visibleEdges(data, nodes)
+  const scope = canvasScope(options.layout)
+  /**
+   * **段位几何是「画什么」的唯一真源。**
+   *
+   * 动线视角下只画 `geometry.nodes` 里有的节点。少了这一条会同时踩两个坑：
+   * ① 没有段位的节点（`failure_reason`）会退到力导向的种子位置上，变成悬在画布上的
+   *    孤儿 —— 它不在任何一段里，却在图上占一个位置；
+   * ② 被收起的段（④ 查询依据）里的节点照样会被画出来，而段头写的是「已收起」——
+   *    画布与段头对不上，读数就成了假的。
+   */
+  const all = visibleNodes(data, options.includeInstance ?? false).filter(node => !scope.kinds.has(node.kind))
+  const nodes = options.laneGeometry ? all.filter(node => options.laneGeometry!.nodes.has(node.id)) : all
+  const edges = visibleEdges(data, nodes).filter(edge => !scope.edges.has(edge.kind))
+  const dimmed = options.dimmedIds ?? new Set<string>()
   return {
     nodes: nodes.map(node => {
-      const style = nodeStyleFor(node, options.gapIds)
-      // 力导向布局的初始位置：给了就落上去再松弛，没给就让 G6 自己随机。
-      const seed = options.positions?.get(node.id)
-      if (seed) { style.x = seed[0]; style.y = seed[1] }
-      return { id: node.id, type: nodeShapeOf(node), data: { node }, style }
+      const lane = options.laneGeometry?.nodes.get(node.id)
+      const style = lane
+        ? laneNodeStyleFor(node, options.gapIds, { size: [lane.width, lane.height], dimmed: dimmed.has(node.id) })
+        : nodeStyleFor(node, options.gapIds, { dimmed: dimmed.has(node.id) })
+      if (lane) {
+        style.x = lane.x
+        style.y = lane.y
+      } else {
+        const seed = options.positions?.get(node.id)
+        if (seed) { style.x = seed[0]; style.y = seed[1] }
+      }
+      // 动线视角一律画成胶囊：段内横排，形状不参与表达（那是关系视图的活）。
+      return { id: node.id, type: lane ? 'rect' : nodeShapeOf(node), data: { node }, style }
     }),
     edges: edges.map(edge => ({
       id: edge.id,
       source: edge.source,
       target: edge.target,
       data: { edge },
-      style: edgeStyleFor(edge),
+      style: {
+        ...edgeStyleFor(edge, options.edgeLabels === false ? { labels: false } : {}),
+        ...(dimmed.has(edge.id) ? { dimmed: true } : {}),
+      },
     })),
   }
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+ * 动线视角的段位（0021 §7.2 / §7.7）
+ *
+ * 位置**完全**由「段位 + 段内顺序」决定，所以它是纯函数：同一份数据、同一个容器，
+ * 每次算出来的坐标一模一样。这也是「上次那个空区在第三段」这类空间记忆能成立的原因。
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/** 一段的尺寸预算。上下留白不是审美：段头要写在带子里，节点下方还挂着徽标。 */
+export interface LaneMetrics {
+  /** 段头带高（段名 + 计数写在这里）。 */
+  header: number
+  /**
+   * 段间距的上限（把剩余高度平分进段间距时的封顶）。
+   *
+   * 不封顶会踩到全屏：容器 1200px、内容只有 500px 时，剩下 700px 平分进 4 个段间距
+   * = 每段之间空 175px。五段本来是**一条动线上的五站**，空成这样读起来像五张互不相干
+   * 的图。封顶之后多出来的空间进 `offsetY`，整块内容垂直居中 —— 那才是「留白」，
+   * 而不是「断开」。
+   */
+  maxBandGap: number
+  /**
+   * 段内容底部要留的高度。
+   *
+   * 现在是 0：徽标画在胶囊内部，不再有东西挂到节点下方。留着这个字段是因为
+   * 「有没有东西挂在节点外面」是会变的（关系视图的徽标就挂在外面），
+   * 到那时它是唯一该改的地方。
+   */
+  bandBottomPad: number
+  /**
+   * 内容左右留白。左侧留够浮层压过来的宽度。
+   *
+   * 面板态给 100：左栏的 pill / 展开面板都浮在画布左上，实测宽约 90px。
+   * 段头文字与节点都从这一列开始，它们才不会被浮层盖住 —— 而「段头读不到」
+   * 等于这个视角没了标题。
+   */
+  padLeft: number
+  padRight: number
+  rowGap: number
+  /** 段与段之间的最小间距。剩余空间会**平分加到这里**。 */
+  bandGap: number
+  /** 每种节点的胶囊尺寸（宽 × 高）。 */
+  sizeOf: (node: AttributionNode) => [number, number]
+}
+
+/**
+ * 面板 / 全屏两档的段位尺寸。
+ *
+ * 面板档算得很紧：380px 宽、四五百像素高的边栏里，五段要能一眼看完 ——
+ * 看不完就退化成「一张排好序的清单」，而动线视角的价值恰在「这条链断在哪」。
+ * 横向预算按 380 − 56 − 16 = 308 给：现象一行两个、检查点一行两个、资产一行三个。
+ * **行数由内容算**（见 `laneLayoutOf` 的 `packLane`），不写死上限 —— 某一段特别密
+ * 就多占一行，而不是被裁掉；五段都留在视野里靠的是「行数取最少」加整体收一点。
+ * 全屏放得下，节点尺寸与段间距都放宽一档。
+ *
+ * 左侧 56px 是留给左栏浮层的：面板态它收起成一颗药丸（约 90px 宽，26px 高），
+ * 只压住第一行节点的左端 —— 比把每一段都往右推 90px 划算得多（那会只剩 270px
+ * 可用宽，检查点会被迫排到四行，五段就铺不进一屏了）。
+ */
+export const LANE_METRICS: Record<StageMode, LaneMetrics> = {
+  panel: {
+    // 行距不动：徽标画在胶囊内部，不占行间净空（见 `BADGE_GAP`）。
+    header: 20, padLeft: 56, padRight: 16, rowGap: 4, bandGap: 6, maxBandGap: 22,
+    bandBottomPad: 0,
+    sizeOf: (node) => {
+      if (node.kind === 'symptom') return [124, 38]
+      if (node.kind === 'hypothesis') return [118, 36]
+      if (node.kind === 'check_point') return [102, 30]
+      if (node.kind === 'asset') return [102, 28]
+      return [160, 30]
+    },
+  },
+  fullscreen: {
+    header: 24, padLeft: 96, padRight: 20, rowGap: 8, bandGap: 14, maxBandGap: 48,
+    bandBottomPad: 0,
+    sizeOf: (node) => {
+      if (node.kind === 'symptom') return [210, 48]
+      if (node.kind === 'hypothesis') return [176, 44]
+      if (node.kind === 'check_point') return [184, 40]
+      if (node.kind === 'asset') return [150, 34]
+      return [200, 40]
+    },
+  },
+}
+
+export function laneMetricsFor(mode: StageMode): LaneMetrics {
+  return LANE_METRICS[mode]
+}
+
+/** 动线视角里一个节点的落位：中心坐标 + 尺寸。单位是**世界坐标**（zoom = 1 时等于画布像素）。 */
+export interface LaneNodePlacement { x: number; y: number; width: number; height: number }
+
+/**
+ * 一段的几何：整条带子的上下边界、段头的下沿、内容区起点、这一段的节点落位。
+ *
+ * `top` / `bottom` 是**世界坐标**，可以直接喂给 `laneGuides()` 算泳道带矩形 ——
+ * 画布与 HTML 泳道带读同一份结果，两处不可能对不上（§7.7 段头与泳道背景）。
+ */
+export interface LaneGeometry {
+  /** 整块内容的宽度（世界坐标）。 */
+  contentWidth: number
+  /** 容器高度减内容高度的一半，用来把内容垂直居中；为负说明装不下。 */
+  offsetY: number
+  bands: Array<{
+    laneId: string
+    top: number
+    bottom: number
+    headerBottom: number
+    /** 段的节点区起点（世界 x）。段头文字与节点左对齐到它。 */
+    x: number
+    rowCount: number
+    nodeCount: number
+  }>
+  nodes: Map<string, LaneNodePlacement>
+}
+
+/**
+ * 一段的入参：段 id + 已经排好序的节点。
+ *
+ * 刻意**只收这两个字段**而不是整个 `LaneSegment`：布局只关心「谁、什么顺序」，
+ * 段名与计数是段头的事。两边不互相依赖，`graph-options` 也就不必 import `model` 的
+ * 段类型。
+ */
+export interface LaneBandInput {
+  laneId: string
+  nodes: AttributionNode[]
+}
+
+/**
+ * 按段位算坐标。
+ *
+ * 算法两步，都不含随机：
+ * 1. **段内**：按传入顺序从左到右摆；一行摆不下就换行（节点宽度不同，
+ *    所以必须真的累加宽度，不能按「每行 N 个」估）。每段的行数上限取
+ *    `rowBudget[laneId]`：**超出的行不撑高带子**，五段因此永远留在视野里 ——
+ *    「哪一段断了」是这张图第一要读的东西，某一段特别密不该把它挤出屏幕。
+ * 2. **段间**：每段高 = 段头 + 行高之和，再加上 `bandGap`；`viewportHeight` 给了
+ *    就把剩余空间**平分进段间距**，让五段铺满高度。剩余不足时 `offsetY` **夹在 0**
+ *    —— 那说明容器太矮，宁可下缘被裁，也不要上缘（段头所在的那一条）被推出画面。
+ */
+export function laneLayoutOf(
+  bands: LaneBandInput[],
+  options: {
+    width: number
+    height: number
+    mode: StageMode
+    /** 期望的内容总高（通常 = 容器高）。省略就按 `bandGap` 自然堆叠。 */
+    viewportHeight?: number
+  },
+): LaneGeometry {
+  const metrics = laneMetricsFor(options.mode)
+  const contentWidth = Math.max(240, options.width)
+  const inner = Math.max(120, contentWidth - metrics.padLeft - metrics.padRight)
+
+  /**
+   * 段内怎么摆：**先求这一段至少要几行，再把节点均分进那几行**。
+   *
+   * 不是「填满一行换下一行」—— 那样最后一行常常只剩一个节点，其余全挤在前面几行，
+   * 而横向预算又不允许超出去，于是最后那个节点会被压得很小。均分是同一个段里
+   * 唯一能让每个节点尺寸接近的做法。
+   *
+   * 行数取「内容总宽 ÷ 可用宽」向上取整 —— **尽量少占行数**，五段才铺得进一屏。
+   * 每一行再按可用宽整体收一点（`scale`），这样最宽的节点也不会越出画布右沿；
+   * 收的是同一段内所有的节点，所以它们看起来仍然是一组。
+   */
+  const packLane = (nodes: AttributionNode[], factor: number): { rows: AttributionNode[][]; widths: number[][]; heights: number[][] } => {
+    if (nodes.length === 0) return { rows: [], widths: [], heights: [] }
+    const sizes = nodes.map(node => {
+      const [w, h] = metrics.sizeOf(node)
+      return [Math.round(w * factor), Math.round(h * factor)] as [number, number]
+    })
+    const totalWidth = sizes.reduce((sum, size) => sum + size[0], 0) + ROW_NODE_GAP * (nodes.length - 1)
+    const rowCount = Math.max(1, Math.ceil(totalWidth / inner))
+    const perRow = Math.ceil(nodes.length / rowCount)
+    const rows: AttributionNode[][] = []
+    for (let start = 0; start < nodes.length; start += perRow) rows.push(nodes.slice(start, start + perRow))
+    const widest = rows.reduce((max, row) => {
+      const content = row.reduce((sum, node) => sum + (sizes[nodes.indexOf(node)]?.[0] ?? 0), 0) + ROW_NODE_GAP * (row.length - 1)
+      return Math.max(max, content)
+    }, 0)
+    const squeeze = Math.min(1, inner / Math.max(1, widest))
+    const widths = rows.map(row => row.map(node => Math.max(48, Math.round((sizes[nodes.indexOf(node)]?.[0] ?? 100) * squeeze))))
+    const heights = rows.map(row => row.map(node => Math.max(24, Math.round((sizes[nodes.indexOf(node)]?.[1] ?? 36) * squeeze))))
+    return { rows, widths, heights }
+  }
+
+  /** 五段铺在给定缩放下的总高。自适应那一步要拿它比对可用高。 */
+  const totalHeightAt = (factor: number): number => {
+    let total = 0
+    for (const band of bands) {
+      const pack = packLane(band.nodes, factor)
+      const rowHeights = pack.heights.map(row => Math.max(...row, 0))
+      total += metrics.header + (rowHeights.length === 0
+        ? EMPTY_ROW_HEIGHT
+        : rowHeights.reduce((sum, h) => sum + h, 0) + metrics.rowGap * (rowHeights.length - 1))
+    }
+    return total + metrics.bandGap * Math.max(0, bands.length - 1)
+  }
+
+  /**
+   * 内容铺不下时整体收一点，而不是让下缘被裁掉。
+   *
+   * 面板档的段位尺寸是按「380px 宽、约 500px 高」定的；边栏高度随宿主的窗口变，
+   * 用户也可能把窗口拉得很矮。这时按 `√(可用高 ÷ 需要高)` 把每个节点等比收一点，
+   * 五段就仍然留在一屏里 —— 而「哪一段断了」必须始终看得见。
+   *
+   * 下界 0.78：再小标签就读不出来了。到那一步宁可让下缘溢出去（此时 `offsetY`
+   * 夹在 0，被裁的只会是最后一段的下沿，段头永远在画面里）。
+   */
+  const fitFactor = ((): number => {
+    if (options.viewportHeight === undefined) return 1
+    if (totalHeightAt(1) <= options.viewportHeight) return 1
+    const guess = Math.max(0.78, Math.sqrt(options.viewportHeight / totalHeightAt(1)))
+    // 收完之后每行装得下更多节点，行数可能变少 —— 再校一次，两次足够收敛。
+    if (totalHeightAt(guess) <= options.viewportHeight) return guess
+    return Math.max(0.78, guess * Math.sqrt(options.viewportHeight / totalHeightAt(guess)))
+  })()
+
+  const packed = bands.map(band => ({ band, pack: packLane(band.nodes, fitFactor) }))
+  const naturalHeights = packed.map(item => {
+    const rowHeights = item.pack.heights.map(row => Math.max(...row, 0))
+    return metrics.header + (rowHeights.length === 0
+      ? EMPTY_ROW_HEIGHT
+      : rowHeights.reduce((sum, h) => sum + h, 0) + metrics.rowGap * (rowHeights.length - 1) + metrics.bandBottomPad)
+  })
+  const gaps = Math.max(0, packed.length - 1)
+  const natural = naturalHeights.reduce((sum, h) => sum + h, 0) + metrics.bandGap * gaps
+  const slack = options.viewportHeight === undefined ? 0 : options.viewportHeight - natural
+  // 剩余空间平分给段间距，但**封顶**（见 `maxBandGap`）：装不下时退回自然间距
+  // （负的 slack 不参与），富余很多时多出来的那部分进下面的 `offsetY`，整块居中。
+  const bandGap = metrics.bandGap + (slack > 0 && gaps > 0
+    ? Math.min(slack / gaps, metrics.maxBandGap - metrics.bandGap)
+    : 0)
+  const total = naturalHeights.reduce((sum, h) => sum + h, 0) + bandGap * gaps
+
+  const geometry: LaneGeometry = {
+    contentWidth,
+    // 夹在 0：容器装不下时宁可下缘被裁，也不要段头被推出画面（见函数头）。
+    offsetY: options.viewportHeight === undefined ? 0 : Math.max(0, (options.viewportHeight - total) / 2),
+    bands: [],
+    nodes: new Map(),
+  }
+
+  let cursor = geometry.offsetY
+  packed.forEach((item, index) => {
+    const height = naturalHeights[index]!
+    const rowHeights = item.pack.heights.map(row => Math.max(...row, 0))
+    const top = cursor
+    const headerBottom = top + metrics.header
+    const band = {
+      laneId: item.band.laneId,
+      top,
+      bottom: top + height,
+      headerBottom,
+      x: metrics.padLeft,
+      rowCount: item.pack.rows.length,
+      nodeCount: item.band.nodes.length,
+    }
+    geometry.bands.push(band)
+
+    let y = headerBottom + (rowHeights.length === 0 ? EMPTY_ROW_HEIGHT / 2 : 0)
+    item.pack.rows.forEach((row, rowIndex) => {
+      const rowHeight = rowHeights[rowIndex] ?? 0
+      let x = metrics.padLeft
+      row.forEach((node, nodeIndex) => {
+        const w = item.pack.widths[rowIndex]?.[nodeIndex] ?? 100
+        const h = item.pack.heights[rowIndex]?.[nodeIndex] ?? rowHeight
+        geometry.nodes.set(node.id, { x: x + w / 2, y: y + rowHeight / 2, width: w, height: h })
+        x += w + ROW_NODE_GAP
+      })
+      y += rowHeight + metrics.rowGap
+    })
+    cursor = band.bottom + bandGap
+  })
+
+  return geometry
+}
+
+/** 同一行里两个节点之间的间距。 */
+const ROW_NODE_GAP = 8
+/** 空段的高度：足以放下一行「这一段还没有东西」的说明。 */
+const EMPTY_ROW_HEIGHT = 24
+
 /**
- * 布局种类。
+ * 布局种类。**只有两种，而且默认是动线。**
  *
- * `force` 是知识图谱的默认读法：没有「上→下」的方向，关系靠聚簇和距离表达，
- * 节点可以拖，像一张会自己摊开的地图。
- * `layered` 是**语义**读法：现象→假设→检查本来就是有向的 DAG，分层把这个方向
- * 显式画出来 —— 代价是它看起来像流程图而不是知识图谱。
+ * `line`（动线）是默认读法：五段泳道，位置完全由段位与段内排序决定（§7.7）。
+ * 它回答的是值班同学打开这一栏真正要问的那句 ——「下一步查什么、这条链断在哪」。
+ * `force`（关系）是自由读法：浮动节点、可拖拽，关系靠聚簇与距离表达。
+ * 它回答「这张图长什么样、哪块密哪里空」，那是维护者的问题。
  *
- * 两个都留：默认 force 回答「这张图长什么样」，切到 layered 回答「谁是上游」。
+ * **v1.4 撤销了「分层」（`layered`）。** 原来留它是因为「方向本身是语义」——
+ * 而动线就是这件事的语义版：分层只按入度分列，动线按这五个阶段分列，且每段带段头
+ * 与计数。两个都能画方向时，留那个说得清「这一段是什么」的（§7.2）。
  */
-export type GraphLayout = 'force' | 'layered'
+export type GraphLayout = 'line' | 'force'
 
 /**
  * 画布所处的容器档位。
@@ -299,10 +766,28 @@ export function seedPositions(data: AttributionGraphData, width: number, height:
   return positions
 }
 
-export function layoutOf(kind: GraphLayout, rankdir: 'LR' | 'TB'): LayoutOptions {
-  if (kind === 'layered') {
-    return { type: 'antv-dagre', rankdir, nodesep: 46, ranksep: 96, controlPoints: false }
-  }
+/**
+ * 布局配置。
+ *
+ * **动线视角不给 G6 任何布局算法**：坐标已经由 `laneLayoutOf` 算好了，
+ * 这里只需一个「原样保留我给的坐标」的布局。G6 的 `grid` 在数据里带了 `x` / `y`
+ * 时会原样采用，因此这是最省的一个 —— 引入 d3-force 或 dagre 都会把我们的段位
+ * 重新摆过一遍，那正是「段位固定」的反面。
+ */
+/**
+ * 动线视角**没有布局算法** —— 它返回 `undefined`，而不是 `{ type: 'grid' }`。
+ *
+ * 这一格出过一次很难看的错：写着 `{ type: 'grid' }`，看着像「不布局，摆成网格」，
+ * 实际是让 G6 **真的去跑一遍网格布局**，把 `style.x` / `style.y` 全部重写掉。
+ * 于是段位算出来的坐标被整份丢弃，节点散落到网格上，而泳道带还画在段位坐标上 ——
+ * 带子与节点彻底对不上。相机又锁在 `zoom: 1` 且没有 `autoFit`，网格铺得比容器大，
+ * 大部分节点直接跑到可视区之外，屏幕上只剩几个徽标和一堆穿出来的边。
+ *
+ * 动线的坐标来自 `laneLayoutOf`（段位 + 段内顺序，纯函数、每次一样），
+ * 所以这里**必须什么都不做**：G6 在没有 `layout` 时才会用数据里给的坐标。
+ */
+export function layoutOf(kind: GraphLayout, rankdir: 'LR' | 'TB'): LayoutOptions | undefined {
+  if (kind === 'line') return undefined
   return {
     type: 'd3-force',
     // 值都偏大：节点带下方徽标，挤在一起时徽标先重叠，比圆重叠更难看。
@@ -316,36 +801,75 @@ export function layoutOf(kind: GraphLayout, rankdir: 'LR' | 'TB'): LayoutOptions
   }
 }
 
+/**
+ * 交互行为。
+ *
+ * 动线视角**刻意关掉 `drag-canvas` 与 `zoom-canvas`**，只留点击：
+ * 画布上的泳道带是叠在画布上的 HTML（`LaneBands`），它按**世界坐标**摆位。
+ * 相机一旦平移或缩放，带子与节点立刻错开 —— 而「段头 + 泳道」正是这个视角的
+ * 全部信息。锁住相机是这套对齐成立的前提，不是省事。
+ *
+ * 关系视图照旧：画布可拖可缩放，节点可拽。
+ */
 export function behaviorsOf(kind: GraphLayout): string[] {
+  if (kind === 'line') return ['click-select']
   // force 布局必须用 drag-element-force：它把拖动写回模拟，松手后图会继续摊开；
   // 用 drag-element 的话拖动只改坐标，力模拟会在下一帧把节点拽回去。
-  return kind === 'force'
-    ? ['drag-canvas', 'zoom-canvas', 'click-select', 'drag-element-force']
-    : ['drag-canvas', 'zoom-canvas', 'click-select', 'drag-element']
+  return ['drag-canvas', 'zoom-canvas', 'click-select', 'drag-element-force']
+}
+
+/**
+ * 动线视角的缩放。**固定 1:1**：世界坐标 = 屏幕像素，HTML 泳道带才能与节点对齐。
+ * 关系视图不锁，用 `zoomRangeFor` 的区间。
+ */
+export const LANE_ZOOM = 1
+
+/** 动线视角里的留白。段位自己带留白，所以这里只留一点点，别把内容挤到中间。 */
+export const LANE_PADDING: Record<StageMode, [number, number, number, number]> = {
+  panel: [0, 0, 0, 0],
+  fullscreen: [0, 0, 0, 0],
 }
 
 /**
  * G6 实例配置。
  *
- * `nodesep` 取 46 而不是默认的 10：假设节点下方挂了标题徽标，行距必须容得下它，
- * 否则同一层里相邻两个节点的徽标会叠在一起。
- *
  * **背景是纯白的，而且刻意不加 `grid-line` 插件。** 井字格在截图和演示里能撑场面，
- * 但它在这张图上是纯噪声：节点位置由力导向决定，网格暗示的「坐标」并不存在；
- * 而这张图上真正要读的是「哪块密、哪里空」，底色越干净越好。
+ * 但它在这张图上是纯噪声：关系视图里节点位置由力导向决定，网格暗示的「坐标」并不
+ * 存在；动线视图里位置由段位决定，网格更没有意义。而这张图真正要读的是「哪块密、
+ * 哪里空」与「哪一段断了」，底色越干净越好（§7.1 两条硬约束之一）。
  */
 export function buildGraphOptions(
   container: { width: number; height: number },
-  layout: GraphLayout = 'force',
+  layout: GraphLayout = 'line',
   rankdir: 'LR' | 'TB' = 'LR',
   mode: StageMode = 'panel',
 ): GraphOptions {
+  const line = layout === 'line'
   return {
     width: container.width,
     height: container.height,
-    background: '#ffffff',
-    autoFit: { type: 'view', options: { when: 'overflow' } },
-    padding: paddingFor(mode),
+    /**
+     * **这里没有 `background`，而且不能加。**
+     *
+     * G6 v5 默认开 `enableMultiLayer`，会在容器里叠四层 canvas，并把 `background`
+     * 只给最底下那层 `background` —— 那是一个**不透明的白色画布**，尺寸铺满容器。
+     * 而容器是泳道带那一层的**后一个兄弟节点**（DOM 顺序在后 = 画在上面），
+     * 且 G6 还给容器设了 `isolation: isolate`。结果就是：**泳道带整个被这块白布盖住**，
+     * 一个字都看不见 —— 而「① 问题现象 3」这些段头正是 §7.7 的核心读数。
+     *
+     * 用无头 Chrome 复刻过四种组合（见 `tests/attribution-layer-order.test.mjs` 的注释）：
+     * 只有「去掉 background」或「把带子挪到画布之后」能让带子出现，两者都做才同时
+     * 满足「看得见」与「点得到」。
+     *
+     * 另外它还是个主题 bug：写死 `#ffffff` 之后，深色主题下画布照样是白的。
+     * 底色由外层容器的 `bg-tita-surface` 提供 —— 那一个跟着主题走。
+     */
+    // 动线视角不能自适应：`autoFit` 会把段位缩放着塞进容器，泳道带随之错位。
+    // 关系视图照旧自适应（那是「哪块密」最直观的一档）。
+    ...(line
+      ? { zoom: LANE_ZOOM }
+      : { autoFit: { type: 'view' as const, options: { when: 'overflow' as const } } }),
+    padding: line ? LANE_PADDING[mode] : paddingFor(mode),
     zoomRange: zoomRangeFor(mode),
     animation: false,
     layout: layoutOf(layout, rankdir),
@@ -353,14 +877,20 @@ export function buildGraphOptions(
       state: {
         selected: { lineWidth: 3, stroke: '#2563eb' },
         active: { lineWidth: 2.6, stroke: '#2563eb' },
+        // 「其余节点透明度降到 0.35」（§7.4 第 9 条）。状态的样式值走 `var()` 共享
+        // 令牌，`DIM_OPACITY` 是它的数值孪生 —— 节点数据在纯函数里算出来时也要用同一
+        // 个数（node:test 里读不到 CSS），两处不同步就会一半亮一半暗。
+        dim: { fillOpacity: DIM_OPACITY, strokeOpacity: DIM_OPACITY, labelOpacity: DIM_OPACITY },
       },
     },
     edge: {
-      // 正交折线是给分层布局用的；力导向里没有「行」的概念，折线反而更乱，
-      // 用二次曲线让交叉点少一点。
-      type: layout === 'force' ? 'quadratic' : 'polyline',
-      style: layout === 'force' ? { curveOffset: 22 } : { radius: 8, router: { type: 'orth' } },
-      state: { selected: { lineWidth: 2.4, stroke: '#2563eb' } },
+      // 段位布局的边一律走折线：起点与终点在相邻两段，折线比曲线更容易顺着读。
+      type: line ? 'polyline' : 'quadratic',
+      style: line ? { radius: 6 } : { curveOffset: 22 },
+      state: {
+        selected: { lineWidth: 2.4, stroke: '#2563eb' },
+        dim: { strokeOpacity: DIM_OPACITY, labelOpacity: DIM_OPACITY },
+      },
     },
     behaviors: behaviorsOf(layout),
   }
@@ -375,7 +905,41 @@ export function buildGraphOptions(
  */
 export function toGraphData(
   data: AttributionGraphData,
-  options: { includeInstance?: boolean; gapIds: ReadonlySet<string>; positions?: Map<string, [number, number]> },
+  /**
+   * 与 `toG6Data` **同一份**入参类型。
+   *
+   * 抄第二份字段清单的下场是它们迟早不一致 —— 而表现是「某个开关在画布上不生效」，
+   * 因为类型在这一层被悄悄丢掉了（加 `layout` 时就正好踩到）。
+   */
+  options: Parameters<typeof toG6Data>[1],
 ): GraphData {
   return toG6Data(data, options) as unknown as GraphData
 }
+
+/**
+ * 画布上的段位矩形（泳道带）。
+ *
+ * 它是 `LaneGeometry` 的**屏幕坐标**视图：HTML 覆盖层按它画带子，画布按同一份
+ * `LaneGeometry` 摆节点。两处共用一套坐标，所以「段头写在哪、哪一段的右边没有线」
+ * 不需要靠眼力对齐。
+ */
+export interface LaneGuide {
+  laneId: string
+  top: number
+  left: number
+  width: number
+  height: number
+  /** 段头带的下沿（相对 guide 顶部）。 */
+  headerHeight: number
+}
+
+export function laneGuides(geometry: LaneGeometry): LaneGuide[] {
+  return geometry.bands.map(band => ({
+    laneId: band.laneId,
+    top: band.top,
+    left: 0,
+    width: geometry.contentWidth,
+    height: band.bottom - band.top,
+    headerHeight: band.headerBottom - band.top,
+  }))
+}