Files
Endoleap/docs/README.md

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 就默认在本机启动。