数据库设计文档

项目: Reading Vocab Helper 版本: 详见 schema.md最后更新: 2026-03-07

---

📚 文档导航

文档	说明
schema.md	📊 核心文档：表结构、关系图、数据流转
optimization.md	⚡ 性能优化记录和策略
01_create_tables.sql	📄 DDL：建表语句（位于 assets/sql/）
02_create_indexes.sql	🔍 索引定义（位于 assets/sql/）
03_init_data.sql	🌱 DML：初始化数据（位于 assets/sql/）

---

🚀 快速开始

当前数据库状态

• 表数量: 12张
• 索引数量: 23个
• Schema版本: v57（权威见 schema.md）
• 数据库文件: lampio.db（本地用户库）+ assets/databases/lampio_dict.db（预装词库 asset）

核心业务表

学习流程：
vocabulary_items (预装词 + 回填词) → notebook_entries (生词本)
                              ↓
                         word_mastery_info (SM-2算法)
                              ↓
                         learning_records (学习历史)

词汇查询（3层回填架构 v6）：
本地 vocabulary_items → Supabase 云端词库 → Edge Function API
         ↓                      ↓                     ↓
    90%+ 命中              8% 命中 → 回填本地      2% 命中 → 回填Supabase → 回填本地

阅读追踪：
reading_sources (阅读来源) ← word_source_relations → notebook_entries
       ↓
ocr_word_positions (单词位置)

---

🔧 开发模式（当前）

数据库变更策略

原则: 简化重建，不做复杂迁移（开发阶段可接受数据丢失）

流程:

1. 修改SQL文件（01_*.sql, 02_*.sql, 03_*.sql）
2. 更新 schema.md 文档
3. 修改 app_database.dart 中的 _schemaVersion
4. 重启应用 → 自动重建数据库

时间戳占位符:

created_at TEXT DEFAULT '{CURRENT_TIMESTAMP}'  -- 应用层自动替换

---

📖 详细文档

schema.md - 数据库架构

完整的表结构、关系图、数据流转说明：

• ER图: 12张表的实体关系
• 表定义: 每张表的详细字段说明
• 关系说明: 外键、约束、级联规则
• 业务流程: 3个核心流程的数据流转
• 索引策略: 20个索引的用途

optimization.md - 性能优化

记录所有性能优化的决策和效果：

• v1.1 优化: 反规范化phonetic字段（减少60% JOIN）
• 复合索引: 提升20-40%查询速度
• 缓存策略: translation_cache设计
• 未来优化方向: 聚合缓存表、远程词库等

---

⚠️ 重要约束

外键级联规则

删除操作	影响
reading_sources	CASCADE → word_source_relations, ocr_word_positions
notebook_entries	RESTRICT → 需先删除 learning_records, word_mastery_info

唯一约束

• vocabulary_items.word - 词库单词唯一
• word_mastery_info.notebook_entry_id - 一对一关系
• word_source_relations(notebook_entry_id, reading_source_id) - 复合唯一

JSON字段

需要应用层序列化：

• vocabulary_items: word_family, synonyms, antonyms
• notebook_entries: tags
• translation_cache: definitions

---

🛠️ 工具和命令

查看数据库结构

# 查看所有表
sqlite3 english_learning.db ".tables"

# 查看表结构
sqlite3 english_learning.db ".schema notebook_entries"

# 查看索引
sqlite3 english_learning.db ".indexes"

# 导出数据
sqlite3 english_learning.db ".dump" > backup.sql

验证数据库

// 代码位置: lib/shared/data/database/app_database.dart
final schemaVersion = await db.rawQuery('PRAGMA user_version');
print('当前Schema版本: $schemaVersion');

---

📝 维护检查清单

修改数据库时，确保完成以下步骤：

• [ ] 修改 01_create_tables.sql 或 02_create_indexes.sql
• [ ] 更新 schema.md 中的ER图和表定义
• [ ] 修改 app_database.dart 的 _schemaVersion（触发重建）
• [ ] 如果是性能优化，记录到 optimization.md
• [ ] 测试重启应用，验证数据库重建成功

---

🔮 未来规划

生产环境迁移（TODO）

生产版本需要实现：

• [ ] 增量迁移脚本（04_migrate_v1_to_v2.sql）
• [ ] 数据备份机制
• [ ] 版本兼容性检查
• [ ] 回滚策略

---

📞 问题排查

常见问题

Q: 应用启动时数据丢失？ A: 开发模式下正常。检查 _schemaVersion 是否修改，导致自动重建。

Q: JOIN查询很慢？ A: 检查是否缺少索引，参考 02_create_indexes.sql 和 optimization.md。

Q: 外键约束错误？ A: 检查删除顺序，reading_sources 会级联删除，notebook_entries 需先删除关联。

---

版本历史:

• v6 (2026-01-01) - 架构统一：移除translation_cache/vocabulary_cache表，移除vocabulary.db依赖，统一使用AppDatabase，启用3层回填（本地→Supabase→Edge Function API）
• v5 (2025-12-31) - 逐级回填：vocabulary_items回归主数据库，支持动态增长
• v4 (2025-12-30) - 云端化：添加vocabulary_cache表，Supabase词汇云端化
• v3 (2025-12-29) - 架构清理：移除主数据库vocabulary_items，词库独立管理
• v2 (2025-12-28) - 性能优化：反规范化phonetic、新增复合索引
• v1 (2025-12-27) - 初始版本：10张表，完整学习追踪功能