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