Files
Endoleap/docs/06-development.md

53 lines
4.3 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.
# 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 需要与后续本地状态协调。
- 刷新解释本地恢复材料,不盲目覆盖为服务端最新模型;未解决请求沿原身份接续。
能讲清这段过程,就已具备定位大部分编辑链路问题的基础。接下来按实际开发目标深入资源、导入或渐进加载,而无需先通读整个仓库。