@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/bindings/steps.ts

@@ -0,0 +1,332 @@
+// 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/>.
+
+// 步骤级协同绑定层（Yjs 多人协作 §7.1 steps 行，任务 22；消费方：TestCase
+// 详情 StepEditor、Bug 详情只读步骤视图、exporter 落库回写）。
+//
+// Y 结构契约（同 fields.ts 文件头）：entity room 的
+//   doc.getArray('steps'): Y.Array<Y.Map<'action'|'expected', string>>
+// 数组顺序即步骤顺序；order（业务列 1 起序号）不入 Y——exporter 落库按
+// 索引+1 归一（@allbluecn/collab-core/steps 为服务端权威实现，key 单源）。
+//
+// 冲突语义：
+// - 插入/删除：Y.Array 相对定位自动合并——「A 插入步骤 3 / B 删除步骤 2」
+//   收敛为两操作都生效，双方顺序一致（bindings-steps.test 场景①）；
+// - 相邻移动（StepEditor ±1 唯一 UI 路径）：两行 Y.Map 字段互写（仅写差异
+//   字段）——不动 Y.Array 结构、零 tombstone；并发改任一行内容走 per-key
+//   LWW（高 clientID 方可胜出），不再有「被移项 map 被 delete」的结构性
+//   内容丢失（审查修复①）；
+// - 非相邻移动（防御保留，UI 无此路径）：delete+insert 同事务原子提交
+//   （Y.Array 无原生 move；移动项实例身份换新，落在其上的并发字段编辑会
+//   结构性丢失——UI 开放非相邻移动/拖拽排序时应换 move 协议，见实现注释
+//   升级点）；
+// - 字段修改：per-key LWW（同 Y.Map 字段语义），并发改不同键双存、同键
+//   确定收敛。
+//
+// 「空 Y.Array = Y 无意见」：业务 schema 步骤 min(1)，空步骤集永不合法，
+// 故空数组安全解释为「room 从未写过步骤」——UI 侧以此回退 loader DTO 展示
+// （Bug 只读视图），exporter 以此跳过业务 steps 列（collab-core/steps 同口径）。
+//
+// 分层同 fields.ts：createStepBinding 无 React 依赖（双 Y.Doc 直连可单测），
+// useCollabSteps 是 useSyncExternalStore 薄封装。不触碰 awareness（§7.1 的
+// 行级 editing 标记留待后续任务——行索引随远端插入/删除漂移，直接标记会
+// 指错行，需先引入稳定行身份再接 awareness）。
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import * as Y from 'yjs'
+import { COLLAB_STEPS_ARRAY_KEY } from '@allbluecn/collab-core/steps'
+import type {
+  CollabConnectionStatus,
+  CollabProviderHandle,
+} from '../provider'
+
+/** 单步快照值（expected 恒为字符串，空串 = 未填——StepEditor 草稿口径） */
+export interface CollabStepValue {
+  action: string
+  expected: string
+}
+
+/**
+ * 绑定数据源（与 fields.ts 的 FieldBindingSource 同形——真实 handle 结构
+ * 兼容直传；测试注入最小 fake。awareness 本绑定不使用，字段保留同形以复用
+ * handle 直传）。
+ */
+export interface StepBindingSource {
+  readonly doc: Y.Doc
+  readonly awareness: unknown | null
+  /** 连接状态订阅（真实 handle 契约：订阅即回放当前状态） */
+  onStatusChange(listener: (status: CollabConnectionStatus) => void): () => void
+}
+
+export interface StepBinding {
+  /** 单调递增变更计数（useSyncExternalStore 快照缓存键） */
+  version(): number
+  /** 读步骤快照（每次现读并新建数组/对象——快照安全；空数组 = Y 无意见） */
+  readSteps(): CollabStepValue[]
+  /** 在 index 处插入一步（越界钳制到 [0, len]） */
+  insertStep(index: number, step: CollabStepValue): void
+  /** 删除 index 处一步（越界 no-op） */
+  removeStep(index: number): void
+  /** 把 from 步移动到 to（delete+insert 同事务原子提交；越界钳制） */
+  moveStep(from: number, to: number): void
+  /** 改 index 步的字段（per-key LWW；越界 no-op） */
+  updateStep(index: number, patch: Partial<CollabStepValue>): void
+  /** 原子清空重灌全部步骤（测试种子对齐 / 未来对账兜底） */
+  replaceSteps(steps: CollabStepValue[]): void
+  /** 订阅变更（插入/删除/移动/字段修改任意变化），返回退订函数 */
+  subscribe(listener: () => void): () => void
+  /** 清理：摘 observer、断状态订阅 */
+  destroy(): void
+}
+
+/** 空快照常量（绑定创建前与降级路径共用同一引用，Object.is 稳定） */
+const EMPTY_STEPS: CollabStepValue[] = []
+
+export function createStepBinding(source: StepBindingSource): StepBinding {
+  const stepsArray =
+    source.doc.getArray<Y.Map<unknown>>(COLLAB_STEPS_ARRAY_KEY)
+
+  let version = 0
+  let destroyed = false
+  const listeners = new Set<() => void>()
+
+  const notify = () => {
+    version += 1
+    for (const listener of listeners) listener()
+  }
+
+  // observeDeep：嵌套 Y.Map 的字段 set（updateStep）不触发数组浅层 observer，
+  // 必须深观察才能把「改步骤字段」响应给远端与本端订阅者
+  const onDeepChange = () => notify()
+  stepsArray.observeDeep(onDeepChange)
+
+  // 快照缓存（按 version 键）：readSteps 每次新建数组/对象，useSyncExternalStore
+  // 以 Object.is 比对快照——无缓存则同版本内每次现读都返回新引用，触发无限重渲染
+  // （fields.ts 同款缓存口径）。notify 先 bump version 再叫醒订阅者，读侧恒新。
+  let cachedSteps: CollabStepValue[] = EMPTY_STEPS
+  let cachedStepsVersion = -1
+
+  const clamp = (value: number, max: number) =>
+    Math.max(0, Math.min(Math.floor(value), max))
+
+  /** 读合法索引处的条目；越界返回 null（防御远端并发位移后的 stale 索引） */
+  const at = (index: number): Y.Map<unknown> | null => {
+    const i = Math.floor(index)
+    if (!Number.isFinite(i) || i < 0 || i >= stepsArray.length) return null
+    const item = stepsArray.get(i)
+    return item instanceof Y.Map ? item : null
+  }
+
+  /** Y.Map 条目 → 快照值（契约外/非法类型归一空串，同 readSteps 口径） */
+  const readMapValue = (item: Y.Map<unknown>): CollabStepValue => ({
+    action: typeof item.get('action') === 'string' ? (item.get('action') as string) : '',
+    expected:
+      typeof item.get('expected') === 'string' ? (item.get('expected') as string) : '',
+  })
+
+  /**
+   * 就地写入快照值（与 toYMap 键口径对称：expected 空串 = 删除键）；等值
+   * 字段跳过不产生 op——相邻交换只写有差异的字段，缩小并发竞争面。
+   */
+  const applyStepValue = (item: Y.Map<unknown>, value: CollabStepValue): void => {
+    if (item.get('action') !== value.action) item.set('action', value.action)
+    if (value.expected === '') {
+      if (item.get('expected') !== undefined) item.delete('expected')
+    } else if (item.get('expected') !== value.expected) {
+      item.set('expected', value.expected)
+    }
+  }
+
+  const toYMap = (step: CollabStepValue): Y.Map<unknown> => {
+    const map = new Y.Map<unknown>()
+    map.set('action', step.action)
+    if (step.expected !== '') map.set('expected', step.expected)
+    return map
+  }
+
+  return {
+    version: () => version,
+
+    readSteps: () => {
+      if (cachedStepsVersion === version) return cachedSteps
+      const out: CollabStepValue[] = []
+      for (const item of stepsArray) {
+        // 契约外条目（非 Y.Map）跳过不抛错；action/expected 归一字符串
+        if (!(item instanceof Y.Map)) continue
+        out.push({
+          action: typeof item.get('action') === 'string' ? (item.get('action') as string) : '',
+          expected:
+            typeof item.get('expected') === 'string' ? (item.get('expected') as string) : '',
+        })
+      }
+      cachedStepsVersion = version
+      cachedSteps = out
+      return out
+    },
+
+    insertStep: (index, step) => {
+      if (destroyed) return
+      stepsArray.insert(clamp(index, stepsArray.length), [toYMap(step)])
+    },
+
+    removeStep: (index) => {
+      if (destroyed) return
+      // 越界 no-op（不钳制——stale 索引删错相邻行比不删更糟）
+      if (Math.floor(index) < 0 || Math.floor(index) >= stepsArray.length) return
+      stepsArray.delete(Math.floor(index), 1)
+    },
+
+    moveStep: (from, to) => {
+      if (destroyed) return
+      const len = stepsArray.length
+      if (len === 0) return
+      const i = Math.floor(from)
+      const j = Math.floor(to)
+      if (i < 0 || i >= len) return
+      if (i === j) return
+      // ── 相邻交换（审查修复①，StepEditor ±1 是唯一 UI 路径）：两行 Y.Map
+      // 字段互写——不动 Y.Array 结构、零 tombstone。并发改任一行内容时走
+      // per-key LWW（高 clientID 方可胜出）而非 delete+insert 的结构性丢失
+      // （被移项 map 被 delete，落在其上的并发编辑必然丢失、无竞争机会）。
+      // 仅写有差异的字段：等值字段不产生 op，缩小并发竞争面。
+      if (Math.abs(i - j) === 1) {
+        const upper = at(Math.min(i, j))
+        const lower = at(Math.max(i, j))
+        if (!upper || !lower) return
+        const upperValue = readMapValue(upper)
+        const lowerValue = readMapValue(lower)
+        source.doc.transact(() => {
+          applyStepValue(upper, lowerValue)
+          applyStepValue(lower, upperValue)
+        })
+        return
+      }
+      // ── 非相邻（当前 UI 无此路径，防御保留）：Yjs 不支持重插已 delete 的
+      // 类型实例——读值 → delete → 以新 Y.Map 承载同值 insert（同事务原子
+      // 提交，一次 update 广播远端原子应用）。⚠ 实例身份换新：落在被移项上
+      // 的并发字段编辑会结构性丢失——升级点：若未来 UI 开放非相邻移动/拖拽
+      // 排序，应换 Y.Element 级 move 协议（如 y-move 扩展或 order 权重字段）。
+      const item = at(i)
+      if (!item) return
+      const snapshot = readMapValue(item)
+      source.doc.transact(() => {
+        stepsArray.delete(i, 1)
+        // 删除后长度 -1；to 语义按删除后的目标位（Visual 移动直觉口径），
+        // 越界钳制到尾部
+        stepsArray.insert(clamp(j, stepsArray.length), [toYMap(snapshot)])
+      })
+    },
+
+    updateStep: (index, patch) => {
+      if (destroyed) return
+      const item = at(index)
+      // 越界 no-op（不钳制——stale 索引改错相邻行比不改更糟）
+      if (!item) return
+      if (patch.action !== undefined) item.set('action', patch.action)
+      if (patch.expected !== undefined) {
+        // 空串归一为删除键（与 collab-core stepToYMap 写入口径对称）
+        if (patch.expected === '') item.delete('expected')
+        else item.set('expected', patch.expected)
+      }
+    },
+
+    replaceSteps: (steps) => {
+      if (destroyed) return
+      source.doc.transact(() => {
+        if (stepsArray.length > 0) stepsArray.delete(0, stepsArray.length)
+        if (steps.length > 0) stepsArray.insert(0, steps.map(toYMap))
+      })
+    },
+
+    subscribe: (listener) => {
+      if (destroyed) return () => {}
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+
+    destroy: () => {
+      if (destroyed) return
+      destroyed = true
+      stepsArray.unobserveDeep(onDeepChange)
+      listeners.clear()
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// React 封装（任务 22 消费面）
+// ---------------------------------------------------------------------------
+
+export interface UseCollabStepsResult {
+  /** 步骤快照（空数组 = Y 无意见，UI 回退 loader DTO 展示） */
+  steps: CollabStepValue[]
+  insertStep(index: number, step: CollabStepValue): void
+  removeStep(index: number): void
+  moveStep(from: number, to: number): void
+  updateStep(index: number, patch: Partial<CollabStepValue>): void
+  replaceSteps(steps: CollabStepValue[]): void
+}
+
+/**
+ * 绑定一个 entity room 的步骤列表（§7.1 steps 行）。handle 为 null（SSR/noop
+ * 上游）时全链路降级：steps 恒空、操作 no-op。生命周期边界同 useCollabFields
+ * （binding 随首个非 null handle 创建一次，卸载销毁；实体切换由路由 key 重建
+ * 承接）。
+ */
+export function useCollabSteps(
+  handle: CollabProviderHandle | null,
+): UseCollabStepsResult {
+  const [binding] = useState<StepBinding | null>(() =>
+    handle ? createStepBinding(handle) : null,
+  )
+  const bindingRef = useRef(binding)
+  bindingRef.current = binding
+  useEffect(() => () => binding?.destroy(), [binding])
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => binding?.subscribe(onStoreChange) ?? (() => {}),
+    [binding],
+  )
+  const getSnapshot = useCallback(
+    () => (binding ? binding.readSteps() : EMPTY_STEPS),
+    [binding],
+  )
+  const steps = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  const insertStep = useCallback(
+    (index: number, step: CollabStepValue) => bindingRef.current?.insertStep(index, step),
+    [],
+  )
+  const removeStep = useCallback((index: number) => bindingRef.current?.removeStep(index), [])
+  const moveStep = useCallback(
+    (from: number, to: number) => bindingRef.current?.moveStep(from, to),
+    [],
+  )
+  const updateStep = useCallback(
+    (index: number, patch: Partial<CollabStepValue>) =>
+      bindingRef.current?.updateStep(index, patch),
+    [],
+  )
+  const replaceSteps = useCallback(
+    (next: CollabStepValue[]) => bindingRef.current?.replaceSteps(next),
+    [],
+  )
+
+  return { steps, insertStep, removeStep, moveStep, updateStep, replaceSteps }
+}

package/src/lib/collab/env.ts

@@ -0,0 +1,33 @@
+// 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/>.
+
+// 协同连接开关（§6）：desktop 版或未配置 VITE_COLLAB_WS_URL → 协同不可用，
+// provider 层返回 noop（编辑器走单机模式，presence UI 不渲染）。
+// 刻意做成调用时读取（非模块常量）：vi.stubEnv 可按用例切换，SSR 与
+// 客户端导航双态安全（import.meta.env 由 Vite define 静态注入）。
+
+import { isDesktopEdition } from '@/lib/edition-desktop'
+
+/** 协作 WebSocket 服务地址（构建期注入，未配置为空串） */
+export function getCollabWsUrl(): string {
+  return (import.meta.env.VITE_COLLAB_WS_URL as string | undefined) ?? ''
+}
+
+/** 协同功能是否可用：非 desktop 版且已配置 WS 地址 */
+export function isCollabEnabled(): boolean {
+  return !isDesktopEdition() && getCollabWsUrl() !== ''
+}

package/src/lib/collab/module-map.ts

@@ -0,0 +1,131 @@
+// 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/>.
+
+// sidebar-routes route.id ↔ presence module key 映射（§8.1）+ 路由 → presence
+// 状态构造。纯同构模块（零 React / 零网络依赖），presence-store 与
+// use-presence-report 共用。
+//
+// 口径对齐：
+// - 前缀匹配同 src/lib/sidebar-utils.ts isPathActive（pathname === link 或
+//   startsWith(`${link}/`)，不误伤 /bugs-x 这类同前缀路由）。
+// - MODULE_ROUTES 的 id/link 必须与 src/config/sidebar-routes.tsx 的
+//   workspaceRoutes 逐条镜像（presence-store.test.ts 有镜像测试钉住防漂移）；
+//   knowledge 不在 workspaceRoutes（nav-knowledge 组件硬编码 /knowledge/*），
+//   在此手动补录。
+// - 未命中任何前缀（如 /settings）→ 调用方回落 'other'（上报但不落任何
+//   侧边栏行，§8.2 本期只做一级 10+1 模块）。
+//
+// section 启发式：仅实体模块（stories/bugs/test-cases/design/knowledge）
+// 派生——精确命中模块 link → 'list'，更深路径 → 'detail'；board/editor 由
+// 后续任务（P3 列表 / P4 画布）经 presence-store action 显式覆盖，此处不猜。
+
+import type { PresenceModule, PresenceSection, PresenceState, PresenceUser } from './presence-store'
+
+/** 一级模块 key（§8.1 枚举 + workspaceRoutes 全量覆盖 + other 兜底） */
+export const PRESENCE_MODULES = [
+  'dashboard',
+  'harness',
+  'inspiration',
+  'stories',
+  'design',
+  'test-cases',
+  'bugs',
+  'task',
+  'knowledge',
+  'other',
+] as const satisfies readonly PresenceModule[]
+
+/** 未命中任何模块前缀时的兜底 key（上报位置但不匹配任何侧边栏行） */
+export const OTHER_MODULE: PresenceModule = 'other'
+
+/** section 启发式适用的实体模块（dashboard/harness 等无列表/详情之分） */
+const ENTITY_MODULES: ReadonlySet<string> = new Set([
+  'stories',
+  'bugs',
+  'test-cases',
+  'design',
+  'knowledge',
+])
+
+export interface ModuleRouteDef {
+  /** sidebar-routes Route.id（任务 10 nav-main 按 id 匹配渲染头像组） */
+  id: string
+  /** presence module key（§8.1） */
+  module: PresenceModule
+  /** 模块根路径（前缀匹配锚点，与 Route.link 一致） */
+  link: string
+}
+
+/**
+ * route.id ↔ module 映射表。按 link 长度降序排列（前缀匹配优先命中最长
+ * 前缀，防未来出现 /bugs 与 /bugs-board 类嵌套前缀时误判）。
+ */
+export const MODULE_ROUTES: readonly ModuleRouteDef[] = [
+  { id: 'testcase', module: 'test-cases', link: '/test-cases' },
+  { id: 'knowledge', module: 'knowledge', link: '/knowledge' },
+  { id: 'inspiration', module: 'inspiration', link: '/inspiration' },
+  { id: 'home', module: 'dashboard', link: '/dashboard' },
+  { id: 'harness', module: 'harness', link: '/harness' },
+  { id: 'story', module: 'stories', link: '/stories' },
+  { id: 'design', module: 'design', link: '/design' },
+  { id: 'task', module: 'task', link: '/tasks' },
+  { id: 'bug', module: 'bugs', link: '/bugs' },
+]
+
+export interface ModuleLocation {
+  module: PresenceModule
+  section?: PresenceSection
+}
+
+/**
+ * 路由前缀 → 模块归属（isPathActive 同口径）。未命中返回 null（调用方
+ * 回落 OTHER_MODULE）；命中实体模块时按路径深度派生 section。
+ */
+export function resolveModuleLocation(pathname: string): ModuleLocation | null {
+  for (const route of MODULE_ROUTES) {
+    const isExact = pathname === route.link
+    const isDescendant = pathname.startsWith(`${route.link}/`)
+    if (!isExact && !isDescendant) continue
+    if (!ENTITY_MODULES.has(route.module)) return { module: route.module }
+    return { module: route.module, section: isExact ? 'list' : 'detail' }
+  }
+  return null
+}
+
+/** 路由变化节流上报口径（§8.1：useThrottledCallback 2s，pacer 统一） */
+export const PRESENCE_REPORT_THROTTLE_MS = 2000
+
+/**
+ * 由当前路径构造 awareness local state（§8.1）：剥 query（脱敏）、解析
+ * 模块归属与 section、打时间戳。ts 由调用方传入（awareness 上报方时钟）。
+ */
+export function buildPresenceState(
+  user: PresenceUser,
+  pathname: string,
+  ts: number,
+): PresenceState {
+  // 剥 query 与 hash：presence route 只保留纯路径（§8.1「脱敏：剥 query」）
+  const purePath = pathname.split('?')[0]!.split('#')[0]!
+  const location = resolveModuleLocation(purePath)
+  return {
+    user,
+    module: location?.module ?? OTHER_MODULE,
+    route: purePath,
+    section: location?.section,
+    ts,
+  }
+}