# Round 3 QA 测试计划：Moonshine English 默认模型

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

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

## 1. QA 目标

Round 3 的 QA 目标是证明：

```text
English 语言版本默认使用 Moonshine English，中文 SenseVoice 路径不退化，且模型下载/初始化失败不会破坏用户数据。
```

重点验证：

- English fresh user 默认 Moonshine。
- Chinese fresh user 默认 SenseVoice。
- 老中文用户升级不被强制下载 Moonshine。
- Moonshine 可下载、校验、加载、离线识别。
- 语言切换会带动 current model 同步。
- Moonshine 失败不破坏 SenseVoice、userdict、history、replacement。

## 2. 测试范围

### 2.1 本轮必须测

- `moonshine-en` profile。
- Moonshine required files 校验。
- English language default model。
- current model resolver。
- onboarding 下载 current model。
- Moonshine engine 初始化。
- 英文离线识别和 history 写入。
- 中文 SenseVoice 回归。
- 语言切换后的模型同步。
- 下载失败保护。
- 缺文件保护。
- 老用户升级保护。

### 2.2 本轮不测

- Parakeet。
- Qwen3-ASR。
- Moonshine v2。
- realtime partial transcript。
- 模型选择页。
- 模型删除 UI。
- 30+ 语言列表。
- Developer ID 签名和 notarization。

## 3. QA 进入标准

研发移交 QA 前必须提供：

- 可运行构建或分支。
- 变更范围说明。
- `go test ./... -count=1` 结果。
- `npm run build` 结果。
- current model resolver 说明。
- Moonshine 下载 URL。
- 已知风险说明。

## 4. 测试环境

| 项目 | 要求 |
|---|---|
| OS | macOS |
| 芯片 | Apple Silicon 必测；Intel 如仍支持则抽测 |
| 网络 | 联网、断网 |
| 语言 | `zh-CN`、`en`、其他语言 fallback |
| 用户状态 | 老中文用户、新中文用户、新 English 用户、缺文件用户 |
| 模型状态 | SenseVoice 已安装、Moonshine 未安装、Moonshine 已安装、Moonshine 缺文件 |

系统语言不建议反复真实修改 macOS 全局设置作为唯一手段。自动化和半自动 QA 可以用临时用户数据目录、config 手动语言设置、mock detector 或启动环境配合验证。

## 5. 测试矩阵

| ID | 场景 | 前置条件 | 期望结果 |
|---|---|---|---|
| R3-QA-001 | Moonshine profile | 查询 `moonshine-en` | profile 存在，backend=`moonshine` |
| R3-QA-002 | Moonshine required files valid | 五个 required files 完整 | 校验通过 |
| R3-QA-003 | Moonshine required files missing | 删除任意一个 required file | 校验失败 |
| R3-QA-004 | English default model | effective language=`en`，auto model | current model=`moonshine-en` |
| R3-QA-005 | Chinese default model | effective language=`zh-CN`，auto model | current model=`sensevoice-zh` |
| R3-QA-006 | 旧配置兼容 | 缺 `ModelSelectionMode` | 默认 auto，不锁死旧 `SelectedModelID` |
| R3-QA-007 | English fresh onboarding | 干净 App Support + English | 下载 Moonshine |
| R3-QA-008 | Chinese fresh onboarding | 干净 App Support + 中文 | 下载/使用 SenseVoice |
| R3-QA-009 | 老中文用户升级 | 已有 SenseVoice/userdict/history | 不下载 Moonshine，数据不丢 |
| R3-QA-010 | Moonshine 加载 | Moonshine 完整安装 | engine ready，硬件信息可区分 Moonshine |
| R3-QA-011 | 英文离线识别 | Moonshine ready + 断网 | 英文语音可识别 |
| R3-QA-012 | history 写入 | 英文识别完成 | `history.json` 新增英文记录 |
| R3-QA-013 | replacement 不退化 | 中文 replacement 已配置 | 中文回归仍生效 |
| R3-QA-014 | 中文回归 | SenseVoice ready | 中文离线识别可用 |
| R3-QA-015 | 中文切 English | SenseVoice installed，Moonshine missing | 进入 Moonshine 下载/need_model |
| R3-QA-016 | English 切中文 | Moonshine installed，SenseVoice installed | 切回 SenseVoice |
| R3-QA-017 | Moonshine 下载失败 | 阻断网络或坏 URL | 不删除 SenseVoice，不写入有效 Moonshine 状态 |
| R3-QA-018 | Moonshine 初始化失败 | 模型完整但强制 provider/路径异常 | 状态 error，数据不丢 |
| R3-QA-019 | staging 清理 | 下载失败后 | `.staging` 不被当成可用模型 |
| R3-QA-020 | UI 文案 | English onboarding | 没有中文模型写死文案 |
| R3-QA-021 | 重启持久化 | English + Moonshine installed 后重启 | 仍为 Moonshine ready |
| R3-QA-022 | 其他系统语言 fallback | detector=`fr-FR` | effective=`en`，current model=`moonshine-en` |

## 6. 自动化测试建议

后端优先覆盖：

- `GetModelProfile("moonshine-en")`。
- `ValidateModelDir(moonshine-en)`。
- `ResolveCurrentModel`。
- `ModelSelectionMode` normalize。
- Engine backend dispatch。
- Unknown backend error。
- Download source validation。

建议命令：

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

前端至少执行：

```bash
cd privatevoice.src/frontend
npm run build
```

## 7. 手工测试步骤

### 7.1 English 新用户路径

1. 备份真实 App Support。
2. 使用临时干净 App Support 或临时 HOME。
3. 模拟 English effective language。
4. 启动 App。
5. 检查 UI 是 English。
6. 检查 onboarding 下载 Moonshine。
7. 下载完成后检查 engine ready。
8. 断网。
9. 按 R-Alt 说一段英文。
10. 检查识别结果和 `history.json`。

通过标准：

- 不下载 SenseVoice。
- Moonshine 模型目录为 `models/moonshine-en`。
- 英文识别结果写入 history。
- 断网时不访问网络也能识别。

### 7.2 中文老用户升级路径

1. 使用真实或复制的老用户数据，包含 SenseVoice、userdict、history。
2. 启动 Round 3 App。
3. 检查 current model 为 `sensevoice-zh`。
4. 做一次中文识别。
5. 检查 replacement 和 history。

通过标准：

- 不触发 Moonshine 下载。
- 不改写或删除 SenseVoice。
- 用户词库和历史保留。

### 7.3 语言切换路径

1. 中文状态下打开设置页。
2. 切到 English。
3. 检查 UI 立即变英文。
4. 检查 current model 变为 Moonshine。
5. 如果未安装，下载 Moonshine。
6. 切回中文。
7. 检查 current model 恢复 SenseVoice。

通过标准：

- 切换语言时模型跟随 effective language。
- 两个模型都保留。
- 切换失败不破坏原模型。

### 7.4 下载失败保护

1. 准备已安装 SenseVoice。
2. 让 English current model 指向 Moonshine。
3. 模拟 Moonshine 下载失败。
4. 检查 SenseVoice 目录和 state。
5. 切回中文并识别。

通过标准：

- Moonshine 失败不会破坏中文路径。
- staging/incomplete 目录不被判定为 installed。

## 8. QA 结论标准

可标记 Round 3 功能性 QA PASS 的条件：

- R3-QA-001 到 R3-QA-022 全部通过，或失败项有明确非阻断说明。
- Round 2 语言设置路径未回归。
- SenseVoice 中文核心路径未回归。
- QA 报告记录版本、build、commit、测试包、日志和关键证据。