edit | blame | history | raw

MD-BUNDLE-04 预览新鲜度

日期：2026-07-02

用户目标

完成统一台账 P-20260701-app-codex-plugin-acceptance-bundle 的 MD-BUNDLE-04：排查并修复 Mindraw App mindraw.app.get_preview_snapshot / project canvas preview 可能返回旧图、错图或错目标内容的问题，针对用户报告的 我是 / 我说 sentinel 做回归证据。

已完成事项

  • 修复 src/lib/mindrawProjectCanvasApi.ts：
  • full-canvas preview 请求带 elementId 时返回 TARGET_PREVIEW_UNSUPPORTED。
  • documentId 与 package 实际 documentId 不一致时返回 DOCUMENT_ID_MISMATCH。
  • package 已打开且 dirty，或 active editor snapshot 与 tab content 不一致时返回 PREVIEW_REQUIRES_SAVED_DOCUMENT。
  • 前端 export PNG 时计算 sourceContentSha256。
  • 修复 src-tauri/src/lib.rs：
  • write_mindraw_preview_snapshot 重读 package 后校验 source hash，不一致返回 PREVIEW_SOURCE_STALE。
  • preview DTO / manifest 写入 previewScope、sourceDocumentId、sourceContentSha256、sourceByteLength、sourceModifiedAt。
  • 补 src/lib/mindrawAppApiTransport.test.ts 回归：
  • 我说 -> 我是 同路径内容变化会重新进入 exporter，且 source hash 变化。
  • dirty/open package 不返回落后磁盘 preview。
  • target elementId 请求不被误当 full-canvas preview 成功。
  • 产出 QA：
  • 02-P/MEXP13-AcceptanceBundle/qa/md-bundle-04-preview-freshness-check-20260702.md
  • 02-P/MEXP13-AcceptanceBundle/qa/md-bundle-04-preview-freshness-check-20260702.json
  • 02-P/MEXP13-AcceptanceBundle/qa/preview-freshness-20260702/26.0702-02-safe-copy.mindraw/
  • 回写 CODEGRAPH.md、INDEX.md、CHANGELOG.md 和 02-P/plan-progress.markdown。

核心事实 / 变更快照

  • 变更对象：Mindraw App project canvas preview API。
  • 事实来源：
  • src/lib/mindrawProjectCanvasApi.ts
  • src-tauri/src/lib.rs
  • src/lib/mindrawAppApiTransport.test.ts
  • QA 报告 02-P/MEXP13-AcceptanceBundle/qa/md-bundle-04-preview-freshness-check-20260702.md
  • 变更前：
  • get_preview_snapshot 是 full-canvas preview，但返回 / manifest 不记录 source document/content hash/mtime。
  • 带 target elementId 的 preview 语义未 fail closed。
  • 打开且 dirty 的 package 可能从落后磁盘生成 preview。
  • 变更后：
  • full-canvas preview DTO / manifest 记录 previewScope、sourceDocumentId、sourceContentSha256、sourceByteLength、sourceModifiedAt。
  • source hash 不一致返回 PREVIEW_SOURCE_STALE。
  • dirty/open package 返回 PREVIEW_REQUIRES_SAVED_DOCUMENT。
  • target elementId 返回 TARGET_PREVIEW_UNSUPPORTED。
  • document mismatch 返回 DOCUMENT_ID_MISMATCH。
  • 用户证据核对：
  • /Users/ar/Documents/技术实验室/MindrawCanvas/26.0702-02.mindraw/drawing.excalidraw 当前磁盘文本为 我是第2个画布，不含 我说。
  • 该包 documentId=mdoc_18be648b9f452660_165e4，与用户 link mdoc_18be6514f9ceff78_165e4 不匹配。
  • 用户 link element id BnZJU5WLUd4tHklxPLaxg 未在只读检查的磁盘包中找到。
  • 范围边界：
  • 当前 get_preview_snapshot 仍只支持 previewScope="full-canvas"。
  • target / frame scoped sidebar preview 需要 PM 后续决定是否拆 targetPreviewSnapshot / elementScopedPreview API。
  • 当前用户安装的 1.2.1 / Build202607021050 DMG 不含本修复；需后续新 DMG 才能用户复验 App 侧修复。

可复用命令 / Runbook

用途：复查 MD-BUNDLE-04 preview freshness / target guard。

前置条件：在 /Users/ar/Projects/ExcalidrawX 执行；无需运行真实 App；不修改用户原始 /Users/ar/Documents/技术实验室/MindrawCanvas。

npm run test:run -- src/lib/mindrawProjectCanvasPreview.test.ts src/lib/mindrawAppApiTransport.test.ts src/lib/mindrawAppReadApi.test.ts
cargo test --manifest-path src-tauri/Cargo.toml preview
cargo test --manifest-path src-tauri/Cargo.toml app_api_transport
npm run build
git diff --check

验证步骤：

  • Vitest 应通过 3 files / 25 tests。
  • Rust preview 应通过 3 tests，其中包含 rejects_png_preview_when_source_hash_is_stale。
  • Rust app_api_transport 应通过 5 tests。
  • npm run build 通过；既有 Vite 字体和大 chunk warning 非阻塞。
  • git diff --check 通过。

未决问题

  • M4C-BUNDLE-05 需要消费 App 新错误 / metadata，不得 READY / blockers=[] 时展示旧图。
  • PM 需决定是否派发新 App DMG，例如 1.2.2 或按当时版本规则处理。
  • 如果产品需要从 mindraw://...documentId...elementId... 直接生成 sidebar target preview，需要另拆 Mindraw API：mindraw.app.get_target_preview_snapshot。

后续建议

  • PM 等 m4c guard 回报后，统一决定 App + plugin 是否都要刷新给用户复验。
  • 新 DMG 生成前复跑本轮 QA 命令，并确认 manifest preview metadata 在真实 App 包中可见。