# 用户需求 - 日期:2026-09-06 - 入口 URL(体验/测试用):http://127.0.0.1/(easy-study 默认;Nginx → 前端 5120 + 后端 8120) - 技术栈:easy-study 默认(FastAPI + React19/TS/antd-mobile/zustand,JSON 文件存储,无数据库) - 来源:`bookshelf/tasks/00_scrum-chat.md` v0.4 条目(第 37–44 行) - **用户明确要求先确认设计再开发**:阶段 4 体验审查通过后必须停在「原型确认停点」,把设计方案 + 原型交用户确认;用户确认前不进入阶段 5/6/7/8。 ## 用户原话 > v0.4 (2026-09-06) 增加单词默写游戏 > > - 基于已有绘本可以输入并记录当前绘本重点词句 > - 儿童端绘本阅读完成后,可以进度单词默写游戏 > - 默写游戏从重点词句中随机选择 > - 单词打乱字母顺序,并提供1-2个干扰项供选择,如 wanted 随机打乱后如 t n a e d w 和干扰项 o i (want 中o 和a 同属于元音wont 可以达到want的干扰效果,wanted 中i和e也同属于元音 wantid 和wanted 也可以实现干扰效果) 孩子 从中依次点击字母 实现单词拼写,避免了 26字母虚拟键盘对6岁孩子造成输入压力。同时可以测验孩子拼写能力 > > 针对这个帮我进行设计,并添加到bookshelf 合适的功能区 > (本轮对话)根据这段进行功能设计,由我进行确认后开始开发 ## 背景补充(主 agent 掌握的上下文) ### 产品与用户 - 产品定位、儿童/家长画像、闭环、完成标准见 `bookshelf/tasks/product-loop-state.md`;孩子约 6 岁、约 300 词、字母认识但不熟、b/p/d/q 易混、不打字、需要大热区少文字;面向孩子的文案禁止 M3/Quiz/Learn 等黑话。 - 家长入口约定:书架长按小熊 🐻 → 出现「听故事 / 校对」切换 → 校对模式下出现「学习情况」→ `/parent`。家长功能不和孩子底栏抢位置。 - 孩子底栏只有:看书 / 拼读 / 闯关;阅读页沉浸无底栏。 - 孩子端改动完成后必须跑 `child-ux-tester`(AGENTS.md 约定),报告只在 `bookshelf/tasks/child-ux-report.md`。 ### 现有孩子端流程(`bookshelf/frontend/src/pages/child/`) - 书架 `Home.tsx`(`/`):「今天读这本」「这些词还要再练」「今天练这些词」三块引导 + 书格。 - 沉浸阅读 `ChildBookReader.tsx`(`/book/:id/read`):`phase` 为 `read` → 翻到最后一页立刻出现「🎉 读完啦!已记录本次阅读」+「读一读这些词」按钮 → `phase=test` 读后检测(抽 6 个词,会读/不会)→ 检测完成出现「去拼读 / 返回书架」。读完时调用 `recordsApi.create` 上报阅读记录(含 `unknown_words`)。顶栏有「拼读」按钮可中途去拼读页。 - 拼读页 `Learn.tsx`(`/learn/:id`):听音选字 → 乱序六宫格 → 按序点字母拼词 → 拆分块;已有「按顺序点字母,拼出这个词」的乱序瓷砖玩法(但只用词内字母、无干扰项,且以音素为单位)。 - 闯关页 `Quiz.tsx`(`/quiz/:id`):5 题,奇数题听音选字、偶数题选正确字母块拆分;结果写 localStorage。 - 路由 id 形如 `stage-03__AtTheSeaside`(`buildBookRouteId(stage, folder)`)。 ### 现有家长端(`bookshelf/frontend/src/pages/parent/`) - `/parent` `Dashboard.tsx`:阅读记录、待复习/薄弱词、最近闯关等汇总;有「回书架」。 - `/parent/review/:id` `BookTextReview.tsx`:文本校对(这一页的句子 / 校对建议 / 录音片段)。 - `/book/:id` `BookReader.tsx`:校对模式下的阅读器(大人改字、调时间轴)。 ### 数据与后端(`bookshelf/backend/app/`) - `routers/books.py`:绘本索引/结构化 JSON 读取;改字/删字/插字/页音频时间 PUT/POST,直接写 `book-structured` JSON。 - `routers/records.py`:阅读记录,按 `child_id` 一个 JSON 文件(`docs/data/reading-records/default.json`),线程锁 + 原子写(tmp + os.replace)。是新增「后端持久化小数据」的现成模板。 - `routers/words.py`:单词查询 `/api/words/lookup/{word}`(音素、字母-音素拆分、释义、音频候选)、TTS `/api/words/tts/{word}`。 - 路径配置集中在 `config.py`(`DATA_DIR`、`RECORDS_DIR` 等,可用环境变量覆盖)。 - 孩子的学习状态(每本书的词状态 new/learning/mastered、correctCount/wrongCount、quizAttempts)目前在 **浏览器 localStorage**(`bookStudy.ts`,键 `easy-study:phonics:book:`),不是后端。 - 单词发音:`playWordAudio(word)` 本地 mp3 → TTS → 浏览器 speechSynthesis 逐级回退;音素发音 `playPhoneme`。 ### 相关已实现的拼词能力(可复用,勿重复造) - `bookStudy.ts`:`shuffle`、`buildShuffledGraphemes`(乱序瓷砖)、`buildGraphemeChoices` / `GRAPHEME_CONFUSIONS`(b/p/d/q、sh/ch/th 等易混字母表)、`recordQuizAnswer`、`saveQuizAttempt`、`peekReviewTask`(错词再练排期)。 - `PhonicsBlocks.tsx`:可点的字母-音素拆分块。 - 样式:`PhonicsModule.css`(`.phonics-listen-choice` 等大按钮)、`ChildBookReader.css`。 ## 主 agent 的初步假设(角色们可质疑) 1. 「输入并记录当前绘本重点词句」是**大人(家长/老师)**的操作,孩子端只消费;录入入口应放在家长/校对侧(如 `/parent/review/:id`、校对模式阅读器 `/book/:id` 或家长中心),不出现在孩子界面。 2. 重点词句需要**后端持久化**(每本书一份 JSON,类似 `reading-records` 的读写方式),而不是只存 localStorage——因为它是「内容配置」,要跨浏览器/跨设备稳定,并让家长和孩子端看到同一份。 3. 「词句」= 单词 + 短句都允许录入;但 V1 的默写游戏只默写**单词**(含从句子里挑出的重点词),句子可作为提示语境(播放/显示)而非默写对象。 4. 干扰项规则:按用户举例,以**同类元音替换**(a/o/e/i/u)为主、辅以已有 `GRAPHEME_CONFUSIONS` 易混辅音;短词(≤4 字母)1 个干扰、长词 2 个;干扰字母不能与词中字母重复以致产生第二个合法拼法。 5. 交互:孩子从打乱的字母块中**依次点击**拼出单词,点过的字母块进入答案槽;支持撤回最后一个;点错即时反馈但不惩罚;能随时听单词发音;不出现 26 键键盘、不需要打字。 6. 默写入口:读完最后一页/读后检测完成后给「默写」入口(与现有「去拼读 / 返回书架」并列或替代其一),同时闯关/书架也可作为次要入口;一本书没有录入重点词时不显示默写入口或给孩子听得懂的空状态。 7. 结果记录:默写对/错写入孩子学习状态(复用 `recordQuizAnswer` 的 correct/wrong 或新增 source),家长在「学习情况」能看到默写情况(最少:哪些词默写错过)。 8. 本轮 V1 范围:家长录入重点词句 + 孩子读完后默写游戏 + 结果记录与家长可见。句子级默写、每日复习排期整合、多孩子档案属于 V2。 ## 范围猜测 - **前端(孩子端)**:新默写游戏页/模块(路由如 `/spell/:id`,或作为 Quiz 的一种题型/独立页——由产品/UX 决定);`ChildBookReader.tsx` 读完/检测完成态加入口;可能 `Home.tsx` 加引导块。 - **前端(家长端)**:重点词句录入/管理面板(在 `BookTextReview.tsx` 或 `BookReader.tsx` 校对模式或 `Dashboard.tsx`),支持增删、从绘本词表点选。 - **后端/数据**:新增重点词句读写接口(如 `GET/PUT /api/books/{stage}/{book_folder}/key-words`)与 JSON 存储目录(`config.py` 加路径);默写结果是否入后端由产品设计决定(当前学习状态在 localStorage)。 - 不涉及:`251228-words/` 旧模块、OCR/音频流水线工具。