Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| a5c9fc35f7 | |||
| 960a3ff7ce |
+2
-2
@@ -11,5 +11,5 @@ node_modules/
|
|||||||
*.tsbuildinfo
|
*.tsbuildinfo
|
||||||
# macOS Finder 的目录元数据。
|
# macOS Finder 的目录元数据。
|
||||||
.DS_Store
|
.DS_Store
|
||||||
# 仓库根 docs 是本地研究/草案目录,当前约定不跟踪其中内容。
|
# 本地研究与历史草案保留在 research-docs;docs 为纳入版本管理的开发教程。
|
||||||
/docs/
|
/research-docs/
|
||||||
|
|||||||
@@ -1,5 +1,7 @@
|
|||||||
# 啡跃 Endoleap
|
# 啡跃 Endoleap
|
||||||
|
|
||||||
|
开发者入门:[从一次画布操作理解项目](docs/README.md)。教程从页面打开、编辑和渲染讲到同步、恢复及功能扩展,无需先读历史设计草案。
|
||||||
|
|
||||||
本地 Next.js App Router + TypeScript + Tailwind CSS + shadcn/ui 项目。首页采用留白、黑色主按钮、衬线标题与线稿画布预览;账户页保留原有布局。工作台使用合并后的单侧栏。
|
本地 Next.js App Router + TypeScript + Tailwind CSS + shadcn/ui 项目。首页采用留白、黑色主按钮、衬线标题与线稿画布预览;账户页保留原有布局。工作台使用合并后的单侧栏。
|
||||||
|
|
||||||
项目目录:`/Users/zzyang/endoleap`。
|
项目目录:`/Users/zzyang/endoleap`。
|
||||||
@@ -116,7 +118,7 @@ CANVAS_UI_TOOLS=/path/to/isolated-tools node tests/canvas-ui-check.mjs
|
|||||||
|
|
||||||
DOM 工具仅需在临时目录安装 esbuild/jsdom,见测试文件开头;不启动浏览器。生产构建与 `tests/api-smoke.mjs` 使用隔离副本和临时本地服务,避免影响现有开发服务器。实际结果及限制见 VALIDATION.md。
|
DOM 工具仅需在临时目录安装 esbuild/jsdom,见测试文件开头;不启动浏览器。生产构建与 `tests/api-smoke.mjs` 使用隔离副本和临时本地服务,避免影响现有开发服务器。实际结果及限制见 VALIDATION.md。
|
||||||
|
|
||||||
Headless Canvas API 的完整方案保留在本地忽略的 `docs/HEADLESS_CANVAS_API_DRAFT.md`。当前工作分支已接入纯 core/runtime、ledger/queue、IndexedDB 恢复、渐进导入/深复制、canonical Foundry 协议和私有 ESM 包预览;使用方式见 `headless/README.md`,尚未发布 npm registry,也不代表完整产品验收或后端部署完成。
|
Headless Canvas API 的完整方案保留在本地忽略的 `research-docs/HEADLESS_CANVAS_API_DRAFT.md`。当前工作分支已接入纯 core/runtime、ledger/queue、IndexedDB 恢复、渐进导入/深复制、canonical Foundry 协议和私有 ESM 包预览;使用方式见 `headless/README.md`,尚未发布 npm registry,也不代表完整产品验收或后端部署完成。
|
||||||
|
|
||||||
Workspace AssetDepot 支持重新授权后的跨项目采用、持久绑定与共享字节。浏览器数据库 v4 将已确认上传的项目文件转换为共享字节指针,保留原 File MIME 和逻辑读取接口;绑定使用恢复格式13。共享回收要求所有项目的持久引用清单完整且与 Root 同步;关闭项目仍受保护。源文件转换、字节、引用清单和 Root 在同一个事务中保存,未确认上传继续保留原 Blob。
|
Workspace AssetDepot 支持重新授权后的跨项目采用、持久绑定与共享字节。浏览器数据库 v4 将已确认上传的项目文件转换为共享字节指针,保留原 File MIME 和逻辑读取接口;绑定使用恢复格式13。共享回收要求所有项目的持久引用清单完整且与 Root 同步;关闭项目仍受保护。源文件转换、字节、引用清单和 Root 在同一个事务中保存,未确认上传继续保留原 Blob。
|
||||||
|
|
||||||
@@ -124,7 +126,7 @@ Workspace AssetDepot 支持重新授权后的跨项目采用、持久绑定与
|
|||||||
|
|
||||||
## 会话期限
|
## 会话期限
|
||||||
|
|
||||||
会话为可撤销的随机令牌。30 天闲置续期、90 天绝对期限由 Core 控制,代理按剩余期限更新 HttpOnly Cookie;既有过期会话不恢复。详细本地说明为 `docs/SESSION_LIFETIME.md`。
|
会话为可撤销的随机令牌。30 天闲置续期、90 天绝对期限由 Core 控制,代理按剩余期限更新 HttpOnly Cookie;既有过期会话不恢复。详细本地说明为 `research-docs/SESSION_LIFETIME.md`。
|
||||||
|
|
||||||
|
|
||||||
## 图片附件与加载
|
## 图片附件与加载
|
||||||
@@ -211,4 +213,4 @@ Core `subgraphs.member_positions` 能力启用时,最终落点(源画布局
|
|||||||
|
|
||||||
`tests/headless/fixtures/foundry-model-operation-v2.json` 是服务适配器单测的完整请求样例。协议 2 的 `request_id` 标识冻结请求,`expected_versions` 是参与 canvas 的已确认版本,`operations[].id` 是逻辑操作 ID。样例把第一代元素 `a` 的 `data.title` 从 `a` 改为 `renamed`;`beforePresent`/`afterPresent` 区分字段缺失与有值。字段旁注与断言在 `tests/headless/service.test.mjs`,静态样例不代表真实服务已执行。
|
`tests/headless/fixtures/foundry-model-operation-v2.json` 是服务适配器单测的完整请求样例。协议 2 的 `request_id` 标识冻结请求,`expected_versions` 是参与 canvas 的已确认版本,`operations[].id` 是逻辑操作 ID。样例把第一代元素 `a` 的 `data.title` 从 `a` 改为 `renamed`;`beforePresent`/`afterPresent` 区分字段缺失与有值。字段旁注与断言在 `tests/headless/service.test.mjs`,静态样例不代表真实服务已执行。
|
||||||
|
|
||||||
`.gitignore` 排除依赖、Next/headless 产物、环境变量、增量缓存和系统文件;仅放行 `.env.example` 作为模板。根 `/docs/` 当前作为本地研究目录忽略。忽略规则只影响未跟踪文件,不会把已经跟踪的文件自动移出 Git。`.env.example` 的公开项目标识与服务端源站说明写在模板内;实际凭据不应写进示例或公开构建变量。
|
`.gitignore` 排除依赖、Next/headless 产物、环境变量、增量缓存和系统文件;仅放行 `.env.example` 作为模板。根 `/research-docs/` 作为本地研究目录忽略;`docs/` 保存纳入版本管理的开发教程。忽略规则只影响未跟踪文件,不会把已经跟踪的文件自动移出 Git。`.env.example` 的公开项目标识与服务端源站说明写在模板内;实际凭据不应写进示例或公开构建变量。
|
||||||
|
|||||||
+2
-2
@@ -23,7 +23,7 @@
|
|||||||
- 按用户约定未访问项目浏览器,未进行视觉布局、真实拖动手感与真实登录会话的浏览器验收。
|
- 按用户约定未访问项目浏览器,未进行视觉布局、真实拖动手感与真实登录会话的浏览器验收。
|
||||||
- 子图关系备份不能作为普通单图快照导入其他画布;导出包含完整 owner 文档集合,避免仅备份父图或重复保存投影。
|
- 子图关系备份不能作为普通单图快照导入其他画布;导出包含完整 owner 文档集合,避免仅备份父图或重复保存投影。
|
||||||
- 网络未知结果保留请求并暂停编辑;普通版本冲突保留本地草稿,不强推覆盖。
|
- 网络未知结果保留请求并暂停编辑;普通版本冲突保留本地草稿,不强推覆盖。
|
||||||
- Headless 库尚未创建,提取方案已改写在本地忽略的 docs/HEADLESS_CANVAS_API_DRAFT.md;已替代的分区/元素/后端需求文档已清理。会话策略文档仍保留。
|
- Headless 库尚未创建,提取方案已改写在本地忽略的 research-docs/HEADLESS_CANVAS_API_DRAFT.md;已替代的分区/元素/后端需求文档已清理。会话策略文档仍保留。
|
||||||
- 原有 next-env.d.ts、pnpm-lock.yaml 和 pnpm-workspace.yaml 不属于本次交付,保留未提交。
|
- 原有 next-env.d.ts、pnpm-lock.yaml 和 pnpm-workspace.yaml 不属于本次交付,保留未提交。
|
||||||
|
|
||||||
|
|
||||||
@@ -80,7 +80,7 @@
|
|||||||
|
|
||||||
## Headless 方案与应用提示依赖
|
## Headless 方案与应用提示依赖
|
||||||
|
|
||||||
本地忽略的 `docs/HEADLESS_CANVAS_API_DRAFT.md` 已重写为方案:同步 command/working document 与独立 runtime、operation ledger、ACK 基线分离;提供 component/feature 组合、API A/B/C、八个 viewport slot、实例 mode、混合选择、文件恢复、幂等与撤销设计。仅为待选择方案,没有提取或发布 npm 包,也没有实现 IndexedDB/outbox。特别区分普通 CAS 快照 PATCH 与有 Idempotency-Key 的事务,避免把重试后的 412 错判为原请求零写入。
|
本地忽略的 `research-docs/HEADLESS_CANVAS_API_DRAFT.md` 已重写为方案:同步 command/working document 与独立 runtime、operation ledger、ACK 基线分离;提供 component/feature 组合、API A/B/C、八个 viewport slot、实例 mode、混合选择、文件恢复、幂等与撤销设计。仅为待选择方案,没有提取或发布 npm 包,也没有实现 IndexedDB/outbox。特别区分普通 CAS 快照 PATCH 与有 Idempotency-Key 的事务,避免把重试后的 412 错判为原请求零写入。
|
||||||
|
|
||||||
实际安装 Sonner 2.0.8、Radix Tooltip 1.4.1,并同步 `package-lock.json`。根布局挂应用 provider,固定通知 ID 避免重复;图标按钮保留实际 button/ref 与原尺寸。通用错误/归属完成使用应用通知,原保存冲突、失败上传和重试入口保留。
|
实际安装 Sonner 2.0.8、Radix Tooltip 1.4.1,并同步 `package-lock.json`。根布局挂应用 provider,固定通知 ID 避免重复;图标按钮保留实际 button/ref 与原尺寸。通用错误/归属完成使用应用通知,原保存冲突、失败上传和重试入口保留。
|
||||||
|
|
||||||
|
|||||||
@@ -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,卸载时归还视图;项目和持久任务由工作区运行时管理。真正关闭项目还需要可靠保存等收尾,浏览器卸载回调也不保证一定完成落盘。
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
# 2. 打开一张画布
|
||||||
|
|
||||||
|
[上一章](01-system.md) · [目录](README.md) · [下一章](03-edit.md)
|
||||||
|
|
||||||
|
## 从地址开始
|
||||||
|
|
||||||
|
当用户进入 `/dashboard/{workspace}/{board}`,App Router 的 [page.tsx](../src/app/dashboard/[workspace]/[board]/page.tsx) 等待路径参数,再把它们交给 `GraphPage`。这一层没有直接读取模型。
|
||||||
|
|
||||||
|
根 [layout.tsx](../src/app/layout.tsx) 已安装 `CanvasRuntimeHost`;dashboard 布局另提供侧栏和活动 board 信息。这意味着画布页面可以复用应用宿主,而不是每次进入路由都自行创建存储和同步器。
|
||||||
|
|
||||||
|
## 从路径引用找到真实身份
|
||||||
|
|
||||||
|
[GraphPage](../src/components/workspace/graph-page.tsx) 调用 [loadCanvasEntry](../src/lib/canvas-entry.ts)。入口并行请求 board 元数据与 profile,确认材料类型是 board、路径引用匹配、有 workspace ID 和账户 ID,然后才读取模型。
|
||||||
|
|
||||||
|
路径里的字符串可能是引用或 slug;持久化作用域需要已解析的真实身份。`workspaceId`、`accountId` 与项目根 ID 在后续参与端口装配、存储隔离与请求校验。
|
||||||
|
|
||||||
|
## 为什么先查 canonical
|
||||||
|
|
||||||
|
入口优先读取 canonical 模型。模型 `ready` 后采用 headless engine;明确允许旧模式的情形才进入 snapshot 链路。权限失败不能简单当成“新接口不存在”,进而偷偷回退旧读写器。
|
||||||
|
|
||||||
|
原因是同一项目一旦采用新模型,旧 snapshot writer 可能无法表达新的数据与操作语义。让它继续写会引入覆盖风险。因此新旧分流是数据完整性边界,不只是选哪个 React 组件。
|
||||||
|
|
||||||
|
真实迁移需要显式操作。入口给出的迁移信息说明资格,并不等于可以立即拿这份旧读取结果发迁移写入;执行前还需收拢旧 writer 并刷新源版本。
|
||||||
|
|
||||||
|
## 模型如何成为 engine
|
||||||
|
|
||||||
|
GraphPage 通过 Host 绑定账户,从对应 WorkspaceRuntime 打开项目。WorkspaceRuntime 按 `document.projectId` 复用打开句柄,避免同一项目重复创建 engine、重复竞争本地 leader。
|
||||||
|
|
||||||
|
完整读取到来时可能是首次打开,也可能要与已有 engine 协调。`open()` 返回已有 engine,并不保证新传入文档一定覆盖了它:运行时还会检查版本、加载状态和来源 token,保护已存在的本地编辑。
|
||||||
|
|
||||||
|
随后 GraphPage 将 engine 交给 `HeadlessGraphCanvas`。旧模式则交给 `GraphCanvas`。这个分叉解释了为何仓库同时存在两组画布组件。
|
||||||
|
|
||||||
|
## 大模型为什么能先显示一部分
|
||||||
|
|
||||||
|
模型读取可以报告前缀预览。GraphPage 在当前 board 已进入前缀时显示预览,有元素后可建立 partial engine;后续前缀在同一加载上下文里继续被采用,完整读取最终收尾。
|
||||||
|
|
||||||
|
前缀不是完整项目。加载状态会限制不安全操作;较新的协议允许在证据和持久屏障满足时执行部分操作,不能概括为“未加载完全部只读”或“显示出来便全部可编辑”。完整结果也必须等前缀采用链结束,不能覆盖其间发生的编辑。
|
||||||
|
|
||||||
|
导航取消、路由匹配、账户代次和 source token 分别解决不同问题:停止旧读取、避免旧画布闪现、隔离换号结果、识别同次模型来源。一个 `isLoading` 布尔值无法替代它们。
|
||||||
|
|
||||||
|
## 跟踪任务
|
||||||
|
|
||||||
|
在 GraphPage 中依次定位 `loadCanvasEntry`、`onPreview`、`openPartial`、`workspace(...).open` 和返回 JSX。写出以下五个状态的显示结果:尚无模型、只读预览、partial engine、完整 engine、legacy snapshot。
|
||||||
|
|
||||||
|
再读 [entry.test.mjs](../tests/headless/entry.test.mjs) 的前两个测试,确认已采用项目不读取旧快照,以及权限失败不会变成兼容回退。
|
||||||
|
|
||||||
|
## 自检
|
||||||
|
|
||||||
|
**用户快速从画布 A 切到 B,A 的慢响应回来后该怎么办?**
|
||||||
|
|
||||||
|
它不能把 A 显示到 B 的路由,也不能越过账户身份围栏。页面清理取消本次读取并撤销显示资格;已拥有的 partial 项目可能继续后台补全,不能为了清页面直接关闭共享 engine。
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
# 3. 一次编辑如何成立
|
||||||
|
|
||||||
|
[上一章](02-open.md) · [目录](README.md) · [下一章](04-view.md)
|
||||||
|
|
||||||
|
## 把“改标题”翻译成命令
|
||||||
|
|
||||||
|
假设当前节点有有效 target,支持对应编辑能力。标题从“想法”改为“行动”的核心接口形态是:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
engine.editor.dispatch({
|
||||||
|
type: 'element.data',
|
||||||
|
target, // 当前元素的 { id, incarnation }
|
||||||
|
patch: { title: '行动' },
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
这只是已取得 engine 后的命令示意。真实界面还要处理焦点、编辑租约、目标是否仍有效等问题。不要绕过命令直接修改 snapshot 中的 Map 或元素对象;它们是受保护的发布结果。
|
||||||
|
|
||||||
|
## 从命令到候选文档
|
||||||
|
|
||||||
|
[editor.ts](../src/lib/canvas-core/editor.ts) 的 `dispatch` 是同步 `transaction` 的便捷封装。事务内部先在候选文档上规划命令,得到 changes。规划会解析目标、检查宿主 policy、组件能力和字段规则;提交前还会对候选文档做整体校验。
|
||||||
|
|
||||||
|
Registry 在这里负责解释“这个组件允许什么”。一个元素存在,不等于它支持任意命令。未来版本和未知组件可以保留原始数据,但不能借此调用未安装的行为。
|
||||||
|
|
||||||
|
Change 描述实际发生的变化,OperationIntent 描述需要同步的逻辑意图,HistoryEntry 则组织用户可撤销的工作单元。它们有关联,却不是同一个对象。
|
||||||
|
|
||||||
|
## 为什么两个命令可以一起成功或一起失败
|
||||||
|
|
||||||
|
例如一个 counter 节点同时移动位置并把 count 改为负数。第一条命令可以在候选文档中成立,第二条违反 schema。事务最终拒绝时,候选文档被丢弃,原文档、历史、操作记录和通知均不应留下第一条命令的结果。
|
||||||
|
|
||||||
|
完整例子在 [consumer.mjs](../headless/consumer.mjs):找到标有“非法事务”的部分,再与后面的合法事务比较。合法的移动与计数更新被组织成一个历史单元。
|
||||||
|
|
||||||
|
事务回调必须同步。异步读取和资源准备先在事务外完成,再带着仍需重新验证的目标进入事务。`await` 期间世界可能变化,不能持有一个可在稍后继续写的事务草稿。
|
||||||
|
|
||||||
|
## 发布边界里还有 runtime
|
||||||
|
|
||||||
|
事务成功后进入 `publish`,构造历史与操作等候选状态。engine 创建 Editor 时注入 `reduceRuntime`,将新操作合入 ledger,并整合相关资源任务;`prepareRuntime` 再检查所有权、加载和资源保留等规则。
|
||||||
|
|
||||||
|
这些准备在最终 state 赋值之前完成,因此“文档已改但待同步操作没有入账”不应成为一次成功提交的状态。准备钩子不做网络 I/O;如果它们偷偷产生外部写入,丢弃候选根也无法撤销外部副作用。
|
||||||
|
|
||||||
|
订阅者随后观察已发布状态,更新页面或调度后续工作。监听器发生异常不能把已经提交的文档倒回去。
|
||||||
|
|
||||||
|
## 撤销为什么不是恢复整个旧快照
|
||||||
|
|
||||||
|
撤销根据历史变化与当前状态执行校验,再发布补偿意图。它必须保留期间到来的有效服务端资源确认等运行事实。如果只是把整个状态替换成编辑前的快照,这些事实会丢失。
|
||||||
|
|
||||||
|
同字段冲突时撤销可能拒绝,并保持历史栈不动。删除后撤销恢复元素会产生新的 incarnation,因此此前捕获的 target 继续失效。一次无实际变化的提交可以返回 applied,但不产生新的 operation;applied 不代表必然发生写入。
|
||||||
|
|
||||||
|
## 跟踪任务
|
||||||
|
|
||||||
|
先跟踪 `dispatch → transaction → plan → publish`,再到 [engine.ts](../src/lib/canvas-runtime/engine.ts) 找 `createEditor` 的 `reduceRuntime` 和 `prepareRuntime`。标出候选状态在哪里变成发布状态。
|
||||||
|
|
||||||
|
在 [core.test.mjs](../tests/headless/core.test.mjs) 阅读标题含 `rejected second command`、`same-field conflict`、`async transactions` 的测试。分别写出它们保护的事实。
|
||||||
|
|
||||||
|
## 自检
|
||||||
|
|
||||||
|
**`dispatch()` 返回 applied,是否意味着服务器已保存?**
|
||||||
|
|
||||||
|
不是。它说明本地命令已成功处理;还需区分有无实际变化、本地可靠持久化是否完成,以及操作是否收到并协调了服务器回执。下一章看页面为什么能先响应,第 5 章再看后续可靠性。
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
# 4. 拖动节点与画面更新
|
||||||
|
|
||||||
|
[上一章](03-edit.md) · [目录](README.md) · [下一章](05-sync.md)
|
||||||
|
|
||||||
|
## 文档坐标不是屏幕坐标
|
||||||
|
|
||||||
|
节点 geometry 属于 owner canvas 的局部空间。嵌套 canvas 带来祖先变换,视口又有平移与缩放。一个鼠标位置必须经过相应转换,才能成为正确的文档几何。
|
||||||
|
|
||||||
|
因此问题“拖完为什么跳动”至少可能来自三处:坐标转换不一致、临时预览与提交几何不一致、旧目标回调迟到。直接调整 React Flow 节点数组,可能暂时改变画面,却没有修复业务文档。
|
||||||
|
|
||||||
|
## 手势先预览,结束才提交
|
||||||
|
|
||||||
|
拖动开始时,sessions 为有效 target 建立手势;移动过程更新临时几何,投影读取有效几何来显示位置;结束时才把最终结果提交到 Editor。取消时释放预览,恢复基于已提交文档的显示。
|
||||||
|
|
||||||
|
这样连续 pointermove 无需每次都生成历史和网络写入。一段有效拖动可成为一个历史单元。取消只处理自己的手势,不能把这段时间并行发生的资源 ACK 或其他有效状态也撤销。
|
||||||
|
|
||||||
|
当前约束下,一个项目同时最多一个写几何的手势。视图 detach 或目标失效会取消对应手势;组件里的编辑租约还保护旧事件处理器,避免它在新的交互开始后提交旧目标。
|
||||||
|
|
||||||
|
## 从事实到可画的数据
|
||||||
|
|
||||||
|
[HeadlessGraphCanvas](../src/components/canvas/headless-graph-canvas.tsx) 同时消费 engine 根和 sessions。场景投影结合文档、当前视图、Registry、renderer 目录及查询,得到 React Flow 使用的节点、边和相关呈现数据。
|
||||||
|
|
||||||
|
投影是派生结果。元素的 owner、业务 data 和历史仍以模型为准;选择与临时预览来自会话。投影缓存与索引是为了减少重复工作,不应成为另一份可以独立编辑的业务文档。
|
||||||
|
|
||||||
|
[canvas-renderers.tsx](../src/components/canvas/canvas-renderers.tsx) 把 renderer 描述映射到具体 React 组件。Registry 回答“数据是什么、允许做什么”,renderer 回答“怎样显示”。只添加一个 React 节点组件,不足以完成可编辑的新类型。
|
||||||
|
|
||||||
|
## 更新如何到达 React
|
||||||
|
|
||||||
|
Editor 提交订阅先推进场景索引,再通知显示。代码对用户字段修改、undo/redo 等采用及时通知,避免受控输入落后;批量创建和后台变化允许合并到呈现帧。sessions 也有自己的通知节奏。
|
||||||
|
|
||||||
|
注意两种时间:文档已经提交的时间,与 React 执行下一次呈现的时间。逐帧合并通知不会把真实提交推迟到下一帧,也不能据此认为同帧发生的业务操作被合成一次事务。
|
||||||
|
|
||||||
|
## 跟踪任务
|
||||||
|
|
||||||
|
在主画布组件定位 `sceneCache`、Editor 的 `subscribe`、`createSessionFrameSource`、`sceneCache.project`,再找 `beginTransform`。画出“pointer → sessions → 投影 → React Flow”和“提交 → Editor → 投影更新”两条路径。
|
||||||
|
|
||||||
|
然后阅读 [consumer.mjs](../headless/consumer.mjs) 的手势取消断言:有效几何变了,但取消后文档坐标不变,请求数也不增加。它在没有 DOM 的情况下展示了业务规则。
|
||||||
|
|
||||||
|
## 自检
|
||||||
|
|
||||||
|
**视口缩放是否应改写每个节点的 geometry?**
|
||||||
|
|
||||||
|
不应该。视口是视图状态,模型坐标保持其业务空间含义。需要坐标转换的是输入、投影和命中过程。混淆两者会让嵌套和多视图行为难以保持一致。
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
# 5. 本地保存、网络同步与恢复
|
||||||
|
|
||||||
|
[上一章](04-view.md) · [目录](README.md) · [下一章](06-development.md)
|
||||||
|
|
||||||
|
## 三种“成功”
|
||||||
|
|
||||||
|
用户改完标题,页面立即显示“行动”。此时只知道本地发布成功。之后还需要可靠保存恢复材料,再推动网络请求,最后解释服务器结果。
|
||||||
|
|
||||||
|
| 阶段 | 已知事实 | 尚不能推断 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 本地发布 | 当前内存文档及关联状态已更新 | 浏览器崩溃后可恢复 |
|
||||||
|
| 本地持久化 | 对应恢复材料已被存储端口确认 | 服务端已经采用修改 |
|
||||||
|
| 服务器结果协调完成 | 回执已被解释并纳入本地状态 | 其他尚未完成操作也已同步 |
|
||||||
|
|
||||||
|
## ledger 为什么与文档一起推进
|
||||||
|
|
||||||
|
ledger 记录逻辑操作、依赖和请求事实。scheduler 根据这些事实判断谁能发送,处理冻结请求、占用、重试和状态查询。它不会通过比较 React 组件状态来猜测需要保存什么。
|
||||||
|
|
||||||
|
[engine.ts](../src/lib/canvas-runtime/engine.ts) 将本地提交转换为 ledger 更新,然后把 ledger 读取、状态更新、可靠保存和具体请求执行注入 [scheduler.ts](../src/lib/canvas-runtime/scheduler.ts)。这把“决定发送什么”和“具体怎么访问 Foundry”分开。
|
||||||
|
|
||||||
|
请求冻结后,重试必须保持原请求身份与内容。发送之前要可靠保存相关请求身份和前置状态,否则进程在服务端执行后崩溃,重启时可能无法知道自己已经发过什么。
|
||||||
|
|
||||||
|
## 请求走到哪里
|
||||||
|
|
||||||
|
浏览器服务适配器通过同源 transport 访问 Next 的 [Foundry route handler](../src/app/api/foundry/[...path]/route.ts),由服务端代理请求上游。浏览器持 HttpOnly 会话 Cookie;代理在服务端转换上游认证,并限制路径、请求头、大小和超时。
|
||||||
|
|
||||||
|
[canvas-service/foundry.ts](../src/lib/canvas-service/foundry.ts) 处理 canonical 模型、操作协议与回执语义。代理负责传输边界,不能替代领域 schema 校验。冻结写入保留原字节,避免在中转时重编码而破坏请求身份。
|
||||||
|
|
||||||
|
认证到期续期由后端会话合同和 [session-cookie.ts](../src/lib/session-cookie.ts) 等代理逻辑协作完成。前端不能单靠延长浏览器 Cookie 来复活服务器已失效的会话。
|
||||||
|
|
||||||
|
## 请求发出后断网,为什么不能直接重做
|
||||||
|
|
||||||
|
假设服务器已执行“想法 → 行动”,响应在途中丢失。客户端看到的网络错误不证明操作未执行。若立刻生成新请求,复制、创建等操作可能重复发生。
|
||||||
|
|
||||||
|
因此 runtime 保留原冻结请求与不确定状态,沿原身份查询或重试。`accepted` 也不等于最终应用并协调完成。具体状态需要服务协议解释,不能把 HTTP 成功统一变成“保存完成”。
|
||||||
|
|
||||||
|
## ACK 如何避免盖掉后续编辑
|
||||||
|
|
||||||
|
客户端收到第一次标题修改的确认时,用户可能已继续输入。runtime 维护 acknowledged 基线与当前 working 文档,根据回执推进已确认状态,再协调尚未解决的本地操作。不能把服务端返回的文档直接覆盖到界面上,否则后一次编辑会丢失。
|
||||||
|
|
||||||
|
[reconcile.ts](../src/lib/canvas-runtime/reconcile.ts) 提供相关协调与重放逻辑。若服务端已应用,但本地无法安全协调,engine 保留回执和冲突材料,阻塞相关流程并报告恢复需求;它不会把失败候选中的一半状态当成成功发布。
|
||||||
|
|
||||||
|
## 刷新后如何接续
|
||||||
|
|
||||||
|
浏览器 storage 适配器使用 IndexedDB 等能力保存恢复记录,并配合 leader 所有权控制本地写入。重新打开项目先解释恢复材料,再处理未解决请求。恢复需要的不只是最终 Document,还包括历史、ledger、已确认基线及相关资源和版本证据。
|
||||||
|
|
||||||
|
[storage-port.ts](../src/lib/canvas-runtime/storage-port.ts) 定义端口合同;[storage.ts](../src/lib/canvas-runtime/storage.ts) 实现浏览器侧存储;[recovery.ts](../src/lib/canvas-runtime/recovery.ts) 负责恢复编解码。内存示例能证明合同接线,但不能证明跨进程崩溃持久性。
|
||||||
|
|
||||||
|
## 跟踪任务
|
||||||
|
|
||||||
|
在 engine 中找到 `createScheduler`,标出 `persistThrough`、执行请求与协调结果的连接。到 [engine.test.mjs](../tests/headless/engine.test.mjs)、[durability.test.mjs](../tests/headless/durability.test.mjs)、[crash-windows.test.mjs](../tests/headless/crash-windows.test.mjs) 中,分别找普通编辑、发送持久屏障、崩溃窗口相关断言。
|
||||||
|
|
||||||
|
用自己的话写出“本地提交 → 恢复材料可靠保存 → 请求发送 → 结果解释 → ACK/working 协调”。这是职责时序;具体 I/O 可以批处理或重入调度,不能把这句话当作每次都只发生一次的函数调用栈。
|
||||||
|
|
||||||
|
## 自检
|
||||||
|
|
||||||
|
**为什么刷新后不只重新 GET 服务端模型?**
|
||||||
|
|
||||||
|
因为尚未确认的本地编辑、结果未知的请求和可恢复任务可能只存在本地。直接丢掉恢复记录会丢失用户工作,也可能让已执行的操作再次执行。
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# 6. 用模型指导开发与排查
|
||||||
|
|
||||||
|
[上一章](05-sync.md) · [目录](README.md)
|
||||||
|
|
||||||
|
## 练习:为 counter 增加“加一”按钮
|
||||||
|
|
||||||
|
先在纸上设计,再动源码。目标不是把按钮画出来,而是让它遵守事务、历史、同步和目标生命周期规则。
|
||||||
|
|
||||||
|
1. 模型:counter 的 `count` 是 JSON data,Registry 校验它的合法范围。`consumer.mjs` 已有完整自定义组件示例,可以先理解其定义。
|
||||||
|
2. 行为:按钮在最新状态下读取有效 target 和 count,通过受支持的命令提交 `element.data`。默认用户编辑进入历史与同步流程,不另写一套 fetch 保存。
|
||||||
|
3. 显示:在 renderer 目录中登记与组件 ID、版本和结构匹配的 React renderer;由应用宿主组合模型定义与 renderer 定义。
|
||||||
|
4. 生命周期:点击时重新确认目标,避免使用删除前捕获的 incarnation;组件卸载只清自己的事件和视图租约。
|
||||||
|
5. 验证:检查加一后文档值、undo/redo、非法数据拒绝及旧 target 拒绝;如果改动触及协议,再验证请求与回执。不要只测试按钮文字变了。
|
||||||
|
|
||||||
|
这里不提供一段未经项目接线验证的“可直接运行插件”。练习的产物是一份变更设计和检查方案。扩展入口可从 [CanvasRuntimeHost](../src/components/workspace/canvas-runtime-host.tsx) 的 `extensions` 与 [createReactRenderers](../src/lib/canvas-bindings/react-renderers.ts) 跟踪。
|
||||||
|
|
||||||
|
## 同一症状,从哪层排查
|
||||||
|
|
||||||
|
| 症状 | 第一处证据 | 接下来问什么 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 一直正在打开 | GraphPage 的 error、入口结果 | 引用、身份、新旧分流还是模型加载失败? |
|
||||||
|
| 点击后无变化 | 命令 Result | 被 policy、能力、schema 还是旧 target 拒绝? |
|
||||||
|
| 文档正确但显示错误 | scene projection 与 renderer 输入 | 会话、坐标、缓存失效还是渲染映射错误? |
|
||||||
|
| 页面已改但刷新丢失 | 本地持久化结果、恢复记录 | 修改是否真正可靠落盘,作用域是否正确? |
|
||||||
|
| 操作迟迟未同步 | ledger、scheduler 门禁 | 依赖、身份、加载、持久屏障还是不确定请求阻塞? |
|
||||||
|
| 撤销失败 | History 与冲突结果 | 当前字段是否已变化,目标代次是否仍有效? |
|
||||||
|
| 上传完成但节点不对 | resource 记录与文档引用 | 上传事实、附件采用和节点编辑是否分别协调? |
|
||||||
|
|
||||||
|
先确认事实在哪层首次偏离,再修对应边界。比如命令已明确 rejected,就先解释拒绝码;此时刷新 renderer 通常不能解决问题。
|
||||||
|
|
||||||
|
## 如何选择测试
|
||||||
|
|
||||||
|
core 测试关注规则和原子性;runtime 测试关注操作、存储与恢复;service 测试关注协议;bindings 测试关注投影、订阅与命中;浏览器与页面集成测试才覆盖真实适配器、焦点和事件。
|
||||||
|
|
||||||
|
同一条测试通过有明确边界:内存 storage 不能证明 IndexedDB 崩溃安全;模拟 transport 不能证明线上 Foundry 正确;源码加载通过也不能证明编译包 exports、Worker URL 正确。
|
||||||
|
|
||||||
|
执行前检查 `package.json` 和对应脚本。`build:headless` 会生成产物;`test:headless:package` 包含构建打包;页面、proxy、浏览器集成也需检查是否隐式编译或启动服务。需要构建的步骤使用用户确认的远程 runner。本教程编写只做文档和引用检查,没有重跑这些产品测试。
|
||||||
|
|
||||||
|
## 完成整套教程的检查
|
||||||
|
|
||||||
|
尝试不用看答案,讲解这段场景:用户打开项目,改标题,开始拖动;服务器返回上次编辑的 ACK;用户取消拖动,然后刷新。
|
||||||
|
|
||||||
|
合格的解释至少包含:
|
||||||
|
|
||||||
|
- 入口解析真实身份并选择新旧模型;WorkspaceRuntime 取得或复用 engine。
|
||||||
|
- 标题命令在候选根上验证,文档、历史和待同步事实一起发布。
|
||||||
|
- 拖动是会话预览,取消不会回退已提交标题,也不会抹掉服务器 ACK。
|
||||||
|
- 界面从文档、会话与 renderer 派生显示,不单独拥有业务真相。
|
||||||
|
- 发送前有可靠保存要求;ACK 需要与后续本地状态协调。
|
||||||
|
- 刷新解释本地恢复材料,不盲目覆盖为服务端最新模型;未解决请求沿原身份接续。
|
||||||
|
|
||||||
|
能讲清这段过程,就已具备定位大部分编辑链路问题的基础。接下来按实际开发目标深入资源、导入或渐进加载,而无需先通读整个仓库。
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
# 从一次画布操作理解 Endoleap
|
||||||
|
|
||||||
|
这套教程带你回答一个完整问题:用户打开图谱、修改节点、拖动节点,再刷新页面时,Endoleap 如何让页面、内存文档、本地恢复记录和服务端保持一致?
|
||||||
|
|
||||||
|
面向能阅读 TypeScript 和 React、但还不熟悉本项目的开发者。无需先阅读历史设计文档。章节中的源码链接用于定位讲解对象;先理解过程,再按任务跟踪函数,无需逐文件通读。
|
||||||
|
|
||||||
|
## 学习路线与完成标准
|
||||||
|
|
||||||
|
| 顺序 | 章节 | 读完应能解释 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 1 | [建立项目模型](01-system.md) | 页面、文档、engine、视图分别保存什么 |
|
||||||
|
| 2 | [打开一张画布](02-open.md) | URL 如何变成可编辑画布,以及为何有新旧入口 |
|
||||||
|
| 3 | [完成一次编辑](03-edit.md) | 命令如何原子更新文档、历史与待同步操作 |
|
||||||
|
| 4 | [拖动与画面更新](04-view.md) | 手势预览、正式提交、投影与 React Flow 的关系 |
|
||||||
|
| 5 | [保存、同步与恢复](05-sync.md) | 本地成功与服务器确认的区别,以及失败如何收尾 |
|
||||||
|
| 6 | [开发与排查实践](06-development.md) | 新功能放在哪层,应补哪类验证,故障从哪里查 |
|
||||||
|
|
||||||
|
建议分三轮:第一轮读 1–3 章建立正常编辑链路;第二轮读 4–5 章掌握交互与可靠性;第三轮完成第 6 章的设计练习。每章末尾都有自检和答案,达到完成标准再进入下一章。
|
||||||
|
|
||||||
|
贯穿案例使用一个已有节点:标题为“想法”,用户将它改为“行动”,再拖动位置。案例中的短代码是接口示意,假定你已取得当前 engine 和有效 target;它不是直接粘贴就能独立运行的脚本。独立宿主的完整装配例子在 [consumer.mjs](../headless/consumer.mjs)。
|
||||||
|
|
||||||
|
## 阅读基线与边界
|
||||||
|
|
||||||
|
本教程依据主线提交 `960a3ff` 的源码编写。讲解重点是 canonical/headless 链路;旧 snapshot 编辑器仍为未升级项目及演示等路径提供兼容。教程会指出分流位置,不假定所有画布已迁移。
|
||||||
|
|
||||||
|
仓库包含 Next.js 前端、浏览器运行时和 Foundry 客户端适配器;Foundry 后端不在本仓库。这里可以解释请求如何生成和处理回执,不能由前端源码推断线上部署状态、权限配置或后端数据库实现。
|
||||||
|
|
||||||
|
`research-docs/` 保留原有本地研究、规格和历史验收资料,并继续被 Git 忽略。它们是本教程的写作来源,读者不需要拥有这些文件。本文不将历史验收数字当作当前分支已重新通过的检查结果。
|
||||||
|
|
||||||
|
## 如何使用源码和测试
|
||||||
|
|
||||||
|
每章的“跟踪任务”只要求查看少数符号,并写出你自己的时序。测试的价值是展示输入、边界和可观察结果,不必先运行整个项目。
|
||||||
|
|
||||||
|
本教程不要求启动开发服务器或构建。项目约定将编译、构建、打包及隐式触发这些动作的验证交给已确认的远程 runner;需要实际执行时先确认 runner。不要因 README 列出了 `npm run dev` 就默认在本机启动。
|
||||||
Reference in New Issue
Block a user