# Easy Study — 课程练习站架构(v0.2) 技术栈:React (Vite) 前端 · Python (FastAPI) 后端 · SQLite · 本地音频/音效文件 目标:1:1 对齐探趣岛学习链路「课程广场 → 课程详情 → `/app/game` 练习」,持久化课程/课节/句表行(词+句)与音频,支持多模式练习与快捷键。管理端延后(P2)。 对照材料:`docs/学习页1对1复刻报告.md`、`tanqudao-capture/deep-20261011/`。 ;交互设计:`docs/练习页交互与功能设计.md` ## 1. 系统分层 ``` React (Vite) /courses 广场 · /courses/:id 详情 · /game 练习(多模式) │ REST JSON + 静态 /media + /tts 代理或本地 Python FastAPI courses · lessons · sheet-rows · media · practice · sfx │ SQLite (data/app.db) media/audio/{tts,sfx,covers,course-images}/ ``` 原则:内容进库;音频以文件为主、库存路径;练习模式先读 sheet;不做会员支付。 ## 2. 前端路由(对齐真实站点) | 路由 | 探趣岛 | 说明 | |------|--------|------| | `/courses` | `/app/courses` | 分类 Tab + 卡片网格 | | `/courses/:courseId` | `/app/courses/:id` | 课节网格、继续学习、收藏 | | `/game` | `/app/game` | 练习主界面(query: courseId, lessonId, mode) | | (可选)`/game?mode=` | 同左 | split / whole / dictation / cn2en / typing / puzzle | 全局壳:左侧 nav(可配置隐藏于 game)、顶栏用户区。 ## 3. 领域模型(对齐 API 真字段) ### 3.1 课程列表/详情(已抓) `GET /api/courses` → `{ items, total, categories:[{key,name}] }` Course 字段:`id, title, category, lessonsCount, learnersCount, visitorsCount, hidden, cover, landscapeCover, editorName, editorColor, heatLevel` `GET /api/courses/:id` 另含 `lessons:[{ id, title, durationSec, hidden }]` `title` 常为 `英文\n中文` 双行。 ### 3.2 课节句表(核心新增,已抓) `GET /api/lesson-sheet?courseId=&lessonId=&practice=split|...` ``` columns: content, translation, cardCut, annotations, voiceUrl, imageUrl row: { id, content, translation, wordTranslation, ipa, pos, syntax, cardCut, annotations, voiceUrl, // "/tts/....mp3" imageUrl, // "/course-images/....webp" 可空 rowType } ``` 语义: - **词行**:短 `content`(如 `it` / `brush`),有 ipa/pos/syntax/wordTranslation/voiceUrl - **句行**:多词 `content`,常有 `cardCut`(`/A/+/B/`)、`imageUrl`、整句 `voiceUrl` - 一课可 ~几十行(L1=62),练习进度 `current/total` 对应该课题量(可能按模式过滤后的题数,如 17/19) ### 3.3 SQLite 表(v0.2) - **courses**:id, title, category, cover_path, landscape_cover_path, editor_name, editor_color, heat_level, lessons_count, sort_order, created_at - **lessons**:id, course_id, title, title_zh, sort_order, duration_sec, hidden - **sheet_rows**:id, lesson_id, sort_order, content, translation, word_translation, ipa, pos, syntax, card_cut, annotations, voice_path, image_path, row_type - 可选生成列:`is_sentence`(content 含空格或 card_cut 非空) - **words**(可选词典投影):从 sheet_rows 去重 lemma → phonetic/meaning/audio - **practice_progress**:user_key(本地), course_id, lesson_id, mode, current, total, updated_at - **sfx**:kind(typing|nav|correct|wrong|complete), name, path, is_default - **practice_sessions / wrong_sentences**:后续 索引:lessons(course_id,sort_order)、sheet_rows(lesson_id,sort_order)、words(lemma UNIQUE) ## 4. API(学习端) | 方法 | 路径 | 说明 | |------|------|------| | GET | /api/courses | 列表 + categories | | GET | /api/courses/{id} | 详情 + lessons | | GET | /api/lesson-sheet | query: courseId, lessonId, practice → rows | | GET | /api/practice/progress | courseId, lessonId → current/total/mode | | POST | /api/practice/enter | 进入练习 | | POST | /api/practice/progress | 上报进度 | | POST | /api/practice/add-time | 累计时长 | | POST | /api/review/wrong-sentences | 错句本 | | GET | /api/sound-effects | 五类音效 URL | | GET | /media/... | 静态封面/图/tts/sfx | | GET | /api/health | 探活 | 管理端(P2):CRUD + 上传/TTS。 ## 5. 练习交互模型(v0.2 重点) ### 5.1 模式枚举 | mode | UI | 输入 | 数据 | |------|-----|------|------| | `split` 拆句练习 | 多 `word-input` | 逐空填词 | lesson-sheet practice=split | | `whole` 整句练习 | textarea | 整句 | 句行 content | | `dictation` 听写 | 音频 + 输入 | 听写 | voiceUrl 优先 | | `cn2en` 中译英 | 中文提示 | 英文 | translation → content | | `typing` 打字练习 | `typing-practice-input` | 逐字 | content | | `puzzle` 拼图 | 词块 | 拼序 | cardCut / 分词 | 顶栏 **切换模式** 打开模式面板;变体 pill 切换拆句/整句。 ### 5.2 快捷键(必须实现,与底栏芯片一致) | 键 | 行为 | |----|------| | **Space** | **显示/隐藏答案**(揭晓后芯片文案变「隐藏答案」) | | **↓ / ↑** | 答案 | | **Ctrl+A** | 朗读(播 voiceUrl) | | **Ctrl+Q** | 不熟悉(可选写入标记) | | **Enter** | 提交(部分模式 Space 亦提交,注意与显隐答案的模式差异) | | **Shift+← / →** | 切题(上一/下一) | | **Ctrl+;** | 再来一次(清空当前题) | | 按钮 上一题 / 下一题 | 同切题 | **填空规则**:禁止模型翻译猜测;产品内「提示」= 揭晓 sheet 中 `content`,用户/自动化均抄写揭晓文本再提交。 ### 5.3 提交与反馈 1. 校验输入 vs 期望 `content`(可忽略首尾标点/大小写策略可配置)。 2. 对:播 sfx.correct + `correct-fx` 动效 + progress.current++ + POST progress。 3. 错:播 sfx.wrong + 登记 wrong-sentences + 允许 Ctrl+; 重试。 4. 完课:sfx.complete。 5. 计时:定时 POST add-time。 ### 5.4 播放器 `useAudioQueue`:词音频、整句音频、朗读快捷键;无整句文件时按 cardCut/词序拼接。 ## 6. 音频与媒体策略 1. TTS:`media/tts/...` ← 导入时下载 `/tts/...` 2. SFX:`media/sfx/{typing,nav,correct,wrong,complete}/` ← `/api/sfx/...` 3. 封面/课图:`media/covers/`、`media/course-images/` 4. 练习:有 voice_path 则播文件;否则 fallback TTS 生成(管理端) ## 7. 仓库目录 ``` easy-study/ apps/web/ # React + Vite apps/api/ # FastAPI + SQLite data/app.db media/{tts,sfx,covers,course-images}/ docs/ARCHITECTURE.md docs/学习页1对1复刻报告.md tanqudao-capture/ # 抓包(含 deep-20261011) scripts/import_from_capture.py ``` ## 8. 分期 - **P0**:表结构(含 sheet_rows)+ 三路由 + 拆句/整句 + Space 揭晓填空 + 快捷键底栏 + 本地音频播放 - **P1**:听写 / 中译英 / 打字 / 拼图 + 音效 + 错句本 + 进度持久化 - **P2**:管理端 CRUD + TTS 批量 - **P3**:从 `deep-20261011/03-api-data` 一键导入脚本 ## 9. 非目标 登录会员体系、支付、排行榜、与探趣岛账号互通、教辅/发帖。 ## 10. v0.1 → v0.2 变更摘要 - 路由改为对齐 `/courses` + `/game`。 - 引入 **sheet_rows** 与真实 lesson-sheet 字段(ipa/pos/syntax/cardCut/voiceUrl/imageUrl)。 - 明确多模式与 **Space 揭晓答案** 工作流。 - 补充 sound-effects、progress/enter/add-time/wrong-sentences API。 - 课程字段补 editorColor、heatLevel、landscapeCover。