3.0 KiB
从一次画布操作理解 Endoleap
这套教程带你回答一个完整问题:用户打开图谱、修改节点、拖动节点,再刷新页面时,Endoleap 如何让页面、内存文档、本地恢复记录和服务端保持一致?
面向能阅读 TypeScript 和 React、但还不熟悉本项目的开发者。无需先阅读历史设计文档。章节中的源码链接用于定位讲解对象;先理解过程,再按任务跟踪函数,无需逐文件通读。
学习路线与完成标准
| 顺序 | 章节 | 读完应能解释 |
|---|---|---|
| 1 | 建立项目模型 | 页面、文档、engine、视图分别保存什么 |
| 2 | 打开一张画布 | URL 如何变成可编辑画布,以及为何有新旧入口 |
| 3 | 完成一次编辑 | 命令如何原子更新文档、历史与待同步操作 |
| 4 | 拖动与画面更新 | 手势预览、正式提交、投影与 React Flow 的关系 |
| 5 | 保存、同步与恢复 | 本地成功与服务器确认的区别,以及失败如何收尾 |
| 6 | 开发与排查实践 | 新功能放在哪层,应补哪类验证,故障从哪里查 |
建议分三轮:第一轮读 1–3 章建立正常编辑链路;第二轮读 4–5 章掌握交互与可靠性;第三轮完成第 6 章的设计练习。每章末尾都有自检和答案,达到完成标准再进入下一章。
贯穿案例使用一个已有节点:标题为“想法”,用户将它改为“行动”,再拖动位置。案例中的短代码是接口示意,假定你已取得当前 engine 和有效 target;它不是直接粘贴就能独立运行的脚本。独立宿主的完整装配例子在 consumer.mjs。
阅读基线与边界
本教程依据主线提交 960a3ff 的源码编写。讲解重点是 canonical/headless 链路;旧 snapshot 编辑器仍为未升级项目及演示等路径提供兼容。教程会指出分流位置,不假定所有画布已迁移。
仓库包含 Next.js 前端、浏览器运行时和 Foundry 客户端适配器;Foundry 后端不在本仓库。这里可以解释请求如何生成和处理回执,不能由前端源码推断线上部署状态、权限配置或后端数据库实现。
research-docs/ 保留原有本地研究、规格和历史验收资料,并继续被 Git 忽略。它们是本教程的写作来源,读者不需要拥有这些文件。本文不将历史验收数字当作当前分支已重新通过的检查结果。
如何使用源码和测试
每章的“跟踪任务”只要求查看少数符号,并写出你自己的时序。测试的价值是展示输入、边界和可观察结果,不必先运行整个项目。
本教程不要求启动开发服务器或构建。项目约定将编译、构建、打包及隐式触发这些动作的验证交给已确认的远程 runner;需要实际执行时先确认 runner。不要因 README 列出了 npm run dev 就默认在本机启动。