@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/collab/__tests__/entity-presence-badge.test.tsx

@@ -0,0 +1,226 @@
+// 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/>.
+
+// EntityPresenceBadge 单元测试（任务 24，§7.1 列表行「行/卡片上远端在看的
+// 人头像（hover 名单）」）：
+//   ① 同模块同实体的在看者 → 渲染头像组 + tooltip 文案「{name} 正在查看此条目」
+//   ② 无在看者 → 渲染 null（不占位）
+//   ③ excludeSelf：本人不在看者名单
+//   ④ route 不匹配（同模块其他实体）→ null
+//   ⑤ module 不匹配 → null
+//   ⑥ 超过 max 折叠 +N + 溢出 tooltip
+//   ⑦ hover 渐显（行 group-hover 语义）
+//   ⑧ 列表页在场（route=模块根）不算在看该实体
+//
+// tooltip 模块以 passthrough stub 替换（Base UI Tooltip 的 pointerenter
+// 在 jsdom 不可模拟，workspace-kb-card 测试同款口径），文案断言直接命中
+// TooltipContent children。
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Profiler } from "react";
+import { act, render, screen, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { overwriteGetLocale } from "@/paraglide/runtime.js";
+
+overwriteGetLocale(() => "zh");
+
+const mockUseSession = vi.fn();
+
+vi.mock("@/lib/auth/auth-client", () => ({
+  useSession: () => mockUseSession(),
+}));
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: ReactNode }) => (
+    <span data-testid="tooltip-wrapper">{children}</span>
+  ),
+  TooltipContent: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+  TooltipTrigger: ({ render }: { render?: ReactNode }) => (
+    <span data-testid="tooltip-trigger">{render !== undefined ? render : null}</span>
+  ),
+}));
+
+import {
+  __resetPresenceStoreForTests,
+  presenceActions,
+} from "@/lib/collab/presence-store";
+import { EntityPresenceBadge } from "../entity-presence-badge";
+
+function teammate(
+  id: string,
+  username: string,
+  module: string,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    user: { id, username, bgShape: "circle", bgColor: "#fff" },
+    module,
+    route: "/stories",
+    ts: Date.now(),
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  cleanup();
+  __resetPresenceStoreForTests();
+  mockUseSession.mockReturnValue({ data: { user: { id: "self-1" } } });
+});
+
+describe("EntityPresenceBadge", () => {
+  it("同模块同实体在看者 → 渲染头像 + tooltip「{name} 正在查看此条目」", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+
+    expect(container.querySelector('[data-testid="entity-presence-badge"]')).not.toBeNull();
+    expect(screen.getByText("A")).toBeDefined();
+    expect(screen.getByText("alice 正在查看此条目")).toBeDefined();
+  });
+
+  it("无在看者 → 渲染 null（不占位）", () => {
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("excludeSelf：本人不进入在看名单", () => {
+    presenceActions.applyRemote(
+      teammate("self-1", "selfie", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    presenceActions.applyRemote(
+      teammate("u9", "zoe", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+
+    expect(screen.queryByText("S")).toBeNull();
+    expect(screen.getByText("Z")).toBeDefined();
+    expect(container.querySelectorAll('[data-testid="tooltip-trigger"]').length).toBe(1);
+  });
+
+  it("route 不匹配（同模块其他实体）→ null", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/2", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("module 不匹配 → null", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "bugs", { route: "/stories/1", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("超过 max（默认 3）折叠 +N + 溢出 tooltip", () => {
+    ["alice", "bob", "carol", "dave", "eve"].forEach((name, i) => {
+      presenceActions.applyRemote(
+        teammate(`u${i}`, name, "stories", { route: "/stories/1", section: "detail" }),
+      );
+    });
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+
+    expect(screen.getByText("+2")).toBeDefined();
+    expect(screen.getByText("还有 2 人在看")).toBeDefined();
+    // 未展示成员的首字母不出现
+    expect(screen.queryByText("D")).toBeNull();
+    expect(screen.queryByText("E")).toBeNull();
+    // 3 个头像 tooltip 触发器 + 1 个 +N 触发器
+    expect(container.querySelectorAll('[data-testid="tooltip-trigger"]').length).toBe(4);
+  });
+
+  it("hover 渐显（行 group-hover 语义：默认透明，行 hover 显现）", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    const badge = container.querySelector('[data-testid="entity-presence-badge"]')!;
+    expect(badge.className).toContain("opacity-0");
+    expect(badge.className).toContain("group-hover:opacity-100");
+  });
+
+  it("列表页在场（route=模块根）不算在看该实体 → null", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories", section: "list" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("session 未就绪（data 为 null）时不过滤、正常渲染他人", () => {
+    mockUseSession.mockReturnValue({ data: null });
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const { container } = render(
+      <EntityPresenceBadge module="stories" route="/stories/1" />,
+    );
+    expect(container.querySelector('[data-testid="entity-presence-badge"]')).not.toBeNull();
+  });
+
+  it("心跳式 state 重建（内容相等的新数组）→ 徽标零重渲染（Profiler commit 计数，审查重要①）", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail", ts: 100 }),
+    );
+    let commits = 0;
+    render(
+      <Profiler id="badge" onRender={() => { commits += 1; }}>
+        <EntityPresenceBadge module="stories" route="/stories/1" />
+      </Profiler>,
+    );
+    const afterMount = commits;
+
+    act(() => {
+      // 心跳续报：ts 前进、内容不变（applyRemote 重建条目对象）
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail", ts: 200 }),
+      );
+      // 其他模块/其他实体成员的心跳同样重建 store，但与本行无关
+      presenceActions.applyRemote(
+        teammate("u2", "bob", "stories", { route: "/stories/2", section: "detail", ts: 200 }),
+      );
+    });
+    expect(commits).toBe(afterMount);
+
+    // 对照：本行在看者真增（换人加入）→ 正常重渲染
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u3", "carol", "stories", { route: "/stories/1", section: "detail", ts: 300 }),
+      );
+    });
+    expect(commits).toBeGreaterThan(afterMount);
+    expect(screen.getByText("C")).toBeDefined();
+  });
+});

package/src/components/collab/activity-attribution.tsx

@@ -0,0 +1,221 @@
+// 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/>.
+
+// 活动流协同来源渲染（任务 18，规格 §10.2 持久来源）：接受 AuditLog 级
+// 数据（userId 主作者 + metadata.perAuthor），渲染「主作者 + 协同参与者」
+// 头像与「A、B 等 N 人更新了文档」摘要。
+//
+// 独立可复用组件：知识库详情页当前没有任何活动/审计时间线 UI（2026-10-07
+// 核实，components/knowledge 与 routes 全量 grep 无命中），故本组件不做
+// 页面挂载，供后续活动流 UI（计划 T23/P3）直接复用。数据契约 =
+// apps/collab exporters/knowledge.ts writeCollabActivity 的写入口径：
+//   AuditLog {
+//     userId:      主作者（per-author 字节占比最高者）
+//     action:      'document.collab_update'
+//     metadata:    { source, summary, perAuthor[{authorId,updates,bytes,share}], totalBytes }
+//   }
+//
+// 解析 fail-closed：metadata 为 Prisma Json（unknown），非对象/字段形态
+// 不符逐条丢弃，绝不抛错。summary 为服务端数据（中文固定串）不直接渲染，
+// 文案一律走本组件 i18n（T16 报告备案口径）。
+//
+// 安全约束：username 等字符串一律 React 文本节点渲染，无 HTML 注入面。
+
+import { UserAvatar } from '@/components/shared-kit'
+import { cn } from '@/lib/utils'
+import type { AvatarConfig } from '@allbluecn/kernel'
+import { m } from '@/paraglide/messages.js'
+
+/**
+ * per-author 归属行（collab 导出器 CollabAuthorStat 落库形态）。authorId
+ * 恒非空：parser 已丢弃 null/非字符串归属行（全归属失败时导出器整条不写）。
+ */
+export interface CollabPerAuthorEntry {
+  authorId: string
+  updates: number
+  bytes: number
+  share: number
+}
+
+/** 解析产物（source 供调用方过滤协同来源行） */
+export interface ParsedCollabAttribution {
+  source: string | null
+  perAuthor: CollabPerAuthorEntry[]
+  totalBytes: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** 解析单条 perAuthor 行：authorId 缺失/非字符串、数值字段非有限数 → 丢弃 */
+function parsePerAuthorEntry(raw: unknown): CollabPerAuthorEntry | null {
+  if (!isRecord(raw)) return null
+  if (typeof raw.authorId !== 'string' || raw.authorId.length === 0) return null
+  if (typeof raw.updates !== 'number' || !Number.isFinite(raw.updates)) return null
+  if (typeof raw.bytes !== 'number' || !Number.isFinite(raw.bytes)) return null
+  if (typeof raw.share !== 'number' || !Number.isFinite(raw.share)) return null
+  return { authorId: raw.authorId, updates: raw.updates, bytes: raw.bytes, share: raw.share }
+}
+
+/**
+ * 解析 AuditLog.metadata（unknown）为协同归属结构；非对象返回 null，
+ * 畸形条目逐条丢弃（调用方拿到的恒为合法形态）。
+ */
+export function parseCollabAttribution(metadata: unknown): ParsedCollabAttribution | null {
+  if (!isRecord(metadata)) return null
+  const perAuthor: CollabPerAuthorEntry[] = []
+  if (Array.isArray(metadata.perAuthor)) {
+    for (const entry of metadata.perAuthor) {
+      const parsed = parsePerAuthorEntry(entry)
+      if (parsed) perAuthor.push(parsed)
+    }
+  }
+  return {
+    source: typeof metadata.source === 'string' ? metadata.source : null,
+    perAuthor,
+    totalBytes:
+      typeof metadata.totalBytes === 'number' && Number.isFinite(metadata.totalBytes)
+        ? metadata.totalBytes
+        : 0,
+  }
+}
+
+/** 协同活动用户摘要（调用方按 authorId 关联查询后传入） */
+export interface CollabAttributionUser {
+  id: string
+  username: string
+  avatarConfig?: unknown
+  bgShape?: string | null
+  bgColor?: string | null
+}
+
+export interface CollabActivityAttributionProps {
+  /** AuditLog.userId（主作者 = per-author 字节占比最高者） */
+  userId?: string | null
+  /** AuditLog.action（document.collab_update → i18n 标签；其余原样显示） */
+  action?: string | null
+  /** AuditLog.metadata（Prisma Json，任意形态，fail-closed 解析） */
+  metadata?: unknown
+  /** authorId → 用户摘要（未命中者以未知用户占位，不渲染头像） */
+  users?: CollabAttributionUser[]
+  className?: string
+  /** 头像组折叠前最多展示人数（含主作者，超出 +N） */
+  max?: number
+}
+
+/** 摘要文案的姓名折叠上限（「A、B 等 N 人」） */
+const NAME_FOLD = 2
+
+/** 标准协同动作（摘要文案已内嵌该语义，不重复追加） */
+const COLLAB_UPDATE_ACTION = 'document.collab_update'
+
+export function CollabActivityAttribution({
+  userId,
+  action,
+  metadata,
+  users = [],
+  className,
+  max = 3,
+}: CollabActivityAttributionProps) {
+  const parsed = parseCollabAttribution(metadata)
+  const userById = new Map(users.map((u) => [u.id, u]))
+  const primary = userId ? (userById.get(userId) ?? null) : null
+
+  const attributed = parsed?.perAuthor ?? []
+  if (!primary && attributed.length === 0) return null
+
+  // 参与者 = perAuthor 按字节占比降序（主作者通常居首）；已知用户取头像，
+  // 未知用户只计入人数（宁缺勿错，不造占位头像）。
+  const ranked = attributed
+    .slice()
+    .sort((a, b) => b.bytes - a.bytes || b.updates - a.updates)
+  const contributors = ranked
+    .map((entry) => ({
+      entry,
+      user: userById.get(entry.authorId) ?? null,
+    }))
+
+  // 摘要文案：单人 → 「{name} 更新了文档」；多人 → 「A、B 等 N 人更新了
+  // 文档」；多人但姓名全不可解析 → 「N 人更新了文档」（避免「 等 3 人…」）
+  const attributedCount = attributed.length
+  let summary: string
+  if (attributedCount <= 1) {
+    const name = contributors[0]?.user?.username ?? primary?.username ?? m.collab_activityUnknownUser()
+    summary = m.collab_activitySingle({ name })
+  } else {
+    const resolvable = contributors.filter((c) => c.user).slice(0, NAME_FOLD)
+    const names = resolvable.map((c) => c.user!.username).join('、')
+    summary = names
+      ? m.collab_activityMany({ names, count: attributedCount })
+      : m.collab_activityCountOnly({ count: attributedCount })
+  }
+
+  // 头像组：可解析用户按占比序展示（去重），折叠 +N
+  const avatarUsers = contributors
+    .filter((c) => c.user)
+    .map((c) => ({
+      user: c.user!,
+      share: c.entry.share,
+      isPrimary: c.entry.authorId === userId,
+    }))
+  const deduped = avatarUsers.filter(
+    (item, i) => avatarUsers.findIndex((x) => x.user.id === item.user.id) === i,
+  )
+  const shown = deduped.slice(0, max)
+  const rest = Math.max(0, deduped.length - max)
+
+  return (
+    <div
+      data-testid="collab-activity-attribution"
+      className={cn('flex items-center gap-2 min-w-0', className)}
+    >
+      <div className="flex items-center -space-x-1.5 shrink-0">
+        {shown.map(({ user, share, isPrimary }) => (
+          <div
+            key={user.id}
+            data-testid={`collab-activity-user-${user.id}`}
+            title={m.collab_activityShare({
+              name: user.username,
+              percent: Math.round(share * 100),
+            })}
+            className="ring-1 ring-background rounded-full"
+          >
+            <UserAvatar
+              name={user.username}
+              avatarConfig={(user.avatarConfig ?? null) as AvatarConfig | null}
+              bgShape={user.bgShape}
+              bgColor={user.bgColor ?? undefined}
+              size="xs"
+            />
+          </div>
+        ))}
+        {rest > 0 && (
+          <span className="flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1 text-[10px] font-medium text-muted-foreground ring-1 ring-background">
+            +{rest}
+          </span>
+        )}
+      </div>
+      <span className="text-xs text-muted-foreground truncate">
+        {summary}
+        {action && action !== COLLAB_UPDATE_ACTION ? (
+          <span className="text-muted-foreground/70"> · {action}</span>
+        ) : null}
+      </span>
+    </div>
+  )
+}

package/src/components/collab/canvas-collab-panel.tsx

@@ -0,0 +1,104 @@
+// 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/>.
+
+// 画布协作者面板（任务 30，规格 §7.1 设计画布行「元素级『X 正在编辑』面板
+// 提示」）：此页协作者头像组（数据源同 T25 viewer badge——canvas room 的
+// RemoteCanvasPresence 列表）+ 元素级编辑提示（远端选中集/拖拽影子对应元素
+// 名）。presentational 组件：remotes/doc 均由 presence-layer 注入，自身不建
+// 连、不读 awareness、不碰引擎（可无头单测）。
+//
+// 挂载：presence-layer 容器内画布视口顶部居中（pointer-events-auto 仅内层
+// pill，不拦画布框选）；与 T25 左上角人数徽标并存——徽标是极简计数，本面板
+// 是完整在场视图（头像 + 谁/在编辑什么）。
+//
+// 渲染纪律：无选中无拖拽 = 旁观（N 人正在查看）；任一远端在编辑/拖拽 = 编辑
+// 提示（多人收敛为「X 等 N 人正在编辑」）；元素名取本地 doc 同 id 节点 name
+// （已删/未加载退化为无元素名形态）；空名降级「未知用户」（全 collab 口径）。
+
+import { m } from '@/paraglide/messages.js'
+import type { RemoteCanvasPresence } from '@/lib/collab/bindings/canvas-presence'
+import { getUserColor } from '@/lib/collab/user-color'
+import type { SceneDocument } from '@/components/design/canvas/document/types'
+
+export interface CanvasCollabPanelProps {
+  /** 此页远端在场快照（presence-layer readRemotes 产物，含 drag 影子） */
+  remotes: RemoteCanvasPresence[]
+  /** 本地画布文档（元素名解析；null = 未就绪，元素名退化） */
+  doc: SceneDocument | null
+}
+
+/** 展示名兜底（空名降级，同 viewer badge / 名牌口径） */
+function displayName(name: string): string {
+  return name.length > 0 ? name : m.collab_activityUnknownUser()
+}
+
+/** 单个远端是否处于编辑/拖拽态 */
+function isEditing(remote: RemoteCanvasPresence): boolean {
+  return remote.selection.length > 0 || (remote.drag?.items.length ?? 0) > 0
+}
+
+/** 编辑目标元素名：优先选中集首元素，拖拽中取影子首元素；已删/无 doc 返回 null */
+function editingNodeName(remote: RemoteCanvasPresence, doc: SceneDocument | null): string | null {
+  const nodeId = remote.selection[0] ?? remote.drag?.items[0]?.id
+  if (!nodeId || !doc) return null
+  return doc.nodes.find((node) => node.id === nodeId)?.name ?? null
+}
+
+export function CanvasCollabPanel({ remotes, doc }: CanvasCollabPanelProps) {
+  if (remotes.length === 0) return null
+
+  const editors = remotes.filter(isEditing)
+  const first = editors[0]
+  let hint: string
+  if (editors.length === 0) {
+    hint = m.collab_canvasViewersCount({ count: remotes.length })
+  } else if (editors.length === 1) {
+    const nodeName = editingNodeName(first, doc)
+    hint = nodeName
+      ? m.collab_canvasEditingNode({ name: displayName(first.name), node: nodeName })
+      : m.collab_fieldEditingBy({ name: displayName(first.name) })
+  } else {
+    hint = m.collab_canvasEditingCount({ name: displayName(first.name), count: editors.length })
+  }
+
+  return (
+    <div
+      data-testid="canvas-collab-panel"
+      className="pointer-events-none absolute left-1/2 top-2 z-20 -translate-x-1/2"
+    >
+      <div
+        className="pointer-events-auto flex items-center gap-2 rounded-full border border-border bg-background/90 px-2.5 py-1 shadow-sm"
+        aria-label={hint}
+      >
+        <span className="flex -space-x-1">
+          {remotes.map((remote) => (
+            <span
+              key={remote.clientId}
+              data-collab-avatar={remote.userId}
+              aria-label={displayName(remote.name)}
+              className="inline-block size-3 rounded-full border border-background"
+              style={{ backgroundColor: getUserColor(remote.userId) }}
+            />
+          ))}
+        </span>
+        <span data-collab-editing-hint className="max-w-70 truncate text-[10px] leading-none text-muted-foreground">
+          {hint}
+        </span>
+      </div>
+    </div>
+  )
+}