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

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

1. QA 目标

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

底层模型 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 如仍支持则抽测
网络	联网、断网两种状态
权限	麦克风未授权、已授权；辅助功能/输入权限按当前产品要求覆盖
模型目录	旧目录、新目录、新旧同时存在、损坏目录

测试数据目录建议：

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
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 回退。
下载失败不删除旧目录。

建议命令：

cd privatevoice.src
go test ./...

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

7. 手工测试步骤

7.1 老用户升级路径

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

通过标准：

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

7.2 新用户下载路径

准备干净 App Support 目录。
联网启动应用。
确认进入 Onboarding 下载流程。
下载完成后检查：

models/sensevoice-zh 存在。
models/state.json 存在。
state 中 selectedModelId = sensevoice-zh。

完成一次录音识别。

通过标准：

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

7.3 下载失败保护

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

通过标准：

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

7.4 离线承诺验证

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

通过标准：

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

8. 证据要求

QA 结论必须记录：

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

建议输出：

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	轻微问题	日志不够明确；测试辅助文件残留但不影响使用