Files
Endoleap/docs/01-system.md

4.0 KiB
Raw Permalink Blame History

1. 建立项目模型

教程目录 · 下一章:打开画布

先把产品拆成两条链

Endoleap 是带账户与工作空间的图谱编辑应用。Next.js App Router 负责页面与同源 API;React 负责界面;React Flow 负责画布呈现与交互接入。用户操作最终改变的是 headless 文档模型。

第一条链是“找到我要打开什么”:路由参数 → 账户与 board 元数据 → canonical 项目模型 → engine → 视图。第二条链是“改变它”:界面动作 → editor 命令 → 原子发布 → 界面订阅更新,同时由 runtime 推动持久化与网络同步。

区分这两条链很重要:页面加载状态属于第一条链;某次修改是否被服务器确认属于第二条链。画布显示出来,不代表此前所有写入都已完成。

一份事实,几种用途

Document 是项目规范化数据,主要有 projectId、canvases、elements、tombstones。元素通过 ownerCanvasId 归属某个 canvas,节点保存 geometry,连线保存端点与路径。组件私有字段放在 data 中。

这里的 board 是路由和工作空间目录中的材料信息;canvas 是文档里的业务结构;ProjectEngine 管理项目的 canonical ID 空间及已加载 canvas。三者有关联,但不能把一次路由切换理解成新建一份独立文档。

对象 保存什么 为什么单独存在
Registry 组件 schema、版本、能力与行为 数据与显示实现可以分离,未知类型也能被保留
Editor 文档提交、历史、查询与命令入口 所有编辑遵守同一校验和发布规则
ProjectEngine Editor 与同步、资源、加载、恢复的协调 编辑事实与运行任务需要一致推进
WorkspaceRuntime 按项目复用 engine,共享工作区资源 切换视图不丢失项目任务
RuntimeHost 按账户/工作区装配与身份隔离 旧账户的异步结果不能冒充新账户结果
ViewSession 选择、焦点、视口、工具和临时手势 两个视图能看同一文档而各有交互状态

运行时包含关系为 Host → WorkspaceRuntime → ProjectEngine → ViewSession。业务树则是 CanvasRecord 的 parent 关系。DOM 嵌套既不是这两种树的替代品,也不能决定元素 owner。

四层代码的职责

canvas-core 解释数据、能力、命令、事务、历史与几何规则;canvas-runtime 增加调度、存储、恢复、资源和异步作业;canvas-service 把运行时端口转换为 Foundry 协议;canvas-bindings 把模型与会话投影成可呈现、可订阅、可命中的数据。应用组件负责装配这些能力,并实现具体界面。

因此“改节点的产品规则”通常从 core 查起;“请求丢失后怎么办”去 runtime;“协议字段怎么编码”去 service;“模型正确但画面错误”去 bindings 和组件。

身份为什么不只是一个 ID

一个元素的目标由 id + incarnation 组成。删除后撤销可以恢复同一个 ID,但恢复实例拥有新的 incarnation。旧输入框或异步回调捕获的 target 不能因此获得修改新实例的权力。账户也有自己的代次保护 authEpoch;它保护账户生命周期,不是元素 incarnation。

跟踪任务

打开 types.ts,找到 Document、ElementRecord 和 Target,为案例节点画出字段归属。然后查看 canvas-runtime-host.tsx 的 CanvasRuntimeHost,标出 Registry、浏览器端口和 Foundry adapters 在哪里注入。

只要能指出“标题在元素 data 中,选择在 ViewSession 中,服务端确认版本在 runtime 中”,本章就已达标。

自检

关闭一个画布页面,是否应该删除文档并停止全部上传?

不应该。页面借用 engine,卸载时归还视图;项目和持久任务由工作区运行时管理。真正关闭项目还需要可靠保存等收尾,浏览器卸载回调也不保证一定完成落盘。