# MD-H5-02 Transport

日期：2026-06-26

## 用户目标

从统一台账 `02-P/plan-progress.markdown` 的 `P-20260626-m4c-handshake-coordination` 领取 Mindraw 侧 `MD-H5-02`，实现 H5 解阻用最小外部 App API transport / capability 暴露，让运行中的 Mindraw 可被本机 m4c 安全发现并调用 read / lease / controlled commit 最小闭环。

## 已完成事项

- 新增 Rust 本机 App API transport：`src-tauri/src/app_api_transport.rs`。
- App 启动时绑定 `127.0.0.1` 随机端口，写入 m4c 默认 discovery 文件 `~/Library/Application Support/com.mindraw.desktop/runtime/write-api.json`，并保留 `app-api-capability.json` 兼容副本。
- `/rpc` 支持 JSON-RPC 调用 `get_open_document_state`、`get_live_frame_context`、`acquire_write_lease`、`release_write_lease`、`commit_write_result(createAiResultFrame)` 和 capabilities。
- 通过 bearer token / `X-Mindraw-Api-Token` 做本机调用 guard。
- 新增前端 dispatcher：`src/lib/mindrawAppApiTransport.ts`，复用既有 `MD-H1-02/03/04/05` read / lease / mutation / save path。
- 更新 doctor：默认读取 `runtime/write-api.json`，校验 required methods、token、`arbitraryJsonPatch=false` 和 `/health`。
- 新增 QA 证据：`02-P/qa/mindraw-h5-app-api-transport-check.md`。
- 更新 `CODEGRAPH.md`、`INDEX.md` 和总台账 Progress Log，标记 `MD-H5-02` 完成。

## 关键决策

- transport 只做本机 HTTP JSON-RPC + capability discovery，不重写业务写入链路。
- write path 仍由前端 facade 执行，避免 Rust 直接改场景 JSON。
- 不开放任意 JSON patch，只允许 `createAiResultFrame`。
- capability primary 路径对齐 m4c 已准备的默认路径 `runtime/write-api.json`。

## 验证结论

- `npm run test:run -- src/lib/mindrawAppApiTransport.test.ts src/lib/mindrawAppWriteApi.smoke.test.ts`：PASS，11 个用例。
- `npm run doctor:mindraw:test`：PASS，13 个 Node test。
- `cargo test --manifest-path src-tauri/Cargo.toml app_api_transport`：PASS，3 个 Rust test。
- `npm run build`：PASS，仅既有字体和 chunk size 警告。
- `git diff --check`：PASS，无输出。

QA 结论：`PASS FOR MD-H5-02 TRANSPORT POC`。

## 文件变更

- `src-tauri/src/app_api_transport.rs`
- `src-tauri/src/lib.rs`
- `src/lib/mindrawAppApiTransport.ts`
- `src/lib/mindrawAppApiTransport.test.ts`
- `src/App.tsx`
- `scripts/mindraw-doctor.mjs`
- `scripts/mindraw-doctor.test.mjs`
- `CODEGRAPH.md`
- `INDEX.md`
- `02-P/qa/mindraw-h5-app-api-transport-check.md`
- `02-P/plan-progress.markdown`

## 未决问题

- 尚未启动真实 Tauri App 后由 m4c 进程外 curl 完整联测。
- capability stale 依赖 doctor health 识别。
- token 当前存于本机 capability 文件；后续是否升级为更强 handshake 由 PM 决定。
- 多窗口 / 多进程 lease 互斥仍未验证。
- 真实 Tauri command ACL / event bridge 需 H5 retry smoke 覆盖。

## 后续建议

- PM 收敛 `MD-H5-02` 与 `M4C-H5-05` 后，决定是否重开 H5 retry smoke。
- m4c 下一步应读取 `runtime/write-api.json` 调真实 endpoint，不得用 direct package write 替代。