docs(canvas): explain legacy persistence and upload cleanup

src/components/canvas/use-canvas-persistence.ts

@@ -21,10 +21,12 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
     if (alive.current) { setSync(next); backup(); }
   }) : null);
   /** 保存规范化document、writer当前版本及内容指纹dirty；回调路径吞掉存储异常，定时effect路径会展示错误。 */
+  // writer 通知捕获创建时的 backup/key；latest 与 pausedRef 保持当前值，key/workspace/board 改变须重建 Hook 所在视图。
   function backup() {
     if (pausedRef.current) return;
     try {
       const current = latest.current;
+      // dirty 使用包含 viewport 的指纹，而 writer.needsSave 忽略 viewport；两者用途不同，不可互换解释。
       localStorage.setItem(key + ":recovery", JSON.stringify({ document: decodeCanvas(JSON.stringify(current)), baseVersion: writer?.version || 1, dirty: writer ? canvasFingerprint(current) !== writer.saved : false }));
     } catch { /* Storage failure is surfaced by the effect below. */ }
   }
@@ -35,6 +37,7 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
       try { localStorage.setItem(key + ":recovery", JSON.stringify({ document: decodeCanvas(JSON.stringify(latest.current)), baseVersion: writer?.version || 1, dirty: writer ? canvasFingerprint(latest.current) !== writer.saved : false })); }
       catch { setSync({ status: "error", version: writer?.version || 1, error: "local_backup_failed" }); }
     }, 250);
+    // 此处只入队，不 await/捕获 running 的拒绝；CanvasSync 的通知与回调需遵守它自身的异常约定。
     const remote = writer ? setTimeout(() => void writer.enqueue(latest.current), 800) : null;
     return () => { clearTimeout(local); if (remote) clearTimeout(remote); };
   }, [document, writer, key, paused]);
@@ -48,6 +51,7 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
     // Writer and key are stable for this board's mounted editor.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [writer, key]);
+  // 同步 localStorage 写入只保证调用返回时 API 未抛错；没有回读、版本日志或刷盘确认。
   // retry先补本地备份再委托writer重试；没有远端writer时返回undefined，不伪造同步成功。
   return { ...sync, retry: () => { backup(); return writer?.retry(); } };
 }