From 060daf02a184c327119eaab9ee7f5de65f8a790a Mon Sep 17 00:00:00 2001 From: ila Date: Sun, 21 Jun 2026 15:16:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=94=A8=E6=88=B7=E8=A1=A8=E9=A2=84?= =?UTF-8?q?=E7=95=99=20course=5Fid=EF=BC=8C=E8=AE=B0=E5=BD=95=E5=A4=9A?= =?UTF-8?q?=E6=95=99=E6=9D=90=E6=89=A9=E5=B1=95=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 04-architecture 3.2：progress/vocab 加预留列 course_id（默认 family-album）， 避免将来接入新概念英语等时迁移用户数据；MVP 仅留列不写多教材逻辑 - 06-tasks：T-301 验收注明该预留列；待办池补"多教材接入"扩展点备忘 Co-Authored-By: Claude Opus 4.8 --- docs/04-architecture.md | 8 ++++++-- docs/06-tasks.md | 13 +++++++++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 62c23ee..c69a466 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -87,9 +87,13 @@ **users** — id, email, password_hash, created_at -**progress** — user_id, episode_id, act, last_position（秒）, completed, updated_at +**progress** — user_id, **course_id**, episode_id, act, last_position（秒）, completed, updated_at -**vocab** — id, user_id, word, episode_id, act, context_sentence, created_at +**vocab** — id, user_id, **course_id**, word, episode_id, act, context_sentence, created_at + +> **`course_id` 是前向兼容的预留列**：MVP 只有「走遍美国」一个教材，建表时即带上此列、固定默认 `"family-album"`。 +> 目的是避免将来接入新概念英语等时，对**已产生的用户进度/生词数据**做痛苦的 schema 迁移（用户数据不可重生，内容数据可重生）。 +> ⚠️ MVP 阶段**仅留列、填默认值，不写任何多教材逻辑**（不建 courses 表、不改内容 JSON、不做按教材过滤）——多教材接入是 V2+，见 [任务看板](06-tasks.md) 待办池。 **功能模块化**：字幕同步、生词本、播放器做成可复用组件，不同教材按需启用（走遍美国用字幕同步；新概念可能更重单词表与语法）。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 65a73d1..3ef32fe 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -55,7 +55,7 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-301 | SQLite 初始化 + 建表（users/progress/vocab） | T-002 | 按 04-architecture 第 3.2 节建表；首次启动自动建库 | TODO | +| 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 | @@ -99,5 +99,14 @@ ## 待办池（Backlog · V2+，暂不排期） -复读/精听（AB 复读、变速）、测验、学习打卡、激励模块、多教材扩展、中英对照、生词 SRS。 +复读/精听（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 的容错思路可复用）。