# 前端开发记录 - 日期 / 轮次:2026-09-19 / 第 1 轮 - 输入:`00-request.md`(含主 agent 裁决 #1–#10)、`10-analysis.md`、`20-product.md`、`30-uiux.md`@第 3 轮、`prototype/`、`40-review.md`、`50-backend.md`、openspec `daily-plan-engine`(proposal/design/specs/tasks 7.x–11.x);契约来源 `05` §5 前端设计、`04` §11 迁移、`03` §2 六卡、`01` §2.3 C1 - 应用的历史教训:无 - 结论:可进测试。`npx tsc -b --noEmit` 与 `npm run build` 已通过;Nginx `http://127.0.0.1/estudy/today` 已实走五卡落点、写一写 2 秒门禁、家长跳卡同步、深链打开、书架入口、一次性 `srs/sync`。完整四词三关收星、听满 45 秒、闯关仓促/离线重放、周日休息态留给 QA(11.2)与 child-ux-tester(11.4,主 agent 调用)。 ## 上游核对 | 上游编号 | 本步落点 | | --- | --- | | 00 裁决 #1 / 03 §2 / 06 §2 | V1 只渲染 `c1/c2/c3/c5/c6`,滤掉 `c4`;星星分母取 `summary.totalStars`(今日 7) | | 00 裁决 #3 / 05 §4.7 / 50-backend records | 阅读只走 `recordsApi.create`(`plan_item_id/mode/event_id`),不再 `POST /events` 写 reading | | 00 裁决 #4 | `newEventId()` = `evt_` + UUID;阅读 `event_id` 按 `planItemId` 落 localStorage,刷新重提幂等 | | 00 裁决 #5 / 8.1 | 卡 `done` 只认服务端;`StarCollect` / `waitForCardDone`,不本地改 done | | 00 裁决 #9 / 7.7 / 10-analysis R2 | 书架三条提示只展示计划里存在的映射;无任务走休息态 | | 00 裁决 #10 / 40-review P0 / 30 F8 | 写一写短按无完成钮;长按 2 秒 → `unlockAdultTools` → `completeCard` | | 01 §2.3 C1 | 孩子句 ≤12 字;热区 ≥44px;DOM 无 plan/SRS/event/Quiz/Learn 黑话 | | 04 §11 / 9.2 | 首次 `/today` 调 `srsApi.sync`,成功写 `easy-study:synced=1` | | 05 §5.1–5.2 / F2–F4 | 路由 `/today`、`/parent/report`;微信落点 Today;底栏仍三项 | | 05 §3.3 `planItemId="{date}:{cardId}"` | 听一听 / 写一写 / 深链均用此形 | | 30-uiux F2–F10、F14–F17、F23–F24 | Today 五卡、听写内嵌、深链、休息/离线、家长周报与跳卡 | | 50-backend skip `device\|time\|other` | 家长页原因映射为这三个 id | **报主 agent(契约/数据缺口,未改后端):** 1. 今日周六 `GET /api/plan/today` 的 `c6.questions` 实为 **14 题**(13 个 `spell_pick` + `phoneme:æ`),与 03/tasks 3.3「周六 15 题」不一致。前端按计划题数组题,不补题。 2. `9.1` 要求 `addWordsToStudy` 同步 `emit`,但客户端允许的 event type 无「加词」项(50-backend 只接受 phonics/quiz/…/writing_checkin)。本轮只更新本地缓存;生词进 SRS 仍靠 `records.unknown_words`。请裁决是否补 type 或从 9.1 删除该条。 3. `05` §5.2 写「卡完成本地先置绿」;tasks/design 决策为服务端确认后才绿。实现以后者为准。 ## 页面与组件清单(对照原型) | 原型页面 | 实现文件 | 覆盖交互 | 状态 | | --- | --- | --- | --- | | `shelf.html` | `Home.tsx` + `Home.css` | 「今天」入口、三条计划提示、休息态、三项底栏 | 已实现 | | `index.html` Today | `Today.tsx` + `Today.css` | 0–7 星、下一张、五卡、完成✓ / 已处理、骨架、庆祝/结束语 | 已实现 | | 听一听层 | `Today.tsx` 原位展开 | 大播放键、差分累计、失败「再试一次」 | 已实现(未实播满 45s) | | 写一写层 | `Today.tsx` | 任务文案、2s 长按家长确认 | 已实现并实走翻绿 | | 拼一拼层 | `Learn.tsx` + `usePlanMode` + `StarCollect` | 第 N/4 词、三关 emit、收星回 Today | 已实现(深链已开,未走完 4 词) | | 读一读层 | `ChildBookReader.tsx` | listen 听整本/听这页;review 先自检再 records;readable:false「跟着音频读」 | 已实现 | | 闯关层 | `Quiz.tsx` | 计划题、hasty、慢错「再试一次」、quiz_summary、收星 | 已实现(深链已开,未答完) | | 加载/休息/离线 | `Today.tsx` | 骨架;休息三入口;缓存+待同步;无缓存「小助手在休息」;软上限文案 | 已实现(今日周六未看到休息真态) | | `parent.html` | `Report.tsx` + `Dashboard.tsx` | 周报区块、空周、今日跳卡/写好了 | 已实现并实走跳听一听 | 新建:`learningEvents.ts`、`usePlanMode.ts`、`StarCollect.tsx/.css`、`Today.tsx/.css`、`Report.tsx/.css`。 `App.tsx` 注册 `/today`(ChildLayout 非沉浸)与 `/parent/report`;启动时 `installLearningListeners()`。 ## 接口对接清单 | 交互 | 接口 | 状态(真实 / mock+原因) | | --- | --- | --- | | 今天页 / 书架提示 | `GET /api/plan/today` | 真实 | | 写一写家长确认 | `POST /api/plan/{date}/cards/c5/complete` | 真实(c5→done,星 0→1) | | 听一听完成 | `POST /api/events` type=`listening` | 真实接线;未实播满 45s | | 拼一拼三关 | `POST /api/events` type=`phonics` | 真实接线 | | 闯关每题 / 汇总 | `POST /api/events` type=`quiz` / `quiz_summary` | 真实接线 | | 拼字首次判 | `POST /api/events` type=`spelling` | 真实接线 | | 阅读完成 | `POST /api/records`(服务端转 reading) | 真实接线;event_id 持久化 | | 离线重放 | `eventsApi.post` 批量 + `easy-study:event-queue` | 真实接线;未断网实走 | | 一次性迁移 | `POST /api/srs/sync` | 真实;本机 `synced=1` | | 家长周报 | `GET /api/reports/weekly` | 真实(W38 有数据 / W01 空) | | 家长跳卡 | `POST /api/plan/{date}/cards/{id}/skip` | 真实(c2 skipped,`card_skip.source=parent`) | | 连续天数 | 用计划 `summary.streak`;`daysApi` 已封装未单独打 | 真实(随 plan) | 无 mock。 ## 与原型差异 | 差异 | 理由 | | --- | --- | | 听一听在 Today **原位展开**,不是独立 overlay 页 | tasks 7.4 / 20-product:V1 不新建 `/listen` | | 空周报告仍显示「今天的任务管理」 | 跳卡针对**当天**计划,与所看周报是否有数据无关;空周区块本身无数字卡片 | | 计划模式拼读隐藏长「怎么玩」说明 | 遵守 C1 ≤12 字/句;自由模式保留原说明 | | 闯关计划题答对后约 0.7s 自动下一题 | 6 岁少点「下一题」;自由模式仍要点 | | 卡完成不乐观置绿 | 遵守裁决 #5 / StarCollect,不以 05「本地先绿」 | | `addWordsToStudy` 不 emit | 无对应事件 type(见上游核对 #2) | ## 自测记录 环境:Nginx `http://127.0.0.1/estudy/`,后端 8000,Vite 5173 热更新。今日 `2026-09-19` 周六计划:c1 `nap,bag,cat,hat`;c2 45s 绘本音频;c3 `mode=review` 且 `readable=false`;c5 `Bb + it/in`;c6 **14** 题。 1. `/estudy/today`:五卡、`0/7`、`0/5`、「下一张:拼一拼」;底栏看书/拼读/闯关;`localStorage['easy-study:synced']==='1'`;正文无 plan/SRS 等黑话。 2. 书架:`已完成 0/5 · 继续`;「今天读这本」Nobody Wanted To Play;「这些词还要再练」cat hat;「今天练这些词」nap bag。 3. 写一写短按:展开「大写、小写各 3 遍 / 单词各写 2 遍 / 写好了就给爸爸妈妈看」,完成类按钮 0 个。长按 2s 出「家长确认」→ 确认 → **c5=done,⭐ 1/7,卡文案「完成 ✓」**。 4. 听一听点开:原位大播放键 +「听完再继续」,未点播(避免未听满误报)。 5. 深链:`/learn/...?plan=2026-09-19:c1&words=nap,bag,cat,hat` 显示「第 1 / 4 个词」;`/book/.../read?plan=...:c3&mode=review` 有「听整本/听这页」「跟着音频读」「回今天」、无底栏;`/quiz/...?plan=...:c6` 显示「第 1 / 14 题」短文案。 6. `/parent/report`:W38 有「做了多少 / 哪里不稳 / 下周练什么 / 阅读 / 跳过」且无「口语」。跳过听一听(原因 device)后 `c2=skipped`,星仍为 1;回 Today 见「爸爸妈妈已处理」+「跳过不会扣星星」。`aria-label` 互不相同。W01:`本周还没有记录` + 日期。 7. `/parent` 有「本周报告」;Dashboard 仍能看到最近学习/拼错汇总。 8. 自由路径:`/learn/:id` 仍有词表与统计;`/quiz/:id` 仍 5 题长文案;`/book/:id/read` 返回书架、无计划听读条、无底栏。旧 `POST /api/records` 200;`GET /api/books/` 200。 9. 构建:`npx tsc -b --noEmit` 通过;`npm run build` 通过(vite 8,约 491 kB JS)。 未在本轮浏览器走完:c1 十二事件收星、c2 真实 45s、c3 翻完+6 词自检、c6 答完+仓促+断网队列、周日/请假休息、改日顺延、全完成 nudge 空体。请 QA 在 60-test 补齐。 ## 本轮改动(第 1 轮) - API:`client.ts` 增 `planApi/eventsApi/srsApi/reportsApi/daysApi` 与 05 字段类型;`ReadingRecordInput` 可选计划字段。 - 基建:`learningEvents.ts`(emit/队列/planCache/waitForCardDone)、`usePlanMode`、`StarCollect`。 - 孩子:`Today` 五卡闭环;`Home` 今天入口改读计划;`Learn/Quiz/SpellingGame/ChildBookReader` 接 `?plan=`;`bookStudy` 去掉 peek 与连对升级,本地 status 镜像 `srsUpdates`。 - 家长:`/parent/report` 周报 + 跳卡/写好了;Dashboard 入口。 - 11.1 后端 e2e 脚本:非本角色。11.4 `child-ux-tester`:请主 agent 在测试门禁后调用。