From 1306df2b35185e159651d16b5aee7c7ca861a2ef Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 01:46:09 +0800 Subject: [PATCH] docs(workspace): explain host page and sidebar lifecycles --- src/app/dashboard/dashboard.tsx | 25 +++++++++++++++++ src/components/workspace/account-panel.tsx | 9 ++++++ src/components/workspace/active-board.tsx | 8 ++++++ src/components/workspace/board-directory.tsx | 8 ++++++ .../workspace/canvas-runtime-host.tsx | 18 ++++++++++++ src/components/workspace/editable-title.tsx | 14 ++++++++++ src/components/workspace/graph-page.tsx | 28 +++++++++++++++++++ src/components/workspace/user-avatar.tsx | 5 ++++ 8 files changed, 115 insertions(+) diff --git a/src/app/dashboard/dashboard.tsx b/src/app/dashboard/dashboard.tsx index f3654e1..e946ec0 100644 --- a/src/app/dashboard/dashboard.tsx +++ b/src/app/dashboard/dashboard.tsx @@ -1,3 +1,8 @@ +/** + * 工作台共享侧栏与浮动快捷条。管理账户/工作区目录、搜索、折叠、改名和账户面板， + * 活动board元数据来自Context，画布业务状态由RuntimeHost拥有；这里不持有第二份元素文档。 + * 浮动条在画布路由或侧栏折叠时显示，展开按钮仅在折叠时显示，收起按钮留在展开侧栏中。 + */ "use client"; import { useEffect, useRef, useState } from "react"; @@ -19,6 +24,7 @@ import { loadBoardDirectory } from "@/lib/board-directory"; import { BoardDirectory } from "@/components/workspace/board-directory"; import styles from "@/components/workspace/workspace.module.css"; +/** 路径/查询参数优先定位空间，目录解析真实ID，UI状态与账户/目录异步生命周期分别维护。 */ export default function DashboardSidebar() { const router = useRouter(); const runtimeHost = useCanvasRuntimeHost(); @@ -42,13 +48,16 @@ export default function DashboardSidebar() { const expandButton = useRef(null); const collapseButton = useRef(null); const hasToggled = useRef(false); + // 同步ref防重复点击创建，listVersion隔离迟到目录列表；二者都不是runtime账户authEpoch。 const createLock = useRef(false); const listVersion = useRef(0); const accountPopup = useRef(null); + // 路径workspace优先于查询和本地选择；slug由目录解析，活动board可补充该路由引用的真实ID。 const workspaceRef = params.workspace || searchParams.get("workspace") || selectedWorkspace; const currentWorkspace = workspaces.find((item) => matchesRef(item, workspaceRef)); const workspace = currentWorkspace?.id || (activeBoard?.workspace_ref === workspaceRef ? activeBoard.workspace_id : workspaceRef); + /** demo用本地资料，真实模式并行加载profile/空间；active+signal阻止卸载后的资料结果写入。 */ useEffect(() => { if (demo) { setProfile({ id: "demo", username: "creator", display_name: "创作者", email: null }); @@ -77,6 +86,7 @@ export default function DashboardSidebar() { return () => { active = false; controller.abort(); }; }, [demo, router]); + /** 每次目录加载先留本空间项，再取完整分页；仅最新listVersion可采用列表，换空间时中断旧请求。 */ useEffect(() => { if (!workspace || status !== "ready") return; const version = ++listVersion.current; @@ -93,13 +103,17 @@ export default function DashboardSidebar() { return () => { active = false; controller.abort(); }; }, [workspace, demo, status, directoryRevision]); + /** 同工作区目录变化事件合并100ms后重读，清理时撤销计时和监听，不跨空间误刷新。 */ useEffect(() => { let timer: ReturnType; + /** 忽略其它workspace事件；多次事件只触发一次revision递增和后续完整目录读取。 */ const refresh = (event: Event) => { if ((event as CustomEvent).detail?.workspace !== workspace) return; clearTimeout(timer); timer = setTimeout(() => setDirectoryRevision((value) => value + 1), 100); }; window.addEventListener("endoleap:board-directory-changed", refresh); return () => { clearTimeout(timer); window.removeEventListener("endoleap:board-directory-changed", refresh); }; }, [workspace]); + /** 就绪且未重复创建才执行，真实模式必要时先建个人空间，demo只写本地目录。 + * 成功递增listVersion防旧列表盖掉新项，再清搜索并导航；创建锁仅保护此UI操作，不替代账户身份护栏。 */ async function newPage() { if (createLock.current || status !== "ready") return; createLock.current = true; @@ -121,6 +135,7 @@ export default function DashboardSidebar() { finally { createLock.current = false; setCreating(false); } } + /** 用户实际切换折叠后，下一帧聚焦新出现的展开/收起按钮；初始渲染不抢焦点。 */ useEffect(() => { if (!hasToggled.current) return; const frame = requestAnimationFrame(() => { @@ -129,17 +144,20 @@ export default function DashboardSidebar() { return () => cancelAnimationFrame(frame); }, [collapsed]); + /** 先关闭账户popover再切布局，避免旧锚点残留弹层；焦点转移交给effect。 */ function toggleSidebar(value: boolean) { accountPopup.current?.hidePopover(); hasToggled.current = true; setCollapsed(value); } + /** 关闭popover后打开设置/新空间对话框，避免两层交互同时争焦点。 */ function openPanel(mode: "settings" | "workspace") { accountPopup.current?.hidePopover(); setPanel(mode); } + /** 真实退出先retireIdentity并完成本地关闭/保存，再请求服务登出；失败留在当前界面报告，不跳过保存。 */ async function logout() { try { if (!demo) { await runtimeHost.retireIdentity(); await api("auth/logout", { method: "POST" }); } @@ -147,13 +165,17 @@ export default function DashboardSidebar() { } catch (e) { setError(errorText(e)); } } + // 已解析活动board标题优先，退回目录标题或加载文案；不从另一工作区的活动记录借名。 const currentTitle = activeBoard && matchesRef(activeBoard, params.board) && activeBoard.workspace_id === workspace ? activeBoard.title : boards.find((board) => matchesRef(board, params.board))?.title || (params.board ? "正在读取图谱…" : "工作空间"); const name = profile?.display_name || profile?.username || "账户"; + // 计数用标题直接匹配；树中保留的搜索祖先由BoardDirectory独立派生，因此数目不等于所有可见行数。 const filtered = boards.filter((b) => b.title.toLocaleLowerCase().includes(query.trim().toLocaleLowerCase())); + // UI能力只作提示/禁用，真实创建权限仍由服务端判定，未知空间不能当成已有编辑权限。 const canCreate = status === "ready" && (!workspace || Boolean(currentWorkspace && currentWorkspace.role !== "viewer")); + /** 成功后同时更新本地目录与匹配的活动board元数据；错误转换成文案交EditableTitle保留草稿显示。 */ async function renameTitle(title: string) { const id = activeBoard?.id || params.board; if (!id || !workspace) return; @@ -167,11 +189,14 @@ export default function DashboardSidebar() { } catch (error) { throw new Error(errorText(error)); } } + // 创建入口复用同一busy/权限状态，降低重复点击，但不在render中发请求。 const createButton = ; + // 尊重减少动态效果偏好；折叠侧栏同时inert/aria-hidden，避免不可见内容仍接受键盘交互。 const transition = { duration: reduceMotion ? 0 : 0.24, ease: [0.22, 1, 0.36, 1] as const }; const roleLabel = currentWorkspace?.role === "admin" ? "管理员" : currentWorkspace?.role === "editor" ? "编辑者" : currentWorkspace?.role === "viewer" ? "查看者" : "工作空间"; + // 展示分为浮动条、侧栏目录、共享账户popover和账户面板；路由/空间作为key让标题及目录局部状态重置。 return ( <> diff --git a/src/components/workspace/account-panel.tsx b/src/components/workspace/account-panel.tsx index 92d731e..185b087 100644 --- a/src/components/workspace/account-panel.tsx +++ b/src/components/workspace/account-panel.tsx @@ -1,3 +1,7 @@ +/** + * 账户资料编辑与新建工作区共用的客户端对话框。保存后通过回调更新宿主目录/资料，再关闭； + * demo分支只构造本地结果，真实分支走profile PATCH或workspaces POST，不由组件直接操作canvas runtime。 + */ "use client"; import { useState, type FormEvent } from "react"; @@ -7,6 +11,7 @@ import type { Workspace } from "@/lib/workspace"; import { UserAvatar } from "./user-avatar"; import styles from "./workspace.module.css"; +/** mode决定表单，busy控制当前提交和退出，error用于就地反馈；输入默认值来自打开时profile。 */ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorkspace }: { mode: "settings" | "workspace"; profile: Profile; @@ -20,6 +25,8 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp const settings = mode === "settings"; const name = profile.display_name || profile.username; + /** 阻止原生导航，捕获FormData后提交；成功先通知宿主再onClose，失败显示错误并恢复按钮。 + * HTML输入限制是交互提示，服务端仍校验真实资料/空间名称。 */ async function submit(event: FormEvent) { event.preventDefault(); if (busy) return; @@ -27,6 +34,7 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp setBusy(true); setError(""); try { + // 设置模式只提交display_name/username，避免将整个profile（含只读信息）作为修改payload。 if (settings) { const input = { display_name: String(data.get("display_name")).trim(), username: String(data.get("username")).trim() }; const updated = demo ? { ...profile, ...input } : await api("profile", { method: "PATCH", body: JSON.stringify(input) }); @@ -41,6 +49,7 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp finally { setBusy(false); } } + // 保存中禁用取消/提交，并拒绝Dialog的关闭状态变化；请求未结束不假装已成功关闭。 return ( { if (!open && !busy) onClose(); }}> diff --git a/src/components/workspace/active-board.tsx b/src/components/workspace/active-board.tsx index 97e987e..fe8cb90 100644 --- a/src/components/workspace/active-board.tsx +++ b/src/components/workspace/active-board.tsx @@ -1,20 +1,28 @@ +/** + * 侧栏与画布页面共享的当前board元数据Context。只保存ID、工作区、路由引用与标题， + * 不保存元素、加载任务或ProjectEngine；目录改名可更新标题而无需重建业务画布。 + */ "use client"; import { createContext, useContext, useMemo, useState, type Dispatch, type ReactNode, type SetStateAction } from "react"; import type { Board } from "@/lib/workspace"; +/** null代表当前没有已解析画布，workspace_ref保留路径slug/引用与真实workspace_id的对应关系。 */ type ActiveBoard = (Pick & { workspace_ref?: string }) | null; +/** 暴露React状态setter，调用方可条件更新以免迟到改名覆盖另一个活动board。 */ const ActiveBoardContext = createContext<{ board: ActiveBoard; setBoard: Dispatch>; } | null>(null); +/** 在工作台布局内保持元数据，useMemo稳定Context对象，避免只因父渲染就通知全部使用方。 */ export function ActiveBoardProvider({ children }: { children: ReactNode }) { const [board, setBoard] = useState(null); const value = useMemo(() => ({ board, setBoard }), [board]); return {children}; } +/** 缺少Provider时拒绝读取；不从浏览器路径凭空构造一条已认证board记录。 */ export function useActiveBoard() { const context = useContext(ActiveBoardContext); if (!context) throw new Error("useActiveBoard requires ActiveBoardProvider"); diff --git a/src/components/workspace/board-directory.tsx b/src/components/workspace/board-directory.tsx index 656aab9..0c896d1 100644 --- a/src/components/workspace/board-directory.tsx +++ b/src/components/workspace/board-directory.tsx @@ -1,3 +1,7 @@ +/** + * 侧栏画布树显示组件，使用业务目录库派生结构/搜索路径，只保存哪些目录项被用户折叠。 + * 不重写board父子归属；活动路径和搜索可临时展开祖先，路由Link负责进入真实画布页面。 + */ "use client"; import { useEffect, useMemo, useState } from "react"; import Link from "next/link"; @@ -6,13 +10,16 @@ import { activeBoardAncestors, boardDirectory, filterBoardDirectory, type BoardB import { boardHref, matchesRef, type Board } from "@/lib/workspace"; import styles from "./workspace.module.css"; +/** branches只随boards/query重算，closed是当前挂载视图局部状态，宿主切工作区可用key重建。 */ export function BoardDirectory({ boards, workspace, active, query, demo }: { boards: Board[]; workspace: string; active?: string; query: string; demo: boolean }) { const [closed, setClosed] = useState(new Set()); const branches = useMemo(() => filterBoardDirectory(boardDirectory(boards), query), [boards, query]); + /** 活动画布或目录刷新时展开其祖先路径，防当前页藏在折叠树下。 */ useEffect(() => { const path = activeBoardAncestors(boards, active); setClosed((previous) => { const next = new Set(previous); for (const id of path) next.delete(id); return next; }); }, [active, boards]); + /** 递归渲染树，视觉缩进最多8层但不裁掉更深子项；搜索时强制展开匹配路径而不清空用户closed记录。 */ function render(items: BoardBranch[], depth = 0) { return
    {items.map(({ board, children }) => { const expanded = !!query.trim() || !closed.has(board.id); @@ -22,5 +29,6 @@ export function BoardDirectory({ boards, workspace, active, query, demo }: { boa {expanded && children.length > 0 && render(children, depth + 1)}; })}
; } + // 有结果显示树；仅搜索无命中给提示，原始目录空时不伪造一条默认页面。 return branches.length ? render(branches) : query ?

没有找到相关页面

: null; } diff --git a/src/components/workspace/canvas-runtime-host.tsx b/src/components/workspace/canvas-runtime-host.tsx index 9de9f4b..46e233e 100644 --- a/src/components/workspace/canvas-runtime-host.tsx +++ b/src/components/workspace/canvas-runtime-host.tsx @@ -1,3 +1,8 @@ +/** + * 应用级Canvas运行时装配点。一次安装模型registry与React renderer目录，按账户/工作区创建runtime， + * 按项目root安装Foundry服务适配。组件只装配依赖，业务根、history、ledger和持久化仍由下层实例管理。 + * 真实宿主卸载才关闭项目；单个画布页面切换只借还视图，不在这里每次重建engine。 + */ "use client"; import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from "react"; @@ -10,20 +15,29 @@ import { createRuntimeHost, createWorkspaceRuntime, type RuntimeHost } from "@/l import { createBrowserDigests, createBrowserImageDecoder, createBrowserStorage } from "@/lib/canvas-runtime/browser"; import { createFoundryAssets, createFoundryPersistence, createFoundryTransport, createFoundryRuns,createFoundryModelLoader } from "@/lib/canvas-service/index"; +/** 应用共享RuntimeHost引用，未装配时为null；renderer Context另有内置显示目录默认值。 */ const Context = createContext(null); +/** 模型定义与显示实现一起在宿主初始化捕获，子页面用此目录保持一致解释。 */ const Renderers=createContext(defaultCanvasRenderers); +/** 读取宿主安装的React renderer集合，不为每个节点重新构造类型表。 */ export function useCanvasRenderers(){return useContext(Renderers);} +/** extensions仅在useState惰性初始化时捕获；后续prop换引用不会热替换已打开项目的schema/renderer。 */ export function CanvasRuntimeHost({ children,extensions=[] }: { children: ReactNode;extensions?:readonly CanvasRuntimeExtension[] }) { const [{host,renderers}] = useState(() => { + // 先组合内置与扩展模型，再按精确版本/结构验证renderer，冲突在打开项目之前失败。 const registry = createRegistry([...builtinComponents(),...extensions.flatMap(extension=>extension.components??[])]),renderers=createReactRenderers([...defaultCanvasRenderers.definitions,...extensions.flatMap(extension=>extension.renderers??[])],registry); const host=createRuntimeHost({ registry, + /** 每身份作用域绑定transport，current护栏由host提供，流读取也要防换账户后的迟到结果。 */ modelLoader(accountId,workspaceId,_authEpoch,current){return createFoundryModelLoader({workspaceId,registry,transport:createFoundryTransport({accountId,isCurrentIdentity:current})});}, + /** 工作区持有浏览器存储、摘要/解码池；root项目共享其身份范围，各自再装配业务端口。 */ workspace(accountId, workspaceId, authEpoch, isCurrentIdentity) { return createWorkspaceRuntime({ accountId, workspaceId, authEpoch, isCurrentIdentity, registry, storage: createBrowserStorage(),digests:createBrowserDigests(),images:createBrowserImageDecoder(), + /** 一项目一组协议适配器；summary策略只压缩已协调回执，不改变网络请求或原始操作身份。 */ adapters(rootId, current) { const transport = createFoundryTransport({ accountId, isCurrentIdentity: current }); return { runs: createFoundryRuns({ workspaceId, rootId, registry, transport }), persistence: createFoundryPersistence({ workspaceId, rootId, registry, transport, resolvedReceiptPolicy:'summary' }), assets: createFoundryAssets({ workspaceId, transport, project: process.env.NEXT_PUBLIC_FOUNDRY_PROJECT || "endoleap", origin: process.env.NEXT_PUBLIC_FOUNDRY_API_ORIGIN }) }; }, + // 同工作区错误用稳定通知id更新，不创建另一份任务状态；错误恢复仍须runtime明确操作。 onError: error => notify({ id: `canvas-runtime:${accountId}:${workspaceId}`, title: "画布同步需要处理", description: errorText(error), level: "error" }), }); }, @@ -31,7 +45,10 @@ export function CanvasRuntimeHost({ children,extensions=[] }: { children: ReactN }); return {host,renderers}; }); + // effect重放的代次令牌只保护宿主清理，不是账户authEpoch，也不进入持久模型。 const lifetime = useRef(0); + /** cleanup延到微任务检查代次：Strict Mode同步重设effect会递增代次，旧cleanup不关闭新挂载宿主。 + * 真正卸载才发起host.close，保存失败由宿主错误回调/日志报告，不在此丢弃根或强行释放leader。 */ useEffect(() => { const generation = ++lifetime.current; // Strict Mode replays effects synchronously; only a real detach retires the host. @@ -39,6 +56,7 @@ export function CanvasRuntimeHost({ children,extensions=[] }: { children: ReactN }, [host]); return {children}; } +/** 需要runtime的页面必须在根Provider内，缺失装配明确抛错而不偷建一个临时host。 */ export function useCanvasRuntimeHost() { const host = useContext(Context); if (!host) throw new Error("CanvasRuntimeHost is missing"); diff --git a/src/components/workspace/editable-title.tsx b/src/components/workspace/editable-title.tsx index 973e196..b9e088d 100644 --- a/src/components/workspace/editable-title.tsx +++ b/src/components/workspace/editable-title.tsx @@ -1,8 +1,13 @@ +/** + * 工作台标题的局部交互状态机：idle→selected→editing→saving，支持二次点击/F2编辑、Enter/失焦保存、Escape取消。 + * 只管理草稿、焦点和提示，真正改名由异步onSave负责；组件本身不修改目录或画布文档。 + */ "use client"; import { useEffect, useRef, useState } from "react"; import styles from "./editable-title.module.css"; +/** editable控制能否进入编辑；title是宿主已采用值，draft只在一次编辑会话内使用，保存失败回editing重试。 */ export function EditableTitle({ title, editable, onSave, className = "" }: { title: string; editable: boolean; @@ -15,11 +20,14 @@ export function EditableTitle({ title, editable, onSave, className = "" }: { const shell = useRef(null); const input = useRef(null); const button = useRef(null); + // ref防Enter和随后的blur重复调用；cancelled防Escape/已完成后的blur重新提交。 const pending = useRef(false); const cancelled = useRef(false); + /** selected阶段才监听外侧pointerdown；离开此模式即退订，编辑/保存不由这条外侧点击逻辑擅自退出。 */ useEffect(() => { if (mode !== "selected") return; + /** 只在实际DOM目标落在shell外时取消选择，标题内部点击保留进入编辑的机会。 */ const deselect = (event: PointerEvent) => { if (event.target instanceof Node && !shell.current?.contains(event.target)) setMode("idle"); }; @@ -27,10 +35,12 @@ export function EditableTitle({ title, editable, onSave, className = "" }: { return () => document.removeEventListener("pointerdown", deselect); }, [mode]); + /** 进入editing后挂载的input才可聚焦/全选，不在渲染阶段直接访问未就绪DOM。 */ useEffect(() => { if (mode === "editing") { input.current?.focus(); input.current?.select(); } }, [mode]); + /** 每次从宿主最新title初始化草稿并清旧错误，不能沿用上次取消的输入。 */ function edit() { if (!editable) return; cancelled.current = false; @@ -38,12 +48,15 @@ export function EditableTitle({ title, editable, onSave, className = "" }: { setError(""); setMode("editing"); } + /** 标记取消以抑制blur保存，回selected并下一帧把焦点还给标题按钮。 */ function cancel() { cancelled.current = true; setError(""); setMode("selected"); requestAnimationFrame(() => button.current?.focus()); } + /** 同步ref挡重复提交，trim后校验非空及UTF-8≤300字节；同名不发请求。 + * 成功回idle，失败留草稿/错误重编辑，finally释放pending允许下一次明确尝试。 */ async function save() { if (pending.current || cancelled.current) return; const name = draft.trim(); @@ -65,6 +78,7 @@ export function EditableTitle({ title, editable, onSave, className = "" }: { setMode("editing"); } finally { pending.current = false; } } + // saving保留input但只读；输入法组合不把Enter当提交，键盘事件停止冒泡避免触发画布快捷键。 return (
{mode === "editing" || mode === "saving" ? ( diff --git a/src/components/workspace/graph-page.tsx b/src/components/workspace/graph-page.tsx index 2c97742..9fd23d2 100644 --- a/src/components/workspace/graph-page.tsx +++ b/src/components/workspace/graph-page.tsx @@ -1,3 +1,7 @@ +/** + * 画布路由的客户端生命周期桥。把路径引用解析成board/profile，再选择新版engine、渐进预览或旧snapshot编辑器。 + * 页面只持显示与导航状态，项目由RuntimeHost/WorkspaceRuntime拥有；卸载中断本页订阅，但已开始的项目加载可转后台完成。 + */ "use client"; import { useEffect, useRef, useState } from "react"; @@ -16,11 +20,16 @@ import type { CanvasSnapshot } from "@/lib/canvas-sync"; import styles from "./workspace.module.css"; import { useActiveBoard } from "./active-board"; import dynamic from "next/dynamic"; +/** 旧编辑器只在浏览器加载，避免服务端执行依赖DOM的画布实现。 */ const GraphCanvas = dynamic(() => import("@/components/canvas/graph-canvas"), { ssr: false, loading: () =>

正在准备画布…

}); +/** 新版编辑器同样独立客户端bundle，模型选择由loadCanvasEntry结果决定，而非界面手动猜格式。 */ const HeadlessGraphCanvas = dynamic(() => import("@/components/canvas/headless-graph-canvas"), { ssr: false, loading: () =>

正在准备画布…

}); +/** 只读渐进预览先出现，已知内容足够后可升级为partial engine，保持原视口。 */ const LoadingGraphCanvas=dynamic(()=>import("@/components/canvas/loading-graph-canvas"),{ssr:false}); +/** route将结果绑定到这次路径；engine/snapshot/migration分别来自实际选择的协议路径。 */ type Loaded = { board: Board; snapshot?: CanvasSnapshot; route: string; engine?: ProjectEngine; migration?:LegacyMigrationContext }; +/** 当前页面只借用host与renderer，retry触发重新读取；不在页面state复制业务文档或history。 */ export default function GraphPage({ workspaceId, boardId }: { workspaceId: string; boardId: string }) { const renderers=useCanvasRenderers(); const demo = useSearchParams().get("demo") === "1"; @@ -30,12 +39,15 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin const { board: activeBoard, setBoard: setActiveBoard } = useActiveBoard(); const [loaded, setLoaded] = useState(null); const [preview,setPreview]=useState<{board:Board;value:LiveModelPreview;route:string}|null>(null); + // 预览视口暂存于ref，切成可编辑视图时交作initialViewport；新路由重置，不当文档编辑保存。 const previewViewport=useRef(undefined); const [error, setError] = useState(""); const [retry, setRetry] = useState(0); const navigationGeneration=useRef(0); + /** 每条路由/重试新建读取生命周期，清旧显示；active、AbortController和host身份护栏共同隔离迟到结果。 */ useEffect(() => { setLoaded(null);setPreview(null);previewViewport.current=undefined; setError(""); + // 演示目录走旧本地画布，不发canonical读取、不绑定真实账户项目。 if (demo) { const item = readDemoBoards(workspaceId).find((board) => matchesRef(board, boardId)); if (item) setLoaded({ board: item, route }); @@ -44,46 +56,62 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin } let active = true; const controller = new AbortController(); + // 保存开始时身份，并在profile解析后取得currentIdentity闭包，后续await返回均据此判断是否还能采用结果。 const startingIdentity=runtimeHost.identity();let currentIdentity:(()=>boolean)|undefined; + // latest合并待采用的预览，pumping串行openPartial/persist，防快流把多个partial打开交错到同一项目。 let latest:{value:LiveModelPreview;board:Board;accountId:string}|undefined,pumping:Promise|undefined,partialEngine:ProjectEngine|undefined,partialRuntime:ReturnType|undefined; + /** 后台任务失败仅在页面仍活跃时显示，离开页面不再更新本页error。 */ const reportBackground=(error:unknown)=>{if(active)setError(errorText(error));}; + /** 已建立partial engine且身份仍有效时，交工作区继续完整读取；视图离开不等于关闭可恢复项目。 */ const completeInBackground=()=>{if(partialEngine?.loading.getState()&¤tIdentity?.())void partialRuntime?.resumeLoading(partialEngine.getSnapshot().document.projectId).catch(reportBackground);}; + /** 串行采用最新预览，先openPartial再发布UI并保存；期间新预览覆盖latest等待槽而非并行改根。 */ function pump(){ if(pumping)return pumping; const task=(async()=>{while(latest){const next=latest;latest=undefined;if(!currentIdentity?.())return;const runtime=runtimeHost.workspace(next.accountId,next.board.workspace_id);partialRuntime=runtime;const engine=await runtime.openPartial(next.value.document,next.value.versions,next.value.loading);partialEngine=engine;if(active&¤tIdentity?.()){setLoaded(previous=>previous?.route===route&&previous.engine===engine?previous:{board:next.board,engine,route});setPreview(null);}else{completeInBackground();return;}await engine.persist();}})(); pumping=task.finally(()=>{pumping=undefined;if(latest&&active)void pump().catch(reportBackground);});return pumping; } + // 导航代次递增传入共享loader，查询身份与取消订阅由host/loader维护；入口优先canonical防旧writer误开。 loadCanvasEntry({ request: api, workspaceRef: workspaceId, boardRef: boardId, registry: runtimeHost.registry, signal: controller.signal,navigationGeneration:++navigationGeneration.current, + /** 只有本board已在前缀中才显示；有元素后推动partial engine，尚未建立engine时用只读预览。 */ onPreview:(value,board,profile)=>{if(active&¤tIdentity?.()&&value.document.canvases.has(board.id)){if(!partialEngine)setPreview({board,value,route});if(value.document.elements.size){latest={value,board,accountId:profile.id};void pump().catch(reportBackground);}}}, + /** profile解析后绑定账户并读取模型；若开始后的authEpoch已变且当前账户不同于响应账户，拒绝旧导航认领。 */ readModel:input=>{const identity=runtimeHost.identity();if(identity.authEpoch!==startingIdentity.authEpoch&&identity.accountId!==input.accountId)throw new Error('identity_changed');currentIdentity=runtimeHost.bindAccount(input.accountId);return runtimeHost.loadModel(input.accountId,input.workspaceId,input.canvasId,{signal:input.signal,navigationGeneration:input.navigationGeneration,onPreview:input.onPreview});}, }).then(async result => { if (!active||currentIdentity&&!currentIdentity()) return; + // 迁移完成回调只递增retry重开入口，不在旧组件内手工切换文档格式。 if (result.mode === 'legacy') { const migration:LegacyMigrationContext={accountId:result.profile.id,rootId:result.migration?.rootId,registry:runtimeHost.registry,isCurrentIdentity:()=>!!currentIdentity?.(),onApplied:()=>{if(active&¤tIdentity?.())setRetry(value=>value+1);}}; setLoaded({board:result.board,snapshot:result.snapshot,route,migration});setPreview(null);return; } + // 服务已返回新模型但本地仍有同根pending时，查询并收尾原迁移记录，不生成新迁移请求。 const pending=readCanvasMigration(localStorage,{accountId:result.profile.id,workspaceId:result.board.workspace_id}); if(pending?.phase==='pending'&&pending.rootId===result.model.document.projectId){ try{await createBrowserCanvasMigration({scope:{accountId:result.profile.id,workspaceId:result.board.workspace_id},registry:runtimeHost.registry,isCurrentIdentity:()=>active&&!!currentIdentity?.(),signal:controller.signal}).resume();} catch(error){reportBackground(error);} } + // 完整模型到来先等partial采用链结束，再open同一项目，避免尾部覆盖尚在发布的前缀根。 while(pumping)await pumping; if(!active||!currentIdentity?.())return; const engine = await runtimeHost.workspace(result.profile.id, result.board.workspace_id).open(result.model.document, result.model.versions,{sourceToken:result.model.sourceToken}); if (active&&(!currentIdentity||currentIdentity())){setLoaded({ board: result.board, engine, route });setPreview(null);} }) .catch((error) => { if (active) { setError(errorText(error)); if (error.message === "invalid_session") router.replace("/login"); } }); + // 清掉未采用预览并中断本页读取；已拥有的partial项目交后台，绝不在这里直接engine.close。 return () => { active = false;latest=undefined; controller.abort();completeInBackground(); }; }, [workspaceId, boardId, route, demo, retry, router, runtimeHost]); + // 即使effect清理/新读取尚未完成，只显示route匹配的结果，不短暂闪出上个board。 const current = loaded?.route === route ? loaded : null; const currentPreview=preview?.route===route?preview:null; const board = current?.board??currentPreview?.board; + /** 发布当前board元数据供侧栏标题使用，卸载/换board归还该Context显示状态，不删除服务端board。 */ useEffect(() => { if (board) setActiveBoard({ id: board.id, slug: board.slug, workspace_id: board.workspace_id, workspace_ref: workspaceId, title: board.title }); return () => setActiveBoard(null); }, [board, workspaceId, setActiveBoard]); + // 本board在侧栏改名后优先读共享新标题；其它board的活动状态不能覆盖当前名称。 const displayBoard = board && activeBoard?.id === board.id && activeBoard.workspace_id === board.workspace_id ? { ...board, title: activeBoard.title } : board; + // 显示优先级：engine→只读预览→旧snapshot→读取占位；重试错误提示与已显示前缀可并存。 return
{displayBoard && current?.engine ? : displayBoard&¤tPreview ? {previewViewport.current=viewport;}} /> : displayBoard ? :
} {error ?
{error}
: !board &&

正在打开图谱…

} diff --git a/src/components/workspace/user-avatar.tsx b/src/components/workspace/user-avatar.tsx index a99db18..361542f 100644 --- a/src/components/workspace/user-avatar.tsx +++ b/src/components/workspace/user-avatar.tsx @@ -1,8 +1,13 @@ +/** + * 头像的轻量显示降级：指定URL加载失败时用名字首段的大写表示，新的URL可重新尝试。 + * 失败标记仅属当前组件，不写用户资料，也不把一次图片失败当成账户失效。 + */ "use client"; import { useState } from "react"; import styles from "./workspace.module.css"; +/** 同一失败URL不反复重载；large仅控制尺寸，图片不发送Referrer，alt保留用户身份文本。 */ export function UserAvatar({ name, url, large = false }: { name: string; url?: string | null;