# 2026-06-25 Phase 3.6 原生包与链接恢复

## 用户目标

用户认可新增小阶段 `Phase 3.6：Native Package & Link Recovery`，要求不要停在 Finder 显示为文件夹、全局链接找不到 `documentId` 的半成品状态，而是继续把 `.mindraw` 的 macOS 原生文件体验和链接恢复补上。

## 已完成事项

- 将版本提升到 `0.8.1`，用于承载 Phase 3.6 修复。
- 新增 `src-tauri/Info.plist`，补齐 `.mindraw` 的 macOS document type / UTI 声明：
  - `com.mindraw.document`
  - `LSTypeIsPackage = true`
  - conforms to `com.apple.package` 与 `public.directory`
- 更新 `src-tauri/tauri.conf.json` 的 `.mindraw` file association。
- 在 `src-tauri/src/lib.rs` 中补齐 package 打开链路：
  - `RunEvent::Opened` 与 macOS `kAEOpenDocuments` Apple Event 统一进入打开处理。
  - 归一化 macOS package file URL 的尾随 `/`。
  - 增加 Foundation `NSURL.filePathURL()` 兜底解析。
- 增加 deep link 选包恢复：
  - registry 缺失、陈旧或 `documentId` 不匹配时，前端提示用户选择 `.mindraw` 包。
  - 后端 `resolve_mindraw_link_from_package` 校验所选包 `documentId` 与链接匹配后重新登记并打开。
- 新增 QA 文档 `02-P/qa/mindraw-phase36-native-package-check.md`。
- 更新 `02-P/plan-progress.markdown`、`CODEGRAPH.md`、`INDEX.md`、`03-O/C2.builds/README.md` 和 `CHANGELOG.md`。
- 创建源码冻结 commit：
  - `202fe6ccaacf799ecad74219075df3ffe2be757b`
  - commit message: `Implement Mindraw native package recovery`
- 创建 release tag：
  - `v0.8.1-Build202606252311`
- 生成验收候选 DMG：
  - `/Users/ar/Projects/ExcalidrawX/03-O/C2.builds/releases/Build202606252311/Mindraw_0.8.1_aarch64-Build202606252311.dmg`
  - SHA256: `f62ce9ce89665683a1207230d65f92453a5ddf36f771fe3e4ff60b42d5f571d5`
- 已将 `/Applications/Mindraw.app` 替换为 `0.8.1` 版本并做本机安装版 smoke。

## 验证结论

- `npm run test:run -- src/lib/imageDrop.test.ts src/hooks/useMenuHandler.test.ts src/hooks/useKeyboardShortcuts.test.tsx src/lib/documentFormat.test.ts src/lib/obsidianExcalidraw.test.ts src/lib/mindrawDeepLink.test.ts src/store/useStore.test.ts`：7 个文件 / 87 个测试通过。
- `cargo test --locked --manifest-path src-tauri/Cargo.toml`：37 个测试通过。
- `cargo check --manifest-path src-tauri/Cargo.toml`：通过。
- `npm run build`：通过，保留既有字体、dialog import 和 chunk size warning。
- `npm run tauri -- build --debug --bundles app`：通过。
- `hdiutil verify`：`Build202606252311` DMG 校验通过。
- release app 和挂载后 app 的 `codesign --verify --deep --strict --verbose=2`：通过。
- `mdls` 新建 `.mindraw` 包：返回 `kMDItemContentType = com.mindraw.document`，type tree 包含 `com.apple.package`、`public.directory`、`com.mindraw.document`。
- 正式安装版冷启动打开：`open /tmp/mindraw-phase36-installed-cold.mindraw` 登记对应 fixture `documentId`。
- 正式安装版运行中打开：`open -a /Applications/Mindraw.app /tmp/mindraw-phase36-installed-open-a.mindraw` 登记对应 fixture `documentId`。
- 测试 registry 记录已清理，只保留用户原有 `mdoc_18bc569bd7821178_ea25`。

## 关键决策

- 当前 Phase 3.6 定义为 `.mindraw` native package / link recovery，不再把 m4c companion app 分发就绪占用为 Phase 3.6；companion app 后移为 Phase 3.7 / backlog。
- `0.8.1` 是本轮小修版本，`Build202606252311` 是对应验收候选包。
- release DMG 不是 Developer ID 签名或公证包；本轮只做本机 ad-hoc sign 以满足安装测试和回滚验证。
- 用户补充授权：后续为测试可直接卸载、替换或重装 `/Applications/Mindraw.app`，无需再为这个可恢复的安装态单独确认；该授权不包含用户画布文件、registry 用户数据或源码删除。

## 未决问题

- 普通 macOS Save As 面板直接创建 `.mindraw` 包仍未实现。
- 原生 picker 直接选择 package document 仍未作为完成能力签收。
- Finder 拖放 `.mindraw` 真实 smoke 的稳定自动化仍未补齐。
- Windows / PC 文件关联、协议注册、安装器和 smoke 仍未开始。
- Phase 4 AssetStore 外置资产权威化仍是后续任务。
- 本机 `stable-aarch64-apple-darwin` 未安装 `rustfmt`，`cargo fmt --manifest-path src-tauri/Cargo.toml -- --check` 未能执行。

## 后续建议

- 用户体验验收重点：安装 `Build202606252311`，确认 Finder 里 `.mindraw` 表现为 package document，双击/`open` 可打开；旧链接找不到 registry 时选择原始 `.mindraw` 包恢复。
- 下一轮不应直接跳 Phase 4；如果用户继续打磨文件体验，优先做普通 Save As package 创建、原生 picker package selection、Finder 拖放 smoke 和错误提示文案。