Files
Endoleap/docs/02-open.md
T

52 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 2. 打开一张画布
[上一章](01-system.md) · [目录](README.md) · [下一章](03-edit.md)
## 从地址开始
当用户进入 `/dashboard/{workspace}/{board}`,App Router 的 [page.tsx](../src/app/dashboard/[workspace]/[board]/page.tsx) 等待路径参数,再把它们交给 `GraphPage`。这一层没有直接读取模型。
根 [layout.tsx](../src/app/layout.tsx) 已安装 `CanvasRuntimeHost`;dashboard 布局另提供侧栏和活动 board 信息。这意味着画布页面可以复用应用宿主,而不是每次进入路由都自行创建存储和同步器。
## 从路径引用找到真实身份
[GraphPage](../src/components/workspace/graph-page.tsx) 调用 [loadCanvasEntry](../src/lib/canvas-entry.ts)。入口并行请求 board 元数据与 profile,确认材料类型是 board、路径引用匹配、有 workspace ID 和账户 ID,然后才读取模型。
路径里的字符串可能是引用或 slug;持久化作用域需要已解析的真实身份。`workspaceId`、`accountId` 与项目根 ID 在后续参与端口装配、存储隔离与请求校验。
## 为什么先查 canonical
入口优先读取 canonical 模型。模型 `ready` 后采用 headless engine;明确允许旧模式的情形才进入 snapshot 链路。权限失败不能简单当成“新接口不存在”,进而偷偷回退旧读写器。
原因是同一项目一旦采用新模型,旧 snapshot writer 可能无法表达新的数据与操作语义。让它继续写会引入覆盖风险。因此新旧分流是数据完整性边界,不只是选哪个 React 组件。
真实迁移需要显式操作。入口给出的迁移信息说明资格,并不等于可以立即拿这份旧读取结果发迁移写入;执行前还需收拢旧 writer 并刷新源版本。
## 模型如何成为 engine
GraphPage 通过 Host 绑定账户,从对应 WorkspaceRuntime 打开项目。WorkspaceRuntime 按 `document.projectId` 复用打开句柄,避免同一项目重复创建 engine、重复竞争本地 leader。
完整读取到来时可能是首次打开,也可能要与已有 engine 协调。`open()` 返回已有 engine,并不保证新传入文档一定覆盖了它:运行时还会检查版本、加载状态和来源 token,保护已存在的本地编辑。
随后 GraphPage 将 engine 交给 `HeadlessGraphCanvas`。旧模式则交给 `GraphCanvas`。这个分叉解释了为何仓库同时存在两组画布组件。
## 大模型为什么能先显示一部分
模型读取可以报告前缀预览。GraphPage 在当前 board 已进入前缀时显示预览,有元素后可建立 partial engine;后续前缀在同一加载上下文里继续被采用,完整读取最终收尾。
前缀不是完整项目。加载状态会限制不安全操作;较新的协议允许在证据和持久屏障满足时执行部分操作,不能概括为“未加载完全部只读”或“显示出来便全部可编辑”。完整结果也必须等前缀采用链结束,不能覆盖其间发生的编辑。
导航取消、路由匹配、账户代次和 source token 分别解决不同问题:停止旧读取、避免旧画布闪现、隔离换号结果、识别同次模型来源。一个 `isLoading` 布尔值无法替代它们。
## 跟踪任务
在 GraphPage 中依次定位 `loadCanvasEntry`、`onPreview`、`openPartial`、`workspace(...).open` 和返回 JSX。写出以下五个状态的显示结果:尚无模型、只读预览、partial engine、完整 engine、legacy snapshot。
再读 [entry.test.mjs](../tests/headless/entry.test.mjs) 的前两个测试,确认已采用项目不读取旧快照,以及权限失败不会变成兼容回退。
## 自检
**用户快速从画布 A 切到 B,A 的慢响应回来后该怎么办?**
它不能把 A 显示到 B 的路由,也不能越过账户身份围栏。页面清理取消本次读取并撤销显示资格;已拥有的 partial 项目可能继续后台补全,不能为了清页面直接关闭共享 engine。