# Round 1 QA 预检记录

状态：QA 预检记录
所属子项目：`02-P-NBL`
Round：Round 1
日期：2026-06-02
输入文档：

- [`prd.md`](prd.md)
- [`qa-test-plan.md`](qa-test-plan.md)
- [`dev-checklist-current.md`](dev-checklist-current.md)
- [`todo-list.md`](todo-list.md)

## 1. 预检结论

当前结论：

```text
研发自动化预检通过；尚不能进入用户验收；正式 QA 仍需固定分支/commit、可运行构建或测试包、真机真实模型验证。
```

本次已处理前一轮复核指出的研发问题：

- primary URL 下载到坏包时，继续尝试 fallback URL。
- `state.json` 路径限制在 `models` 根目录内，拒绝绝对路径和 `..` 逃逸。
- macOS engine 使用 profile 中的 `ProviderOrder`。
- engine 初始化失败时区分缺模型和模型结构存在但不可加载。
- Onboarding 可以显示 `need_model + error`。
- 前端可通过 `EngineService.GetStatus()` 补查可能错过的 engine 状态。
- 用户主动下载时可安全替换 `models/sensevoice-zh`，失败时尝试恢复 backup。

## 2. 自动化验证结果

| 命令 | 结果 | 说明 |
|---|---|---|
| `cd privatevoice.src/frontend && npm run build` | 通过 | 前端构建通过，有既有 Svelte a11y warning |
| `cd privatevoice.src && go test ./internal/model -count=1` | 通过 | 模型包测试强制重跑 |
| `cd privatevoice.src && go test ./... -count=1` | 通过 | Go 全量测试强制重跑；新 checkout 需先完成前端构建以生成 `frontend/dist` |

前端构建 warning：

- `src/components/update/UpdateDialog.svelte`：dialog focus / noninteractive listener warning。
- `src/components/shared/ToggleSwitch.svelte`：button aria label warning。

判断：

```text
这些 warning 不由 Round 1 改动引入，本轮未修改对应组件。
```

## 3. 新增测试覆盖

已覆盖：

- 默认 profile 为 `sensevoice-zh`。
- 未知 model id 报错。
- `RequiredFileRule.AnyOf`。
- `RequiredFileRule.AllOf`。
- `model.int8.onnx` 优先于 `model.onnx`。
- 缺少 `tokens.txt` 失败。
- 0 字节 required file 失败。
- 旧 `models/sensevoice` 可解析。
- 新旧目录都存在时优先 `models/sensevoice-zh`。
- 非法 `state.json` fallback。
- state 指坏目录 fallback。
- state 指绝对路径时拒绝并 fallback。
- state 使用 `../` 逃逸时拒绝并 fallback。
- 不完整目录返回 `installed_incomplete`。
- bad archive 不写 installed state。
- primary 坏包时尝试 fallback URL。
- 下载失败不删除旧模型。
- 用户触发下载可替换已有 `models/sensevoice-zh`。

## 4. Fixture 状态

已新增：

```text
privatevoice.src/testdata/round1/
```

包含：

- `models-valid-legacy/`
- `models-valid-new/`
- `models-incomplete-missing-tokens/`
- `models-incomplete-missing-model/`
- `models-zero-byte/`
- `state-invalid-json/`
- `state-points-to-legacy/`
- `state-points-to-broken/`
- `userdict.json`
- `history.json`

说明：

```text
这些 fixture 是轻量 fake model 文件，只用于路径、state、校验、fallback 的确定性测试。
它们不能替代真实 SenseVoice 模型识别验证。
```

## 5. 仍未满足的正式 QA 准入项

| 项目 | 状态 | 说明 |
|---|---|---|
| 固定分支 | 已完成 | `codex/round1-model-profile` |
| 固定 commit id | 待完成 | 暂存区已收拢，提交后进入正式 QA 基线 |
| 可运行 App 或测试包 | 未完成 | 尚未打包 |
| 原始测试日志文件 | 未完成 | 当前结果记录在对话和本文件中，未单独落日志文件 |
| 真实 SenseVoice 模型下载 | 未完成 | 需要真实网络和模型源 |
| 真实 SenseVoice 初始化 | 未完成 | 需要真实模型文件 |
| 真机麦克风验证 | 未完成 | 需要 macOS 权限和真实录音 |
| 断网真实识别 | 未完成 | 需要真实模型和真机 |
| 网络观察 | 未完成 | 需要真机验证识别阶段无上传 |

## 6. 不可替代的真机 QA

正式 QA 必须覆盖：

- Apple Silicon 真机真实 SenseVoice 初始化。
- 旧 `models/sensevoice` 断网升级路径。
- 新 `models/sensevoice-zh` 新用户下载路径。
- 麦克风权限未授权 / 已授权。
- 辅助功能或上屏权限回归。
- 真实录音识别。
- 上屏文本。
- replacement。
- 历史写入。
- 已有模型时断网启动、录音、识别、写历史。
- 识别阶段网络观察。
- 菜单栏、Dock 隐藏策略、窗口层级、全屏、Split View smoke。
- 坏模型文件导致 engine 初始化失败时 UI 是否可恢复。

## 7. 下一步

建议顺序：

1. 创建 Round 1 专用分支。
2. 提交当前改动，得到固定 commit id。
3. 如要进入正式 QA，先生成可运行测试包或明确本地启动命令。
4. QA 按 [`qa-test-plan.md`](qa-test-plan.md) 执行真机场景。
5. QA 输出 `qa-report-YYYYMMDD.md`。
6. 如果 QA 通过，再按项目发布规则递增版本、更新 `CHANGELOG.md`、打包 `.dmg`。