主题
RB 本地数据库表速览
22 张表（19 张 baseline schema + v11/v16/v18 新建表；v20 phrase_interaction_log 已于 v25 DROP 退役），按用途分 5 组 （另有 4 张
*_new迁移期临时重建表 + 预装库内 3 张lemma_*表，均不计入） 列级详细定义见docs/database-schema.md；迁移版本史见docs/database-schema.md§10 Supabase DDL 见supabase/sql/sync-tables.sql
目录
1. 学习核心（6 张）
产品核心价值——用户学习英语的全部数据。其中 5 张（learning_entries / reading_notes / reading_pages / word_page_links / page_annotations）与 Supabase/RVH 双向同步。reading_pages / word_page_links 自 v23 起带 deleted_at（笔记四级删除闭环：笔记本/来源页/句子/单词四级软删 + 墓碑跨端传播）。
| 表 | 作用 | 预装 | 同步 | Soft-Delete |
|---|---|---|---|---|
| vocabulary | 词库。word 作主键（COLLATE NOCASE，跨端 PK 对齐）。存 IPA 音标、CEFR 等级、词性释义 JSON、词频、词形/词族等。预装库由 RVH pipeline 单点产出，运行时 ATTACH 只读 lampio_dict.db；查词遇预装库外的词走 Supabase 缓冲池回填 | 18,898 | ❌ | ❌ |
| learning_entries | 学习状态。用户"加入学习"的每个词一条记录，承载 SM-2 算法全部状态（easy_factor / interval / repetitions / next_review_date / last_review_quality）。word FK → vocabulary，UNIQUE(user_id, word) | — | ✅ | ✅ |
| reading_notes | 笔记容器。一个域名/资源自动创建一个 note（webArticle/pdf/epub）。存标题、封面 BLOB、阅读进度、full_text_path | — | ✅ | ❌ |
| reading_pages | 页面来源。一个 URL = 一条 reading_source，挂在 reading_note 下。存 HTML 缓存路径 + storage_path（跨端快照）。v23 加 deleted_at（remove_reading_page 事务软删 + 级联软删子表 word_page_links/page_annotations） | — | ✅ | ✅ |
| word_page_links | 词-来源关联。记录"这个词是在哪个页面学的"。notebook_entry × reading_source 唯一。v23 加 deleted_at（词级删除 + 随来源级联软删；写入用 ON CONFLICT DO UPDATE SET deleted_at=NULL 复活） | — | ✅ | ✅ |
| page_annotations | 句子级学习痕迹。记录用户在某页面对句子做的 4 类操作：translation(翻译) / analysis(拆解) / context(指代·背景) / highlight(标记)。「本页精读」面板（句子工作台 SentenceWorkbench）的持久化数据源；highlight 同时驱动原文内联黄 <mark>（content-script loadAndWrapAnnotations 按 source_text 重建）。FK → reading_pages | — | ✅ | ✅ |
预装库
lampio_dict.db内的非主库表（2026-06-15 cross-end/13 lemmatizer 折叠）：除vocabulary外，bundled 预装库还含 3 张lemma_*表——lemma_surface_to_base(140,277) /lemma_base_forms(101,713) /lemma_meta(4)。它们是 lemmatizer Layer 1/2 数据，运行时由commands/lemmatizer.rs从 bundled db 只读直载进内存（不 seed 进主库、不同步）。详见docs/vocabulary-domain-knowledge.md§7。
关系
vocabulary ──1:N──→ learning_entries ──1:N──→ word_page_links
(word PK) (soft-delete) (soft-delete, v23)
│ N:1
▼
reading_notes ──1:N──→ reading_pages ←── word_page_links
(soft-delete, v23)
│
└──1:N──→ page_annotations (soft-delete)2. 词汇过滤（3 张）
控制 CEFR 高亮和发现模式的过滤范围。
| 表 | 作用 | 预装 | 同步 | Soft-Delete |
|---|---|---|---|---|
| known_words | 用户排除词（per-user）。用户手动排除的词，从 CEFR 高亮和发现列表中过滤。排除一个词同时会 soft-delete 对应的 notebook_entry。source='user' 还兼作"覆盖推荐停用词"的 tombstone | — | ✅ | ✅ |
| default_stopwords | 系统默认停用词（a/the/is/are…）。纯本地预装（2026-07 决策5：不再从 Supabase 拉取）——由 init_data.sql 安装期播种 211 行（id 沿用确定性 sys-ew-*，跨端一致），仅 id/word/sort_order 三列；作为 merge 源 INSERT OR IGNORE 进用户的 known_words | ~211 | ❌ 预装 | ❌ |
| reference_words | ~193 条专有名词/缩写（国家、城市、组织、品牌如 CNN/NASA/GDP），带 chinese_meaning。2026-08-31 起是纯数据表：不参与任何查询过滤（此前它是高亮/发现的黑名单，实测 193 行里 145 行空转、20 行冗余，独有的 28 行里 17 行是误杀 —— fox/dna 与 15 个带 adj 的国籍词）。保留的理由是那 193 行中文释义是 L-D「专名走 background 补全」的兜底数据源。7 个 Tauri 命令已随之下线。自 2026-04-21 起不同步 | ~193 | ❌ | （本地） |
过滤链
vocabulary 全集
→ 排除 known_words（用户排除词，含从 default_stopwords 合并的系统停用词）
→ 排除纯专名（`db/vocab_scope.rs` 谓词，**只对「发现候选池」这一支生效**）
→ 最终高亮/发现词集Rust 层（WHERE 子句）和 JS 层（Set.delete）双重过滤，defense-in-depth。
⚠️ 两点易错： ① 专名过滤只在「我们主动推给用户」的那一支（发现 / 快速分级 / 校准 / 难度评估）。 用户已保存的词（CEFR 高亮 / 复习 / 统计）一律不过滤 —— 他存了就是他的选择。 ② 这条链上曾经还有一步「排除 reference_words」，2026-08-31 已拆除（见该表那一行）。
3. 内容发现（6 张）
为用户提供英文内容入口。分"推荐"（远程拉取）和"用户自建"（本地操作 + 同步）两部分。
推荐三表（← Supabase 公开表拉取）
| 表 | 作用 | 预装 | Supabase 对应 | 首页区域 |
|---|---|---|---|---|
| recommended_sites | 推荐站点。英文站点（BBC/NPR/Aeon 等），App 启动时从 Supabase 远程刷新覆盖 is_default=1 的记录 | 33 | recommended_sites | Recommended Sites |
| recommended_feeds | 推荐 RSS 源，App 启动时从 Supabase 远程刷新 | 8 | recommended_feeds | Recommended Feeds |
| recommended_articles | AI 推荐文章。由 Supabase Edge Function 每日生成，App 启动时拉取，7 天过期 | — | recommended_articles | Recommended For You |
用户自建三表
| 表 | 作用 | 同步 | Soft-Delete | 首页区域 |
|---|---|---|---|---|
| favorite_sites | 用户收藏站点。domain 级别（如 bbc.com），用户点击 ☆ 收藏。UUID id + user_id | ✅ | ✅ | My Favorite Sites |
| rss_feeds | 用户订阅的 RSS 源。从推荐中订阅或手动添加 URL。UUID id + user_id | ✅ | ✅ | My Feeds |
| rss_items | RSS 文章缓存。每个 feed 下缓存的文章条目，含已读状态和 CEFR 等级。FK → rss_feeds（不同步，靠孤儿清理） | ❌ | ❌ | Feed 文章列表 |
4. 阅读辅助 / 统计 / 复习支撑（7 张）
增强阅读体验 + 学习统计 + 复习卡支撑的本地功能表。domain_prefs + word_cloze_contexts 参与同步，其余 5 张均 local-only（含用户阅读/学习内容的均纳入"用户切换清理"红线 5c）。
| 表 | 作用 | 同步 | 说明 |
|---|---|---|---|
| domain_prefs | 域名偏好。记住每个域名的阅读模式（original / reader）和关联的 reading_note。PK (user_id, domain)，FK → reading_notes。自阶段 C 起加入同步矩阵（synced_at + deleted_at） | ✅ | 按域名 1 条 |
| resource_history | 访问历史。统一记录 web/epub 的打开记录，含打开次数和最后访问时间。首页 Recently Opened 和历史面板的数据源。per-user 隔离，UNIQUE(user_id, uri)。⚠️ resource_type 有 CHECK('web','epub')，粘贴文本刻意记作 'web'（改成 'text' 会当场违约，见 database-schema.md） | ❌ | 持续增长 |
| reading_log | 阅读会话统计明细。每次会话写一行（word_count / new_words / read_time / cefr_level）。StatsPanel 的 trends/weekly/monthly/streaks 全部读这里。与 resource_history 互补：后者是"访问过哪些"（去重），前者是"每次读了多少/多久"（可 SUM/GROUP BY） | ❌ | 持续增长 |
| pronunciation_attempts | 跟读评分历史。Azure Speech 发音评分明细，per-user。v11 新建，local-only MVP，同步矩阵留后续 | ❌ | 持续增长 |
| word_cloze_contexts | 复习卡 cloze 语境（roadmap ⑥）。存用户加词时正在读的句子 + 原始 surface，复习卡正面据此挖空生词；v17 加 sense_gloss（贴合语境义项 gloss，翻面绿底高亮重定位）。v16 新建 / v21 去 UNIQUE 重建 / v24 纳入同步矩阵，含用户阅读句 | ✅ | 一词多语境池（v21 去 UNIQUE(user_id,word)，应用层去重 + 封顶 5 满池软删最旧；merge 后 reconcile_cloze_pool 重新封顶，见 docs/database-schema.md §8） |
| word_personalized_examples | 个性化例句缓存（roadmap ④）。复习揭晓侧"再看一个新语境例句"按需生成结果，锚 sense_gloss + 真实读句 + 兴趣信号经 Edge Function generate-example 产出，一词≤5。v18 新建 | ❌ | local-only，与跨用户缓冲池互斥 |
5. 基础设施（1 张）
| 表 | 作用 | 说明 |
|---|---|---|
| settings | KV 配置。存 Supabase URL/anon_key、auth_user_id、last_sync_at / last_sync_attempt_at、vocabulary_seed_version、各类用户偏好开关 | ~20+ 个 key |
6. 表关系图
=== 学习核心 + 阅读笔记 ===
vocabulary (18,898 预装, word PK)
│ 1:N (word FK)
▼
learning_entries (SM-2 学习状态, soft-delete, 同步)
├── 1:N ── word_page_links (词-来源关联, soft-delete v23, 同步)
│ │ N:1
│ ▼
│ reading_pages (页面来源, soft-delete v23, 同步)
│ │ N:1 │ 1:N
│ ▼ ▼
│ reading_notes page_annotations
│ (笔记容器, 同步) (翻译/拆解/指代/标记痕迹, soft-delete, 同步)
│
=== 词汇过滤 ===
known_words (用户排除词, soft-delete, 同步) ←── word (软引用，v43 后无 FK)
default_stopwords (系统停用词, 本地预装 seed) ──merge──→ known_words
reference_words (~193 参考词, 本地不同步；2026-08-31 起纯数据、不再当过滤器)
=== 内容发现 ===
rss_feeds (同步) ──1:N──→ rss_items (本地缓存)
recommended_sites / recommended_feeds / recommended_articles（← Supabase 拉取）
favorite_sites（同步）
=== 阅读辅助 / 统计 / 复习支撑 ===
domain_prefs ──→ reading_notes.id (可选 FK，同步)
resource_history / reading_log / pronunciation_attempts（独立，本地）
word_cloze_contexts（复习卡支撑，word 软引用，同步 v24 起）/ word_personalized_examples（复习卡支撑，本地，word 软引用）
=== 基础设施 ===
settings（独立 KV）7. 数据流全景
用户打开网页
│
├─→ resource_history（记录访问，去重）
├─→ reading_log（会话统计明细，供 StatsPanel）
├─→ domain_prefs（读取/存储阅读偏好）
│
├─→ CEFR 高亮
│ vocabulary → 排除 known_words → 高亮（已保存词**不**过滤专名，见「过滤链」）
│
├─→ 查词 / 学习
│ vocabulary（本地预装）→ 未命中走 Supabase 缓冲池回填 → 弹窗释义
│ → learning_entries（加入学习，SM-2 初始化）
│ → word_page_links（关联页面）
│ → word_cloze_contexts（存当前阅读句 + surface，供复习卡挖空）
│
├─→ 翻译 / 拆解 / 指代·背景 / 标记（选区工具栏 + 本页精读卡）
│ → 调用 API/Edge（翻译/拆解/指代）或纯本地（标记）→ 前端实时展示
│ → page_annotations（4 类痕迹，关联到 reading_pages）
│ → highlight 类另在原文画内联黄 mark（即时 + 刷新重建）
│
├─→ 短语自动高亮
│ → 无自有表（命中短语保存走 learning_entries，复用 save_word 链路）
│ → 曾有 phrase_interaction_log 验证埋点，已于 v25 DROP 退役
│
├─→ 跟读评分
│ → Azure Speech → pronunciation_attempts（评分明细）
│
├─→ 笔记系统
│ domain_prefs → reading_notes → reading_pages
│ → page_annotations
│ → word_page_links
│ 四级删除（v23）：来源页/句子/单词软删 → deleted_at 墓碑
│ → reading_pages 软删级联清 word_page_links/page_annotations/cloze
│ → sync 墓碑三分支跨端传播（不复活）
│
└─→ 复习
learning_entries（SM-2 due cards）
→ word_cloze_contexts（正面挖空语境，一词多语境轮换 v21）+ word_personalized_examples（揭晓侧按需生成例句）
→ 2-button Hard/Easy → 更新 SM-2 状态8. 同步总览
10 张用户表双向同步（↔），3 张推荐表单向拉取（←）。reference_words 自 2026-04-21 起不再同步；default_stopwords 自 2026-07 决策5 改纯本地预装（不再拉取，Supabase 侧已 DROP）；rss_items 不同步（靠孤儿清理）；word_cloze_contexts 自 2026-07-09（v24）起纳入同步矩阵。其余 local-only 不进同步矩阵：resource_history / reading_log / pronunciation_attempts / word_personalized_examples / default_stopwords。下表为 yes/no 速查；完整列级映射 + Supabase 全列定义见 docs/database-schema.md §9。
| 本地表 | Supabase 表 | 方向 | Soft-Delete |
|---|---|---|---|
| learning_entries | user_learning_entries | ↔ | ✅ |
| reading_notes | user_reading_notes | ↔ | ❌ |
| reading_pages | user_reading_pages | ↔ | ✅（v23） |
| word_page_links | user_word_page_links | ↔ | ✅（v23） |
| known_words | user_known_words | ↔ | ✅ |
| favorite_sites | user_favorite_sites | ↔ | ✅ |
| rss_feeds | user_rss_feeds | ↔ | ✅ |
| domain_prefs | user_domain_prefs | ↔ | ✅ |
| page_annotations | user_page_annotations | ↔ | ✅ |
| recommended_sites | recommended_sites | ← 拉取 | — |
| recommended_feeds | recommended_feeds | ← 拉取 | — |
| recommended_articles | recommended_articles | ← 拉取 | — |
| default_stopwords | （无，本地预装） | 预装 seed | — |