lingo/docs/06-tasks.md

任务看板（Tasks · AI 的 Jira）

把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。

⛔ 使用规则（最重要，必须遵守）

1. 一次只做一个任务：每轮只领取一个状态为 TODO、且其依赖均已 DONE 的任务——取最靠前的那个。
2. 做完即停：完成该任务、自测通过其"验收"、把状态改成 DONE 后，停下来汇报，等待下一步指令。不要顺手往下做后续任务，不要一次铺开多个任务。
3. 不跳步：依赖未 DONE 的任务不能开工；如果发现顺序不合理，先提出来，别擅自重排。
4. 完成的定义：以 编码规则 第 8 节"改完之前"清单为准（能构建、过校验、对得上验收、文档同步、如实汇报）。
5. 动手前先读 CLAUDE.md 与 编码规则；范围以 需求、做法以 技术栈 + 架构设计 为准。

状态图例

TODO 待开始 · DOING 进行中（同一时间最多 1 个）· DONE 已完成并验收 · BLOCKED 受阻（注明原因）

改状态时直接编辑本文件对应行。DOING 全局只允许有一个。

---

Phase 0 · 地基（必须最先完成）

先有最小可运行骨架，才能在上面验证最难的字幕同步。

ID	任务	依赖	验收要点	状态
T-001	初始化 go 模块 + go-app 最小可运行页面	—	go.mod 就位；GOOS=js GOARCH=wasm go build 通过；浏览器打开能看到一个最简页面	DONE
T-002	后端静态服务 + 音频路径映射	T-001	访问 /family-album/audio/u0101.mp3 能播到磁盘 family-album-usa/audio/u0101.mp3；wasm/静态资源正常加载	TODO
T-003	加载并解析 episodes.json 为 Go 结构体	T-001	struct 与真实 schema 一致（line 仅 {t,en}，无 zh）；启动时成功载入 26 集；前端可拿到课程数据	TODO

T-003 范围：只做数据加载与类型定义，不做 UI 渲染（那是 Phase 2）。

Phase 1 · 核心验证：字幕同步原型（最难，先攻）

先用写死的一幕把同步跑通，验证可行性，再谈页面。

ID	任务	依赖	验收要点	状态
T-101	单幕音频播放器组件（播放/暂停/拖动）	T-002, T-003	选一个有音频的 act（如 ep1 act1），能播放、暂停、拖动进度	TODO
T-102	字幕逐句渲染 + 当前句高亮	T-101	播放时高亮句与人耳听到的一致；定位用 currentTime 在 lines[].t 上二分查找	TODO
T-103	点句跳转	T-102	点任一句，音频在约 1 秒内 seek 到该句 t 开头并继续播放	TODO
T-104	容错：非单调时间戳 / 无音频降级	T-103	时间戳乱序/相等不崩（已知 ep18/ep25）；hasAudio=false 的 act 只显示文本并标注无音频	TODO

对应需求验收：02-requirements 第五节"逐句同步"。这是 P0 核心，务必先单独跑通。

Phase D · 设计（先于 Phase 2 的 UI）

ID	任务	依赖	验收要点	状态
T-200	UI 效果稿：播放页 + 课程列表（HTML/CSS）	—	中保真稿覆盖逐句高亮/点句跳转/进度/无音频降级；用真实数据；CSS 可迁移 go-app。见 design_mockups/	DONE

设计 spike，不是生产代码。产出在 design_mockups/play.html、design_mockups/list.html，作为 T-201/T-203 的视觉依据；CSS 可迁移，但不要直接把 spike 当生产代码整体搬入。

Phase 2 · 课程列表 + 播放页

ID	任务	依赖	验收要点	状态
T-201	课程列表页（读 episodes.json 渲染）	T-003	列出 26 集 / 各幕；标出哪些幕有音频；移动优先布局	TODO
T-202	路由：列表 → 选集选幕 → 播放页	T-201	点列表项进入对应播放页，可返回	TODO
T-203	播放页接入 Phase 1 同步组件	T-202, T-104	任选有音频的幕，播放 + 逐句同步 + 点句跳转全部可用	TODO

页面路由与组件归属见 路由；视觉参考 design_mockups/；包布局见 架构设计 第六节。

Phase 3 · 后端账号体系（Session Cookie）

ID	任务	依赖	验收要点	状态
T-301	SQLite 初始化 + 建表（users/progress/vocab）	T-002	按 04-architecture 第 3.2 节建表；首次启动自动建库；progress/vocab 含预留列 course_id，默认 "family-album"（仅留列，不写多教材逻辑）	TODO
T-302	注册 / 登录 API + httpOnly Session Cookie	T-301	注册、登录成功后下发 httpOnly cookie；带 cookie 的请求能识别用户；登出失效	TODO
T-303	前端登录 / 注册界面 + 登录态	T-302	能注册登录；刷新后保持登录；未登录访问需登录的页面会被引导登录	TODO

接口合约见 API；建表 SQL 见 架构设计 第 3.2 节。

Phase 4 · 生词本

ID	任务	依赖	验收要点	状态
T-401	生词本 API（增 / 删 / 查）	T-302	登录用户可增删查自己的生词；按 episode_id+act 记录出处	TODO
T-402	点词加入生词本（播放页交互）	T-401, T-203	在字幕里点单词即可加入；有反馈	TODO
T-403	生词本列表页	T-401	查看自己的生词列表；刷新/重进仍在	TODO

对应需求验收：02-requirements 第五节"生词本"。MVP 只存单词，不接词典释义。接口合约见 API 生词本一节。

Phase 5 · 进度同步

ID	任务	依赖	验收要点	状态
T-501	进度 API（读写 last_position / completed）	T-302	按用户 + episode_id+act 读写播放进度	TODO
T-502	播放时上报进度 + 列表显示进度	T-501, T-203, T-201	播放中断点被记录；课程列表显示学习进度（如"2/3 幕"）	TODO
T-503	跨设备验证	T-502	A 设备学习后，B 设备登录同账号看到相同进度与生词本	TODO

对应需求验收：02-requirements 第五节"账号与同步"。接口合约见 API 学习进度一节。

Phase 6 · PWA 离线化

ID	任务	依赖	验收要点	状态
T-601	PWA manifest + 可安装	T-203	可安装到手机主屏，有图标与名称	TODO
T-602	Service Worker 缓存 app shell	T-601	二次访问离线也能打开界面	TODO
T-603	离线缓存音频与文稿 + 离线可用验证	T-602	断网后能打开已学过的课程并播放	TODO

对应需求验收：02-requirements 第五节"离线可用"。MVP 内容锁定 ep1–17（ep18–26 缺音频，见 02-requirements / 数据校验）。

---

里程碑

• M1 · 同步可行性：Phase 0 + Phase 1 完成 → 字幕同步原型跑通（最高风险解除）
• M2 · 可用闭环：+ Phase 2/3/4/5 → 列表/播放/账号/生词/进度的最小闭环
• M3 · MVP 达成：+ Phase 6 → 可安装、离线可用，对齐 02-requirements 全部 P0 验收

待办池（Backlog · V2+，暂不排期）

复读/精听（AB 复读、变速）、测验、学习打卡、激励模块、中英对照、生词 SRS。 （来源见 02-requirements"后续迭代"；MVP 阶段一律不做。）

多教材接入（如新概念英语）— 扩展点备忘

MVP 已做的前向兼容：progress/vocab 预留了 course_id 列（默认 family-album），用户数据无需迁移。真正接入时还需：

1. 内容加 course 层：每本教材一个 JSON + courses 索引（或顶层 courses[]）；走遍美国即第一个 course。
2. 用户表启用 course 维度：查询/写入带上 course_id（列已预留，补逻辑即可）。
3. 内容组件按教材类型分化：新概念更重课文+单词表+语法，需不同渲染组件（架构已说"功能模块按教材启用"）。
4. line 兼容无逐句时间戳：t 可空 + 无同步降级（T-104 的容错思路可复用）。