# 测试报告 ## 第 1 轮(2026-09-06) - 输入:00-request.md、10-analysis.md@第 1 轮、20-product.md@第 1 轮、30-uiux.md@第 2 轮、40-review.md@第 2 轮、50-backend.md@第 1 轮、55-frontend.md@第 1 轮、OpenSpec `book-word-spelling-game`(specs `bookshelf-book-key-words`、`bookshelf-spelling-game` 每个 Scenario 作为用例;tasks.md 7.1、7.2) - 应用的历史教训:无 - 环境:入口 `http://127.0.0.1/`(Nginx 80 → 前端 5173 dev server + 后端 8000,`/api/health` 200);接口直测 `http://127.0.0.1/api/books/{stage}/{book_folder}/key-words`;浏览器为 Cursor 内嵌 Chromium(自动播放策略宽松,见「测不到的」);测试用书 `stage-03/AtTheSeaside`(路由 `stage-03__AtTheSeaside`),无题库对照书 `stage-03/AtThePool` - 结论:**返工:退回前端**(1 P0 + 2 P1 + 7 P2;P0 为家长录入页在产品界面内不可达,P1 为脏状态守卫漏一个返回入口、上一题音频慢失败会吞掉下一题) - 涉及孩子端:是(需另跑 child-ux-tester) ### 追溯链机械核对(诉求# → 功能# → 页面/接口) | 诉求 | 功能 | 落点(实测) | 断链? | | --- | --- | --- | --- | | P0-1 | F01/F02/F10 | `/parent/review/:id?tab=key-words` `KeyWordsPanel` + GET/PUT key-words | **页面存在但界面内无入口**(Bug #1) | | P0-2 | F03 | `ChildBookReader` 完成卡「玩拼字」→ `/spell/:id` | 否 | | P0-3 | F04/F10 | `spelling.ts buildSpellingRound` + 同一 GET | 否 | | P0-4 | F06 | `buildLetterTiles/pickDistractors` | 否 | | P0-5 | F05/F07 | `/spell/:id` 再听一次 / 字母块 / 退一步 | 否 | | P0-6 | F05/F07/F08/F09 | 判题、首次口径、结果页 | 否 | | P0-7 | F01/F03 | 家长校对区 vs 孩子读后路径 | 大人侧入口断链(同 Bug #1) | | P0-8 | F11 | 已由用户确认,状态文件有记录 | 否 | | P1-1 | F02/F03 | 无启用词不显示入口 + 空状态页 | 否 | | P1-2 | F04/F06/F07 | 重复字母独立块、判题比对 normalized | 否 | | F12–F14 | — | 听听书里的话 / `spellingAttempts` / 仪表盘「最近拼错的词(本设备)」 | 否 | ### 成功标准核对(10-analysis 验收口径) | 标准 | 结果 | 依据 | | --- | --- | --- | | P0-1 录入并稳定关联该书 | **部分满足** | 深链进入页签录入 wanted/shell/boat + 1 句保存后,刷新、`curl` GET 均一致,`QaSpellOther` 等其他书文件不受影响;但大人从「书架长按🐻→校对→点书」到达的是 `/book/:id` 校对阅读器,全站没有任何按钮/链接指向 `/parent/review/:id`,只能手输 URL(Bug #1) | | P0-2 读完后自然进入默写 | 满足 | 读完 17 页 → 读一读这些词(6 词)→ 完成卡显示 64px 高主按钮「🔤 玩拼字」,去拼读/返回书架降为 44px 文字级;阅读页与拼字页均无底栏 | | P0-3 题目来自当前书随机 | 满足 | 8 词题库两次开局分别为 `at→shell→wanted→swimming→boat`、`swimming→boat→at→wanted→sea`(子集与顺序均不同);3 词全出;回合进行中把配置改为 8 词,进行中回合仍为 3 题 | | P0-4 乱序 + 1–2 个辨析干扰 | 满足 | wanted:`n i u e d a t w`(干扰 i/u,同类元音);shell:`a s o h l l e`(两个独立 l + a/o);boat:`a t i b o`(恰 1 个);swimming 10 块保留 m、i 各两个;未出现与目标同字母的干扰 | | P0-5 只点候选字母、无键盘 | 满足 | `/spell` 页 `input/textarea/contenteditable` 数量为 0;全程点字母块 + 退一步完成 | | P0-6 判定拼写表现 | 满足 | `wantid` 判错保留答案槽并抖动提示;退两步改 `wanted` 显示「✓ 改对啦」;结果页「你自己拼对了 2 个」,wanted 标「↻ 再试后拼对」;localStorage `wanted.wrongCount=1, correctCount=0, firstAttemptCorrect=false, completedAfterRetry=true` | | P0-7 大人/孩子分区 | **部分满足** | 孩子流程无编辑控件、底栏仍为看书/拼读/闯关;但大人配置入口未接线(Bug #1) | | P0-8 先确认再开发 | 满足 | state.md 记录用户确认后才进入开发,本轮未涉及 | | P1-1 无词不进空游戏 | 满足 | 全部停用后完成卡恢复原两按钮;直达 `/spell/stage-03__AtThePool` 显示「这本书还没有拼字,先回书架吧」仅一个返回动作 | | P1-2 不产生无解/错判 | 满足 | shell 两个 l 分别可点;`judge` 只比对目标;`at`(2 字母)洗牌后不等于目标顺序 | ### Spec Scenario 逐条核对 **bookshelf-book-key-words** | Scenario | 结果 | 依据 | | --- | --- | --- | | 进入页签看到当前书 | **失败(入口)** | 页头「At The Seaside · 第3级」+ 页签正确,但 WHEN 描述的「长按小熊→校对→打开某本书的校对页」实走到 `/book/:id`,无处切到重点词句(Bug #1) | | 编辑与删除已有条目 | 通过 | 编辑 shell→shells、编辑为重复词 Boat 被拒;删除 want;删除已关联句弹「关联 1 个词,只解除语境、保留单词。」,确认后 wanted 变「还没有关联句子」 | | 合法单词 ` Wanted ` | 通过 | 前端显示 `wanted` ✓ 出题;接口 PUT ` Wanted ` 回传 text=normalized=wanted,客户端伪造的 normalized 被覆盖 | | 非法形式被拒绝 | 通过 | ice cream→「一次只能输入一个单词,不能有空格」、don't→「暂不支持带撇号的单词」、sea-side→「暂不支持带连字符的单词」、abc1→「单词里不能有数字」、空→「请先输入一个单词」;接口对同批 + `café`、空词、空句返回 422 逐条 `{index,field,reason}` | | 重复单词 want/Want | 通过 | 前端「这个单词已经在列表里了」;接口 `duplicate normalized word` | | 停用影响数量 | 通过 | 3→2,再启用→3 | | 继续编辑 | 通过 | NavBar 返回弹「更改还没保存」→ 继续编辑,草稿(含关联)保留 | | 放弃更改 | 通过 | 停用 boat + 删句 + 改词后切「文本校对」→ 放弃更改 → 页签切换;切回后恢复为最近保存的 3 词 1 句 | | 读取未配置的书 | 通过 | `QaSpellTest` GET 200 空文档且不落盘 | | 保存并重新读取 | 通过 | 3 词 1 句刷新一致;二次保存保留 id/created_at;其他书字节不变 | | 服务端校验 | 通过 | 422 前后文件字节一致;类型错误 422 同样不改写 | | 保存失败不假装成功 | 通过 | 后端:目标路径为目录时 PUT 500 `Failed to persist`,无残留 `.tmp`;前端:拦截接口后保存显示「没有保存成功 / 刚才的内容还在」+「重新保存」,草稿保留;解除拦截后重试成功 | **bookshelf-spelling-game** | Scenario | 结果 | 依据 | | --- | --- | --- | | 有题库时显示入口 | 通过 | 见 P0-2 | | 无题库时不显示 | 通过 | 全部停用后完成卡只有 去拼读/返回书架 | | 直接访问无题的书 | 通过 | AtThePool 空状态,仅「回书架」 | | 多于 5 个词 | 通过 | 8 词两轮均 5 题,子集/顺序不同 | | 少于 5 个词 | 通过 | 3 词恰各出一次 | | 重听 | 通过 | 点「再听一次」触发新一轮 `play()` 调用;页面无目标词文本(DOM 正则检索 wanted/shell/boat 均无) | | 音频全失败 | 通过 | 打桩 `play()` reject + `speak()` error:每题「这个词暂时听不到,先换一个,不算错。」后跳过,结果页「你自己拼对了 0 个 / 今天先听到这里」,学习记录条数不变 | | 用户示例 wanted | 通过 | 8 块、干扰 i/u 或 o/u,顺序乱序 | | 重复字母 shell | 通过 | 7 块含两个独立 l,干扰 a/o 或 i/o | | 短词 boat | 通过 | 5 块恰 1 干扰 | | 正常拼写 | 通过 | 第 N 个字母入槽即判「★ 自己拼对啦!」,900ms 后进下一题 | | 撤回 | 通过 | 点 s、h 后退一步,槽内只剩 s,h 恢复可点 | | 首次拼错再改对 | 通过 | 见 P0-6 | | 首次拼对 | 通过 | shell/boat `firstAttemptCorrect=true` | | 有错词 | 通过 | 「再练一次 只练刚才改过的」仅 1 题(第 1 / 1 个) | | 全对 | 通过(有 P2) | 复练轮全对后无「再练一次」,只剩「完成,回书架」——但为透明文字按钮,非「突出」(Bug #6) | | 记录即时落盘 | 通过 | 首题填满即写入(attempts 4→5),随后 × 退出「要先休息一下吗?已经拼过的会记下来。」→ 继续拼状态保留 / 先回书架;未答题无记录 | | 家长查看 | 通过 | `/parent`「最近拼错的词(本设备)」显示 wanted · At The Seaside · 时间 + 「换设备后不会同步」 | ### P0 功能核对(20-product F01–F11) | 功能 | 结果 | 备注 | | --- | --- | --- | | F01 每书重点内容管理 | 部分 | 增改删启停均可;入口不可达(Bug #1);顶栏返回漏守卫(Bug #2) | | F02 单词可出题校验 | 通过 | 前后端双重校验一致 | | F03 读后默写入口 | 通过 | 有/无题库两态正确 | | F04 当前书随机组题 | 通过 | 快照冻结实测通过 | | F05 听音识词 | 通过(有 P1) | 自动播、再听一次 68px;慢失败误跳题(Bug #3) | | F06 乱序字母与干扰项 | 通过 | — | | F07 点字母拼写与撤回 | 通过 | — | | F08 判题与温和纠错 | 通过 | 不清空、不扣分、文字+抖动 | | F09 本轮测验结果 | 通过 | — | | F10 内容后端持久化 | 通过 | 36 项接口断言全过 | | F11 原型确认门禁 | 通过 | — | | F12 语境关联 | 通过 | 「🎧 听听书里的话」`speak("We wanted an ice cream.", en-GB)`,无关联词不显示 | | F13 本机学习状态融合 | 通过 | `source=spelling`、`spellingAttempts` 落盘;Learn/书架「今天练这些词」能看到 | | F14 家长查看近期错词 | 通过(有 P2) | 级别显示原始 `stage-03`(Bug #7) | ### Bug 清单 | # | 现象 | 复现步骤 | 疑似归属 | 级别 | | --- | --- | --- | --- | --- | | 1 | 大人在产品界面内到不了「重点词句」录入页:全站无任何按钮/链接指向 `/parent/review/:id`;只能手输 URL。20-product IA「书架长按小熊 → 校对模式 → 选书校对 → 当前绘本校对页 → 重点词句」未落地;55-frontend 只验证了深链 | 1) `http://127.0.0.1/` 长按🐻 → 点「校对」 2) 点 At the Seaside 卡片 → 进入 `/book/stage-03__AtTheSeaside`(句子时间/波形校对器),页面控件无「校对页/重点词句」 3) 点「学习情况」→ `/parent`,无任何按书链接 4) `grep parent/review` 全前端 src 仅 App.tsx 路由一处 | 前端(入口接线);设计需明确入口控件放在校对阅读器还是学习情况 | **P0** | | 2 | 家长顶栏「← 回书架」链接绕过脏状态守卫,未保存内容无提示直接丢失(Spec「未保存更改离开保护」要求点击返回时确认) | 1) `/parent/review/stage-03__AtTheSeaside?tab=key-words` 添加 `donkey`(未保存,显示「有更改还没保存」) 2) 点页面最上方 `ParentLayout` 的「← 回书架」 → 直接跳到 `/`,无对话框 3) 回到页签,donkey 不存在 | 前端(`ParentLayout` 链接未接 `runWithDirtyGuard`) | **P1** | | 3 | 上一题的音频「慢失败」会把下一题误判为「听不到」并跳过,该词本轮消失且不记录:`skipCurrent` 闭包不绑定题目,`playWordAudio(...).catch(skipCurrent)` 迟到的 reject 作用在当前题上 | 1) 进入 `/spell/stage-03__AtTheSeaside`,Q1=boat 2) 打桩 `HTMLMediaElement.prototype.play` 对 boat 1.5s 后 reject、`speechSynthesis.speak` 触发 onerror(模拟 TTS 慢超时),其余词正常 3) 点「再听一次」后立刻拼对 boat → 进入 Q2=wanted(其音频正常) 4) 约 3.6s 后 Q2 显示「这个词暂时听不到,先换一个,不算错。」并跳到 Q3;localStorage 本轮无 wanted 记录 | 前端(`SpellingGame.tsx` 应校验触发失败的 wordId 是否仍为当前题) | **P1** | | 4 | 横屏手机视口(844×390)下答案槽(top 444)、字母块(562–636)、退一步(bottom 707)全部在视口外且页面不可滚动(`.child-layout` `height:100vh;overflow:hidden`,`.spelling-page` 无内部滚动),孩子看不到任何字母块;竖屏 390×844 与 1024×768 正常 | `Emulation 844×390` 打开 `/spell/stage-03__AtTheSeaside`,滚轮/`scrollTo` 均无效 | 前端(与现有 Learn 页同源限制,拼字页应自带 `overflow-y:auto` 或 `flex:1;min-height:0`) | P2 | | 5 | dev 模式下开局约 2s 内题目和字母块被整体替换、连续播放两个不同词的音频(如 boat→shell):StrictMode 双挂载使 `load()` 跑两次(两次 GET key-words),两次 `setRound` 各自组题,第一次的音频已开始播放;生产构建不受影响,但 `load` 缺少 ChildBookReader 那样的 `alive` 过期守卫 | 进入 `/spell/:id` 后立即抓快照,再等 2.5s 再抓:字母块集合不同;`performance` 中 key-words 请求两条 | 前端 | P2 | | 6 | 全对结果页与空题库页的唯一动作「完成,回书架」/「回书架」是透明文字按钮(`.spelling-secondary`),未按 30-uiux「只突出完成,回书架」做主按钮 | 复练轮全对;或直达 `/spell/stage-03__AtThePool` | 前端 | P2 | | 7 | 家长「最近拼错的词(本设备)」卡片级别显示原始 `stage-03`,校对页同位置显示「第3级」 | `/parent` 有拼错记录时查看 | 前端 | P2 | | 8 | 校对页切到「重点词句」页签后,头部「内容页 1/17 · 页码 2 ← →」翻页器仍显示且可点击,与页签内容无关 | `/parent/review/:id?tab=key-words` | 前端 | P2 | | 9 | 删除列表中的词后,添加框下方旧的错误提示(如「这个单词已经在列表里了」)不清除 | 输入 Want(已有 want)被拒 → 删除 want → 提示仍在 | 前端 | P2 | | 10 | 写入失败 500 的 `detail` 原文包含服务器绝对路径(`E:\nginx-1.8.0\html\data\book-key-words\...`) | 让 `stage-03/QaSpell500.json` 成为目录后 PUT | 后端 | P2 | 统计:P0 1(前端 1)、P1 2(前端 2)、P2 7(前端 6、后端 1)。 ### 边界与回归记录 - 接口契约脚本 36 项全过:空文档 200 不落盘;normalized 服务端重算、悬空 `sentence_id` 置空、id/时间戳补齐、二次保存保留 id/created_at、其他书隔离;422(多词/撇号/连字符/数字/非 ASCII/空词/重复/空句)逐条原因且文件不改写;Pydantic 类型错误 422;目录占位 500 无残留 tmp;损坏 JSON GET 500;OpenAPI 含 GET/PUT。`%2E%2E` 路径穿越被 Nginx/uvicorn 规范化拦下。 - 7.1 端到端(经 `http://127.0.0.1/`):家长录 wanted/shell/boat + 1 句保存 → 孩子读完 At the Seaside → 6 词检测 → 「玩拼字」→ 首题 wantid 改对 → 结果「自己拼对 2 个」→ 「再练一次」1 题 → 仪表盘看到 wanted。孩子可见文本无 `Quiz/Learn/M3/spelling`。(注:家长侧经深链进入,见 Bug #1) - 7.2 回归:`/`、`/learn/:id`、`/quiz/:id` 底栏「看书/拼读/闯关」均在;`/book/:id/read` 与 `/spell/:id` 无底栏;无重点词的书完成卡与改动前一致(两按钮同样式);`/parent/review/:id` 文本校对页签的句子/建议/录音片段/波形正常;`npm run build` 通过(tsc + vite);`python -m compileall app` 通过,`/api/health` 200。 - 读取失败:拦截 key-words 后 `/spell` 显示「刚才没准备好 / 再试一次 / 回书架」,解除后重试进入游戏;同样拦截下阅读页正常加载并完成检测,完成卡回退为两按钮。 - 回合快照:进行中把配置从 3 词改成 8 词,当前回合仍 3 题并正常完成;下一轮才读到 8 词。 - 移动端:竖屏 390×844 字母块 56×58、再听一次 322×68、退一步底边 729 < 844,无横向溢出;家长面板单列 318px 无溢出(操作按钮 46×36,成人侧可接受);横屏 844×390 见 Bug #4。 - 大人侧「试听」触发 `playWordAudio` 本地音频候选链。 - 观察(非 bug,请验收留意):「再练一次」轮会再次调用 `recordSpellingResult`,产生一条新的首次记录(wanted correctCount 0→1),首次口径按"每轮"而非"每词每天"统计,spec 未禁止但会影响「测验」解读。 ### 测不到的 - 严格自动播放策略浏览器(桌面 Chrome/iOS Safari)下直接打开或刷新 `/spell/:id`(无用户手势):`play()`/`speak()` 会被拒,代码把它与"音频不可用"同等处理 → 全部题目被跳过并直接出结果页。本环境(Cursor 内嵌浏览器,`navigator.userActivation.hasBeenActive=false` 仍可播)未复现,需真机验证;建议对 NotAllowedError 单独提示「点一下开始听」而不是跳题。 - 真实 TTS 网络超时下 Bug #3 的自然复现率未测(用打桩复现)。 - 书架长按🐻的真实触摸长按(用 PointerEvent 模拟 900ms 完成)。 ### 数据副作用与恢复 - `docs/data/book-key-words/stage-03/AtTheSeaside.json`:测试前**不存在**;测完保留示例 wanted(关联句「We wanted an ice cream.」)/ shell / boat,均启用。临时书 `QaSpellTest/QaSpellOther/QaSpell500/QaSpellBad` 已清理,目录下仅此一文件。 - `docs/data/reading-records/default.json` 新增 3 条 At the Seaside 阅读记录(11:30、11:44、11:45 UTC)来自本轮读完流程,未删除。 - 测试浏览器 localStorage `easy-study:phonics:book:stage-03__AtTheSeaside` 在测试前清空过一次(其中原有前端自测残留),现含本轮拼字记录,供仪表盘验收查看。 ## 历史轮次 (无)