# Round 1 QA 测试计划：模型 Profile 基础设施

状态：v0.1 QA 计划稿
所属子项目：`02-P-NBL`
Round：Round 1
日期：2026-06-02
输入文档：

- [`prd.md`](prd.md)
- [`engineering-tasks.md`](engineering-tasks.md)

## 1. QA 目标

Round 1 的 QA 目标不是证明“代码结构变漂亮了”，而是证明：

```text
底层模型 Profile 改造没有破坏现有用户体验，并且为后续多模型接入提供了可验证的基础。
```

重点验证：

- 老用户升级后可继续使用旧模型目录。
- 新用户仍可完成 SenseVoice 下载和初始化。
- 不完整模型不会被误判为可用。
- 下载失败不会破坏已有模型。
- 用户词库、历史、设置不丢。
- 已有模型时断网可正常识别。
- UI 不暴露 Round 2-5 的新模型和语言能力。

## 2. 测试范围

### 2.1 本轮必须测

- 模型 profile registry。
- required files 校验。
- `models/state.json` 缺失、损坏、失效。
- 新目录 `models/sensevoice-zh`。
- 旧目录 `models/sensevoice`。
- 新旧目录同时存在。
- Onboarding 下载链路。
- Wails public API 兼容。
- engine 初始化。
- 用户词库 replacement。
- 历史写入。
- 权限页、首页、词库页、历史页基础回归。
- 断网已有模型识别。

### 2.2 本轮不测

- Moonshine 真实识别效果。
- Parakeet 真实识别效果。
- Qwen3-ASR 真实识别效果。
- 多语言 UI。
- 模型选择 UI。
- 模型删除 UI。
- 模型 marketplace。

## 3. QA 进入标准

研发移交 QA 前必须提供：

- 可运行构建或可运行分支。
- 变更范围说明。
- 开发自查记录。
- Go 单元测试结果。
- 前端构建或现有前端检查结果。
- 测试 fixture 说明。
- 已知风险说明。

未满足以上条件时，QA 可以拒绝进入正式验收，只做预检。

## 4. 测试环境

最低环境：

| 项目 | 要求 |
|---|---|
| OS | macOS，优先覆盖当前主要目标版本 |
| 芯片 | Apple Silicon 必测；Intel 如仍支持则抽测 |
| 网络 | 联网、断网两种状态 |
| 权限 | 麦克风未授权、已授权；辅助功能/输入权限按当前产品要求覆盖 |
| 模型目录 | 旧目录、新目录、新旧同时存在、损坏目录 |

测试数据目录建议：

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

建议包含：

```text
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
zh_short.wav
```

如果真实模型体积过大，自动化测试可以使用小型 fake file fixture；真实识别必须在真机手工测试中使用真实模型完成。

## 5. 测试矩阵

| ID | 场景 | 前置数据 | 网络 | 期望结果 |
|---|---|---|---|---|
| R1-QA-001 | 老用户旧目录 | 只有 `models/sensevoice`，文件完整 | 断网 | 不重新下载，能初始化和识别 |
| R1-QA-002 | 新用户无模型 | 无 `models` 目录 | 联网 | Onboarding 下载到 `models/sensevoice-zh`，校验通过 |
| R1-QA-003 | 新目录优先 | 新旧目录都完整，无 state | 断网 | 使用 `models/sensevoice-zh` |
| R1-QA-004 | state 指旧目录 | state path=`sensevoice`，旧目录完整 | 断网 | 使用旧目录，不迁移、不删除 |
| R1-QA-005 | state 非法 JSON | `state.json` 非法，新/旧目录完整 | 断网 | fallback 到目录探测 |
| R1-QA-006 | state 指坏目录 | state 指向不完整目录，旧目录完整 | 断网 | fallback 到旧目录 |
| R1-QA-007 | 缺 tokens | 目录只有模型文件 | 断网 | `ModelExists=false`，不初始化 engine |
| R1-QA-008 | 缺模型文件 | 目录只有 `tokens.txt` | 断网 | `ModelExists=false`，不初始化 engine |
| R1-QA-009 | 0 字节文件 | required file 为 0 字节 | 断网 | 模型不可用 |
| R1-QA-010 | int8 优先 | 同时有 `model.int8.onnx` 和 `model.onnx` | 断网 | 使用 int8 |
| R1-QA-011 | 下载失败保护 | 已有旧模型，下载 URL 失败 | 联网/断网 | 旧模型仍可用，旧目录未被破坏 |
| R1-QA-012 | 解压失败保护 | 已有旧模型，压缩包损坏 | 联网 | 不写入完整 state，旧模型仍可用 |
| R1-QA-013 | 重试下载 | 前一次下载失败 | 联网 | 再次下载可继续，不需手动清理 |
| R1-QA-014 | Wails API 兼容 | 任意有效模型状态 | 任意 | 旧 `ModelExists` / `DownloadModel` 调用可用 |
| R1-QA-015 | UI 不暴露新能力 | 任意模型状态 | 任意 | 不出现 Moonshine、Parakeet、Qwen3-ASR、语言选择、模型选择 |
| R1-QA-016 | replacement 回归 | 模型完整，词库含 replacement | 断网 | 识别结果经过 replacement |
| R1-QA-017 | 历史回归 | 模型完整，历史为空 | 断网 | 识别后新增历史 |
| R1-QA-018 | 权限回归 | 麦克风未授权 | 任意 | 不进入假录音状态，权限页可用 |
| R1-QA-019 | 权限已授权 | 麦克风已授权 | 断网 | 可录音、识别、上屏 |
| R1-QA-020 | macOS 真实使用 smoke | 模型完整 | 断网 | 菜单栏、Dock 策略、窗口层级、全屏/Split View 无明显回归 |

## 6. 自动化测试建议

自动化优先覆盖确定性逻辑：

- `ModelRegistry` 默认模型。
- `LanguageRegistry` 最小 `zh-CN`。
- required files `allOf` / `anyOf`。
- int8 优先。
- 0 字节 required file 失败。
- state 缺失 fallback。
- state 非法 JSON fallback。
- state 指坏目录 fallback。
- 新旧目录优先级。
- `SelectedModelID` 默认值。
- 无效 `SelectedModelID` 回退。
- 下载失败不删除旧目录。

建议命令：

```bash
cd privatevoice.src
go test ./...
```

如果新增前端相关改动，执行项目现有前端构建或检查命令。

## 7. 手工测试步骤

### 7.1 老用户升级路径

1. 准备 App Support 目录，只放旧模型目录 `models/sensevoice`。
2. 删除或不创建 `models/state.json`。
3. 断网。
4. 启动应用。
5. 确认不进入模型下载页。
6. 完成一次录音识别。
7. 确认历史新增。
8. 确认旧模型目录仍存在，未被移动或删除。

通过标准：

- 用户无需重新下载。
- 识别可用。
- 用户数据不丢。

### 7.2 新用户下载路径

1. 准备干净 App Support 目录。
2. 联网启动应用。
3. 确认进入 Onboarding 下载流程。
4. 下载完成后检查：
   - `models/sensevoice-zh` 存在。
   - `models/state.json` 存在。
   - state 中 `selectedModelId = sensevoice-zh`。
5. 完成一次录音识别。

通过标准：

- 下载路径不再写入旧目录作为新安装目标。
- 下载完成后 engine ready。

### 7.3 下载失败保护

1. 准备完整旧目录 `models/sensevoice`。
2. 配置错误下载 URL 或断网触发下载失败。
3. 执行下载。
4. 确认旧目录未被删除。
5. 重启应用。
6. 确认仍可使用旧模型识别。

通过标准：

- 失败不会破坏已有模型。
- 再次启动可恢复。

### 7.4 离线承诺验证

1. 准备完整模型。
2. 断网。
3. 启动应用。
4. 录音识别。
5. 检查历史写入。
6. 观察是否出现异常网络请求或下载重试。

通过标准：

- 已有模型时离线可完整使用。
- 识别阶段不请求远程服务。

## 8. 证据要求

QA 结论必须记录：

- 分支名 / commit id。
- App 版本和 build 编号。
- macOS 版本。
- 芯片类型。
- 测试模型目录组合。
- 执行命令和结果。
- 自动化测试日志。
- 手工测试矩阵结果。
- 关键失败场景截图或日志。
- 断网测试结果。
- 网络观察结论。

建议输出：

```text
02-P-NBL/round-1/qa-report-YYYYMMDD.md
```

## 9. QA 退出标准

QA 通过必须同时满足：

- P0/P1 问题全部关闭。
- P2 问题已修复或有明确接受结论。
- 自动化测试通过。
- 老用户旧目录升级路径通过。
- 新用户下载路径通过。
- 下载失败保护通过。
- 断网已有模型识别通过。
- replacement 和历史回归通过。
- UI 不暴露新模型和语言入口。
- QA 证据记录完整。

## 10. 缺陷分级

| 级别 | 定义 | 示例 |
|---|---|---|
| P0 | 阻塞发布，核心功能不可用或数据损坏 | 老用户升级后模型不可用；下载失败删除旧模型；用户词库丢失 |
| P1 | 主要路径失败或离线承诺破坏 | 已有模型断网不能识别；不完整模型导致崩溃；Wails 旧 API 断裂 |
| P2 | 局部功能异常，有绕过方式 | state 修复失败但不影响加载；错误文案不够清晰 |
| P3 | 轻微问题 | 日志不够明确；测试辅助文件残留但不影响使用 |