# Phase 3.7.3 Clean QA

日期：2026-06-26

## 用户目标

用户确认按“先做 3.7.2 doctor/preflight POC，再做 3.7.3 clean environment QA，然后进入 3.8 document lease / App write API”的顺序推进，并要求开工 Phase 3.7.3。

## 已完成事项

- 为 `scripts/mindraw-doctor.mjs` 增加 `--system-handlers` 模式。
- `--system-handlers` 通过 macOS `NSWorkspace` 查询 `mindraw://` 默认 handler 和临时 `.mindraw` 探针包默认 handler，不启动 App，不修改 LaunchServices。
- 补充 doctor 单测到 11 条，覆盖缺 App、旧版本、缺 scheme、缺 document type、bundle id 错误、URL handler 错配、`.mindraw` handler 错配和非 macOS。
- 用临时 fake app CLI 矩阵验证 clean / 异常环境。
- 完成有效 `.mindraw` fixture 的 package smoke：`packageOpen=pass`。
- 写入 Phase 3.7.3 QA 报告，并同步 doctor 契约、companion app spec、主计划、工程地图和索引。

## 关键决策

- Phase 3.7.3 不卸载或覆盖 `/Applications/Mindraw.app`，采用可恢复的临时 fake app 场景模拟干净 / 异常环境。
- 默认 `doctor:mindraw` 仍不启动 Mindraw；真实打开动作只在显式 `--smoke` 时发生。
- 系统 handler 检测单独放在 `--system-handlers`，用于 m4c / QA preflight 更准确地区分“App 声明正确”和“LaunchServices 实际 handler 正确”。
- Phase 3.7 第一批可视为闭环；签名 / 公证、自动安装、Windows installer 和真实全新机器安装验收留作后续分发增强，不阻塞 Phase 3.8。

## 文件变更

- `scripts/mindraw-doctor.mjs`
- `scripts/mindraw-doctor.test.mjs`
- `02-P/qa/mindraw-phase373-clean-environment-qa.md`
- `02-P/qa/mindraw-phase37-companion-doctor-contract.md`
- `02-P/功能任务/companion-app-distribution-spec.md`
- `02-P/plan-progress.markdown`
- `CODEGRAPH.md`
- `INDEX.md`
- `.codex-sessionhistory/2026-06-26-Phase373CleanQA.md`

## 验证

- `npm run doctor:mindraw:test`：PASS，11 tests。
- `node --check scripts/mindraw-doctor.mjs`：PASS。
- `npm run doctor:mindraw -- --pretty --system-handlers`：PASS，当前本机 `warn`，唯一 warning 为 `MINDRAW_BUILD_UNKNOWN`；URL/package handler 均 `pass`。
- 临时 fake app CLI 矩阵：PASS，覆盖 missing app、old version、missing scheme、missing document type、wrong bundle id、wrong system handlers、missing package smoke。
- `npm run doctor:mindraw -- --pretty --system-handlers --smoke --package 02-P/Round01-mindraw-defstart/fixtures/minimal-empty.mindraw`：PASS，`packageOpen=pass`。
- `git diff --check` 覆盖本轮相关文件：PASS。

## 未决问题

- App metadata 仍不能稳定暴露 `Build202606261221`，doctor 保留 `MINDRAW_BUILD_UNKNOWN` warning。
- 本轮没有执行真实全新 macOS 用户 / 全新机器安装验收。
- deep link 完整视觉成功证据沿用 `0.8.3` hotfix smoke；本轮未制造未知 `documentId` 触发用户可见错误弹窗。
- Developer ID 签名、公证、自动下载 / 自动安装、Windows installer 和 Phase 3.8 document lease / App write API 尚未实现。

## 后续建议

- 下一步进入 Phase 3.8 document lease / App write API spike。
- 3.8 第一批应先定义外部工具写入 `.mindraw` 包时的 dirty/revision/lease 契约、拒写策略、App 接管策略和 QA failure matrix，再决定是否进入生产代码。