# Round 2 QA 测试计划：语言检测与语言版本设置

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

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

## 1. QA 目标

Round 2 的 QA 目标是证明：

```text
语言版本配置可被正确检测、保存、恢复，并且不会破坏 Round 1 已验证通过的 SenseVoice 离线识别链路。
```

重点验证：

- 老用户升级不丢数据。
- 新用户首次启动语言解析正确。
- 设置页可切换自动、中文、English。
- UI 文案跟随 effective language。
- 语言切换不触发模型切换、模型删除或模型下载。
- Round 1 的 SenseVoice、replacement、历史、断网识别不退化。

## 2. 测试范围

### 2.1 本轮必须测

- `LanguageMode` / `LanguageID` 默认值。
- 旧 config 兼容。
- 非法 language config fallback。
- 中文系统 auto 解析。
- English 系统 auto 解析。
- 其他系统语言 auto 解析。
- 设置页语言切换。
- 重启后语言选择持久化。
- 前端 i18n 切换。
- SenseVoice 模型目录不变。
- `SelectedModelID` 不被语言切换改写。
- 用户词库、历史、热键、音频设备、Dock 设置不丢失。
- 断网已有模型识别。

### 2.2 本轮不测

- Moonshine 识别。
- Parakeet 识别。
- Qwen3-ASR 识别。
- 30+ 语言列表。
- 粤语独立语言。
- 欧洲语言 UI。
- 模型选择页。
- 模型删除和回滚。
- Developer ID 签名和 notarization。

## 3. QA 进入标准

研发移交 QA 前必须提供：

- 可运行构建或分支。
- 变更范围说明。
- `go test ./...` 结果。
- 前端构建结果。
- 语言检测 mock 或测试方式说明。
- 老用户升级测试数据说明。
- 已知风险说明。

## 4. 测试环境

| 项目 | 要求 |
|---|---|
| OS | macOS |
| 芯片 | Apple Silicon 必测；Intel 如仍支持则抽测 |
| 网络 | 联网、断网 |
| 系统语言 | 中文、English、至少一种其他语言模拟 |
| 用户状态 | 老用户、新用户、非法配置用户 |
| 模型状态 | 旧目录 `models/sensevoice`、新目录 `models/sensevoice-zh` |

系统语言不建议真实反复改系统全局设置作为唯一测试手段。自动化应通过 detector mock 覆盖；真机只做关键 smoke。

## 5. 测试矩阵

| ID | 场景 | 前置条件 | 期望结果 |
|---|---|---|---|
| R2-QA-001 | 老配置升级 | config 无 `LanguageMode` / `LanguageID` | 正常启动，默认 auto，有效语言正确 |
| R2-QA-002 | 中文系统 auto | detector 返回 `zh-CN` | effective=`zh-CN`，UI 中文 |
| R2-QA-003 | English 系统 auto | detector 返回 `en-US` | effective=`en`，UI English |
| R2-QA-004 | 其他系统语言 auto | detector 返回 `fr-FR` | effective=`en`，UI English |
| R2-QA-005 | 手动中文 | 设置页选择中文 | 保存 `manual/zh-CN`，UI 立即中文 |
| R2-QA-006 | 手动 English | 设置页选择 English | 保存 `manual/en`，UI 立即 English |
| R2-QA-007 | 切回自动 | 设置页选择自动 | 保存 `auto`，effective 跟随 detector |
| R2-QA-008 | 重启持久化 | 手动 English 后重启 | 仍为 English |
| R2-QA-009 | 非法 LanguageMode | config 写入坏值 | 启动不崩溃，fallback auto |
| R2-QA-010 | 非法 LanguageID | config 写入坏值 | 启动不崩溃，fallback 有效语言 |
| R2-QA-011 | 语言切换不改模型 | 已安装 SenseVoice | `SelectedModelID` 仍为 `sensevoice-zh` |
| R2-QA-012 | 语言切换不下载模型 | 已有模型，联网观察 | 不触发新下载 |
| R2-QA-013 | 语言切换不删模型 | 旧目录模型 | `models/sensevoice` 保留 |
| R2-QA-014 | 词库保留 | userdict 有 replacement | 切换语言后 replacement 仍在 |
| R2-QA-015 | 历史保留 | history 有记录 | 切换语言后历史不丢 |
| R2-QA-016 | 热键保留 | 自定义热键或默认热键 | 切换语言后仍可触发 |
| R2-QA-017 | 断网识别 | 已有模型，断网 | 可录音识别并写历史 |
| R2-QA-018 | UI 不暴露新模型 | 任意语言 | 不出现 Moonshine/Parakeet/Qwen3-ASR |
| R2-QA-019 | English UI 文案 | effective=`en` | 设置页、onboarding 关键文案不是中文 |
| R2-QA-020 | 中文 UI 文案 | effective=`zh-CN` | 设置页、onboarding 关键文案是中文 |

## 6. 自动化测试建议

后端优先覆盖：

- `NormalizeLanguageMode`。
- `NormalizeLanguageID`。
- detector locale normalize。
- `ResolveEffectiveLanguage`。
- `LanguageRegistry` 查询和排序。
- `GetLanguageSettings` 返回 options。
- `SetLanguageAuto`。
- `SetLanguageManual`。
- 老 config 缺字段加载。
- 非法 config fallback。

建议命令：

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

前端至少执行：

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

## 7. 手工测试步骤

### 7.1 老用户升级

1. 准备已有 App Support 数据，含：
   - `config.json`
   - `userdict.json`
   - `history.json`
   - `models/sensevoice`
2. 确保旧 config 不含语言字段。
3. 启动 Round 2 App。
4. 检查语言设置默认值。
5. 完成一次识别。
6. 检查词库、历史、模型目录。

通过标准：

- 老用户无需重新设置。
- 识别可用。
- 用户数据不丢。

### 7.2 新用户中文系统

1. 使用干净 App Support。
2. mock 或真实设置 detector 返回中文。
3. 启动 App。
4. 检查 UI 为中文。
5. 检查默认模型仍是 `sensevoice-zh`。

通过标准：

- 中文用户默认中文。
- 不出现模型选择步骤。

### 7.3 新用户 English 系统

1. 使用干净 App Support。
2. mock detector 返回 `en-US`。
3. 启动 App。
4. 检查 UI 为 English。
5. 检查默认模型仍是 `sensevoice-zh`。

通过标准：

- English 用户默认 English。
- 本轮不出现 Moonshine。

### 7.4 设置页切换

1. 打开设置页。
2. 在语言版本中依次选择：
   - 中文
   - English
   - 自动
3. 每次切换后检查 UI 文案、config、模型目录。
4. 重启 App 后复核。

通过标准：

- UI 立即切换。
- 重启后持久化。
- 模型不被删除、迁移或下载。

### 7.5 离线回归

1. 准备完整 SenseVoice 模型。
2. 切到 English UI。
3. 断网。
4. 完成一次识别。
5. 切回中文 UI。
6. 再完成一次识别。

通过标准：

- 不管 UI 语言是什么，已有模型离线识别都可用。
- history 正常写入。

## 8. QA 结论标准

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

- 测试矩阵中 R2-QA-001 到 R2-QA-020 全部通过，或失败项有明确非阻断说明。
- Round 1 核心路径未回归。
- QA 报告记录版本、build、commit、测试包、日志和关键证据。