docs: add guided developer tutorial and separate local research

This commit is contained in:
2026-11-16 16:09:54 +08:00
parent 960a3ff7ce
commit a5c9fc35f7
10 changed files with 357 additions and 7 deletions
+50
View File
@@ -0,0 +1,50 @@
# 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,卸载时归还视图;项目和持久任务由工作区运行时管理。真正关闭项目还需要可靠保存等收尾,浏览器卸载回调也不保证一定完成落盘。