Files
Endoleap/docs/01-system.md

51 lines
4.0 KiB
Markdown
Raw Permalink 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.
# 1. 建立项目模型
[教程目录](README.md) · 下一章:[打开画布](02-open.md)
## 先把产品拆成两条链
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](../src/lib/canvas-core/types.ts),找到 `Document`、`ElementRecord` 和 `Target`,为案例节点画出字段归属。然后查看 [canvas-runtime-host.tsx](../src/components/workspace/canvas-runtime-host.tsx) 的 `CanvasRuntimeHost`,标出 Registry、浏览器端口和 Foundry adapters 在哪里注入。
只要能指出“标题在元素 data 中,选择在 ViewSession 中,服务端确认版本在 runtime 中”,本章就已达标。
## 自检
**关闭一个画布页面,是否应该删除文档并停止全部上传?**
不应该。页面借用 engine,卸载时归还视图;项目和持久任务由工作区运行时管理。真正关闭项目还需要可靠保存等收尾,浏览器卸载回调也不保证一定完成落盘。