# 05 系统总体设计 > 所属:`tasks/0913-EnglishStudyAnalysis/`(阶段 1 文档) > 版本:v1.0(2026-09-17) > 上游:`01`-`04`(画像约束、课程数据、每日卡片、状态机与算法) > 下游:三条 product-pipeline(`daily-plan-engine`、`speaking-coach-agent`、`listening-clips-and-starters`)的 `00-request.md` 背景补充;`deploy/hermes/`、`deploy/nginx/` > 约定:本文只定「契约」与「边界」,页面细节与代码结构由流水线角色在各自文档中细化,但不得改变本文的数据契约与接口路径。 --- ## 1. 范围与设计原则 **范围**:在现有 Easy Study(FastAPI + React/Vite + Nginx,JSON 存储)之上新增 5 个后端模块、4 个孩子端页面/入口、1 个家长报告页、1 个 Hermes skill + 5 个 cron、1 个火山语音评分服务。 **原则**: 1. **服务端是学习进度的唯一真源**:所有学习结果以「事件」进服务端,浏览器 localStorage 只作离线缓冲。 2. **微信是唤起通道,不是界面**:Hermes 只转发后端渲染好的文案;孩子看到的数字、词、链接都来自后端,模型不得改数字。 3. **确定性优先,LLM 只做措辞**:计划生成、判定、评分对齐全部确定性;LLM 仅用于反馈润色与看图鼓励,且有模板兜底。 4. **局域网内闭环**:除火山 ASR/TTS/LLM 调用与微信消息外,不出局域网;孩子音频只存本机。 5. **与现有约定一致**:数据继续放 `docs/data/`(运行时数据子目录 `learning/` 建议 gitignore),后端路由前缀 `/api/*`,对外经 Nginx `/estudy/api/*`,前端路由沿用 `basename=/estudy`。 ## 2. 部署拓扑 ```mermaid flowchart TB subgraph lan [家庭局域网] subgraph pc [本机 192.168.11.157] api["FastAPI :8120 — plan/events/srs/speech/reports/curriculum"] data[("docs/data — curriculum + learning")] media[("E:/nginx-1.8.0/html — images audio clips speech")] api --- data api --- media end subgraph nas [NAS 192.168.11.94] nginx["Nginx :80/:443 — /estudy 前端静态 + 反代 api"] end subgraph hermesHost [Hermes 主机 Linux] hermes["hermes gateway — cron + weixin adapter + skill"] end ipad["iPad — 微信 + Safari PWA"] phone[家长手机 微信] end subgraph cloud [公网] ilink[微信 iLink Bot API] volc["火山:豆包语音 ASR/TTS、方舟 LLM api/v3、方舟 Agent Plan api/plan"] end ipad -->|https /estudy| nginx --> api phone --> ilink ipad --> ilink hermes <-->|long poll| ilink hermes -->|http /api 带 token| api hermes -->|Agent Plan| volc api -->|ASR TTS LLM| volc ``` 组件职责: - **FastAPI(本机)**:全部业务逻辑与数据;定时任务用 APScheduler(04:00 生成计划、23:30 生成日报、周六 19:50 周报、月末月报),不依赖 Hermes 存在。 - **Nginx(NAS)**:`/estudy/` 静态前端、`/estudy/api/` 反代本机 8120、`/estudy/audio|images|clips` 直出;新增 443 TLS(§9)。 - **Hermes(Linux 主机)**:只做「定时拉文案 → 发微信」「收消息 → 调后端」;不持有学习数据。 - **火山**:豆包语音 ASR/TTS(openspeech)、方舟标准 API(后端 LLM)、方舟 Agent Plan(Hermes 模型)。 ## 3. 数据模型 ### 3.1 文件布局 ``` docs/data/ ├── curriculum/ # 课程数据(git 跟踪) │ ├── phonics-units.json │ ├── hf-words.json │ ├── starters-words.json │ ├── ort-sequence.json │ ├── clips.json │ ├── qa-bank.json │ └── letters.json ├── assessment/ │ └── baseline-v1.json # 评测题库(01 §3.2) └── learning/ # 运行时数据(建议 .gitignore,夜间 zip 备份到 NAS) └── {child_id}/ ├── profile.json # 04 §13 ├── srs.json # 全部学习项状态 ├── plans/YYYY-MM-DD.json # 每日计划 ├── events/YYYY-MM.jsonl # 事件流(追加) ├── days.json # 请假、streak、星星累计 └── reports/ ├── daily/YYYY-MM-DD.json ├── weekly/YYYY-Www.json └── assessment/YYYY-MM.{json,md} E:/nginx-1.8.0/html/audio/ ├── clips/{series}/S{ss}E{ee}/{clipId}.mp3 # 今日一句音频片段 ├── speech/{child_id}/YYYY-MM-DD/{eventId}.{m4a|webm|wav} # 孩子录音(90 天滚动删除) ├── tts-feedback/{hash}.mp3 # 反馈 TTS 缓存 └── cambridge/starters/{set}/… # 真题音频 ``` 写入模式沿用 `bookshelf/backend/app/routers/records.py`:进程内 `threading.Lock` + `*.tmp` 写入后 `os.replace`;`events` 用 JSONL 追加(每行一个事件,写前加锁)。所有时间为 ISO 8601 带 `+08:00`。 ### 3.2 `srs.json` ```json { "version": 1, "updatedAt": "2026-09-20T20:31:00+08:00", "items": { "word:cake": { "kind": "word", "subkind": "phonics", "text": "cake", "status": "learning", "enteredAt": "2026-09-18T19:35:00+08:00", "dueAt": "2026-09-19T00:00:00+08:00", "extendCount": 0, "correctCount": 1, "passCount": 1, "wrongCount": 1, "hastyCount": 0, "noSignalCount": 0, "confusionWeight": 0, "correctDays": ["2026-09-18"], "lastResult": "correct", "lastAt": "2026-09-18T19:36:10+08:00", "sources": [{"type": "unit", "ref": "W9"}, {"type": "reader", "ref": "stage-03__TheEggHunt", "at": "2026-09-16T19:40:00+08:00"}], "history": [{"at": "2026-09-18T19:36:10+08:00", "result": "correct", "source": "phonics", "score": null}] }, "phoneme:eɪ": {"kind": "phoneme", "text": "eɪ", "graphemes": ["a_e", "ai", "ay"], "status": "weekly", "...": "..."}, "pattern:go-went": {"kind": "pattern", "text": "go/went", "status": "new"} } } ``` ### 3.3 `plans/YYYY-MM-DD.json` ```json { "date": "2026-09-21", "dayType": "weekday", "generatedAt": "2026-09-21T04:00:02+08:00", "version": 1, "week": {"id": "W1", "rule": "短 a", "episode": "peppa-S01E01"}, "cards": [ {"id": "c1", "type": "phonics", "title": "拼一拼", "icon": "🔤", "minutes": 3, "items": [{"itemId": "word:cat", "role": "new"}, {"itemId": "word:hat", "role": "new"}, {"itemId": "word:map", "role": "review"}, {"itemId": "word:bag", "role": "review"}], "deeplink": "/learn/stage-03__NobodyWantedToPlay?plan=2026-09-21:c1&words=cat,hat,map,bag", "status": "pending", "carriedOver": false, "completedAt": null, "stars": 1}, {"id": "c2", "type": "listening", "title": "听一听", "icon": "👂", "minutes": 4, "clipId": "peppa-S01E01-003", "deeplink": "/listen/peppa-S01E01-003?plan=2026-09-21:c2", "status": "pending"}, {"id": "c3", "type": "reading", "title": "读一读", "icon": "📖", "minutes": 6, "bookId": "stage-03__NobodyWantedToPlay", "mode": "listen", "deeplink": "/book/stage-03__NobodyWantedToPlay/read?plan=2026-09-21:c3&mode=listen", "status": "pending"}, {"id": "c4", "type": "speaking", "title": "说一说", "icon": "🎤", "minutes": 3, "items": [{"itemId": "word:cat", "refText": "cat"}, {"itemId": "word:hat", "refText": "hat"}, {"itemId": "word:map", "refText": "map"}, {"itemId": "sentence:peppa-S01E01-003", "refText": "I love muddy puddles."}], "deeplink": "/speak/2026-09-21:c4", "requiresMic": true, "status": "pending"}, {"id": "c5", "type": "writing", "title": "写一写", "icon": "✏️", "minutes": 2, "letters": "Bb", "words": ["we", "the"], "deeplink": null, "status": "pending"}, {"id": "c6", "type": "quiz", "title": "闯关", "icon": "🏆", "minutes": 2, "questions": [{"itemId": "phoneme:æ", "qtype": "listen_pick"}, {"itemId": "word:they", "qtype": "sentence_choice", "patternId": "they-them"}], "deeplink": "/quiz/stage-03__NobodyWantedToPlay?plan=2026-09-21:c6&mode=review", "status": "pending"} ], "summary": {"totalStars": 8, "earnedStars": 0, "completedCards": 0, "streak": 4}, "wechat": {"morning": "…渲染好的文案…", "nudge": "…", "evening": null} } ``` `planItemId = "{date}:{cardId}"`,页面通过 `?plan=` 带回,事件用它关联。 ### 3.4 事件 `events/YYYY-MM.jsonl`(每行一条) ```json {"id": "evt_01J8…", "childId": "default", "type": "phonics", "at": "2026-09-21T19:33:12+08:00", "planItemId": "2026-09-21:c1", "itemId": "word:cat", "payload": {"stage": "listen_pick", "firstAttemptCorrect": true, "attempts": 1, "responseMs": 2400, "hasty": false}, "client": {"ua": "iPad Safari", "app": "1.4.0"}, "migrated": false} ``` `type` 枚举与 payload 约定: | type | payload 必填 | 说明 | | --- | --- | --- | | `phonics` | stage(listen_pick/scramble/spell)、firstAttemptCorrect、attempts、responseMs | Learn 三连关每词每关一条 | | `quiz` | qtype、correct、firstAttemptCorrect、attempts、responseMs、hasty、chosen、answer | 每题一条;结束另发 `quiz_summary` | | `spelling` | firstAttemptCorrect、mistakeCount、completedAfterRetry | SpellingGame 沿用现有字段 | | `reading` | bookId、mode(listen/read/review)、pagesRead、totalPages、completed、durationSec、unknownWords[] | 兼容 `/api/records`;records 接口内部转发一条 reading 事件 | | `listening` | clipId、playCount、sentencePlayCount、durationSec、free | 听一听 | | `speaking` | refText、itemKind(word/sentence/qa)、attempt、score、wordScores[]、weakPhonemes[]、asrText、audioPath、noSignal | 每次录音一条 | | `writing_checkin` | letters、words、photo(bool)、source(wechat/parent) | Hermes 或家长页 | | `test` | testId、module、correct、firstAttempt、responseMs、score?、judgedBy? | 基线/周测/月测/Starters | | `card_complete` / `day_complete` | cardId / stars、streak | 服务端聚合后写入(客户端只做乐观显示) | | `card_skip` | cardId、reason、source(parent/hermes) | skip API 服务端写入(2026-09-19 裁决新增) | | `day_off` | reason、source | Hermes 或家长页 | | `sync` | migratedItems、migratedEvents | localStorage 迁移 | 事件写入后同步执行 SRS 更新(04 §3-§5),返回 `srsUpdates` 供前端即时反馈。 ## 4. API 契约 所有接口前缀 `/api`(经 Nginx 为 `/estudy/api`)。`child_id` 默认 `default`。写接口从 Hermes 调用时必须带 `X-Easy-Token: `;iPad 前端同源调用不需要(局域网信任,与现有接口一致)。错误统一 `{detail}`。 ### 4.1 plan | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/plan/today?child_id&date=` | 返回 §3.3 结构;`date` 缺省为今天(Asia/Shanghai);不存在则即时生成 | | POST | `/api/plan/generate?child_id&date=&force=false` | 幂等生成;`force=true` 重新生成(只允许当日未产生事件时) | | GET | `/api/plan/today/wechat-text?child_id&kind=morning\|nudge\|saturday` | `text/plain; charset=utf-8`;`nudge` 在全部完成或 day_off 时返回 **空体 + 200**(Hermes no-agent 静默) | | POST | `/api/plan/{date}/cards/{cardId}/skip` | 家长跳过,body `{reason}` | | POST | `/api/plan/{date}/cards/{cardId}/complete` | 无页面卡片(写一写)手动完成;服务端同时发 `card_complete` 事件 | ### 4.2 events | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/api/events` | body 为单条或数组(前端离线队列批量重放,≤ 200 条);事件 `id` 由客户端生成(`evt_` + ULID/UUID);服务端按 `(childId, id)` 幂等去重,重复提交返回原 `ids` 与当前卡状态、不再次更新 SRS/星星/报告;返回 `{ok, ids[], srsUpdates: [{itemId, from, to, dueAt}], card: {id, status, stars}}` | | GET | `/api/events?child_id&from&to&type&planItemId&limit=500` | 查询 | ### 4.3 srs | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/srs/due?child_id&date&kinds=word,phoneme&limit=20` | 到期项(含 dueScore) | | GET | `/api/srs/items?child_id&status=learning&kind=word` | 列表 | | POST | `/api/srs/sync` | body `{states: [BookStudyState…], lastBookId}`(前端原样上传 `easy-study:phonics:book:*`);服务端按 04 §11 映射合并;返回 `{migratedItems, migratedEvents}` | | POST | `/api/srs/items/{itemId}/reset` | 家长重置某项为 `new` | ### 4.4 speech | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/api/speech/assess` | `multipart/form-data`:`audio`(m4a/webm/wav ≤ 15s)、`ref_text`、`item_kind`(word/sentence/qa)、`item_id`、`plan_item_id`、`attempt`(1-3)、`qa_id?`;返回 §7.5 `AssessResult`,并已写入 `speaking` 事件 | | POST | `/api/speech/tts` | body `{text, voice: "coach", lang: "zh-en"}` → `{url}`(缓存命中直接返回) | | GET | `/api/speech/health` | 检查火山凭证与 ffmpeg | ### 4.5 reports | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/reports/daily?child_id&date&format=json\|wechat` | 日报(星星、完成卡、亮点 1-2 条、明日预告) | | GET | `/api/reports/weekly?child_id&week=2026-W38&format=` | 周报(03 §6 模板字段) | | GET | `/api/reports/monthly?child_id&month=2026-09&format=` | 月报 = 评测报告 + 月度指标 | | GET | `/api/reports/assessment?child_id&month=` | 01 §3.5 JSON | `format=wechat` 返回 `text/plain`,由后端 `wechat_templates.py` 渲染;Hermes agent 模式允许「润色语气」但文案中所有数字、词、链接必须原样保留(skill 里写死这条规则)。 ### 4.6 curriculum / tests / days | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/curriculum/week?child_id&date=` | 本周规则、词池、集数、5 句、字母游标 | | GET | `/api/curriculum/clips/{clipId}` | 单句详情(含音频 URL、起止、中文、词) | | GET | `/api/curriculum/units` / `/hf-words` / `/starters-words?coverage=1` | 静态课程数据(覆盖率带事件统计) | | POST | `/api/tests/starters` | `{date, set, parts: [{part: "L1", correct: 4, total: 5}], notes}` → 事件 `test(testId=starters-{date})` | | POST | `/api/tests/judge` | 家长判定 `{testId, module, itemId, result: correct\|pass\|wrong}` | | POST | `/api/days/{date}/off` | `{reason, source}`;当日 plan 标 `dayType=day_off`,nudge/evening 静默 | | GET | `/api/days/streak?child_id` | `{streak, graceLeft, starsTotal}` | ### 4.7 现有接口的调整 - `POST /api/records`:保持兼容,是阅读结果的**唯一提交入口**(页面不得再单独上报 `reading` 事件);新增可选字段 `plan_item_id`、`mode`、`event_id`,服务端只转成一条 `reading` 事件并按 `event_id` 幂等(2026-09-19 裁决)。 - `/api/books/` 书架三条引导改由前端读 `/api/plan/today` 派生,不改接口。 ## 5. 前端设计 ### 5.1 路由与入口 | 路由 | 页面 | 布局 | 说明 | | --- | --- | --- | --- | | `/today` | Today | 儿童布局 + 底栏 | 微信链接直达;书架顶部新增「今天」入口卡 | | `/listen/:clipId` | Listen | 沉浸(无底栏) | 今日一句 | | `/speak/:planItemId` | Speak | 沉浸 + PWA | 口语教练;微信 UA 显示引导页 | | `/learn/:id` `/quiz/:id` `/spell/:id` `/book/:id/read` | 现有 | — | 接受 `?plan=`;结束时上报事件并返回 `/today` | | `/parent/report` | ParentReport | 家长布局 | 周报/月报/评测报告、Starters 录分、卡片跳过、换书 | | `/parent/plan` | ParentPlan | 家长布局 | 查看/调整 profile(时段、限额、阈值)、课程游标 | 底栏「看书 / 拼读 / 闯关」保留;「今天」作为书架首屏顶部大卡 + 微信深链,不加第四个底栏项(避免与既有信息架构冲突,由 UI/UX 角色最终定)。 ### 5.2 今天页(孩子) - 顶部:昵称 + 今天星星 `⭐ 3/8` + 连续天数小火苗;勋章条。 - 6 张竖排大卡(≥ 88px 高):图标 + 名字 + 一行内容(书名 / 词 / 字母)+ 状态角标(待做 / 昨天没做完 / 完成 ✓)。 - 点卡 → 深链;返回今天页时 `GET /api/plan/today` 刷新;卡完成时卡片翻绿 + 小音效。 - 6 卡全完成:满屏庆祝 + 「今天 8 颗星」+ 「明天见」。 - 周日 / 请假日:只显示「今天休息,想玩就点」→ 自由闯关(不计划)。 - 后端不可达:读取 `localStorage['easy-study:plan-cache']` 显示昨日/缓存计划,提示「小助手在休息」;事件进 `easy-study:event-queue` 队列,恢复后批量 `POST /api/events`。 ### 5.3 深链协议 - 所有卡片链接形如 `{publicBaseUrl}{route}?plan={planItemId}&…`。 - 页面在完成条件达成时 `POST /api/events`(含 `planItemId`),随后 `navigate('/today')`;若从书架进入(无 `plan`),行为与现在一致但仍上报事件(不关联卡)。 - 现有 `bookStudy.ts` 的 `recordQuizAnswer/saveQuizAttempt/recordSpellingResult/addWordsToStudy` 改为「写本地缓存 + 发事件」,掌握度判定移到服务端;`peekTodayWords/peekReviewTask` 退役。 ### 5.4 听一听 - 大播放键播放场景片段(`clips.json` 的 `sceneStart-sceneEnd`),进度条可见;下方今日一句卡:英文大字、中文小字、截图;「再听一遍」计数到 3 变绿。 - 音频来自 `/estudy/audio/clips/...` 切好的 mp3(不在前端做 media fragment 截取,避免 iOS Safari 的兼容问题)。 - 视频版(M4 起可选):`