WordDatabase 类文档

负责人: 刘继轩

一、概述

WordDatabase 类负责与 SQLite 数据库交互，管理单词、分类、用户和学习记录。它提供了一系列方法用于数据库的初始化、单词和分类的增删改查、用户认证以及学习记录的管理。同时，还支持获取随机单词、按复习次数筛选单词以及更新单词学习信息等功能。

二、设计理念

WordDatabase 是系统的“数据仓库管理员”。

• 设计理念: 这是一个典型的数据访问对象（DAO）。它将所有 SQL 语句和数据库连接细节封装在内部，对上层（Learner）提供语义清晰的接口（如 getWordsToReview(), updateWordLearningInfo()）。这种设计极大地降低了系统的耦合度，如果未来需要将 SQLite 更换为 MySQL，我们只需要修改这一个类，而上层代码无需任何变动。

三、属性

• QSqlDatabase m_db：数据库连接对象。
• QString Path：当前数据库的路径。
• QString m_connectionName：数据库连接的名称。

四、方法

数据库状态管理

• bool isOpen() const：检查数据库是否打开。

  返回值：若数据库已打开，返回 true；否则返回 false。

• void close()：关闭数据库连接。

数据库操作

• bool initDatabase(const QString &name)：打开已有的数据库。

  参数：name 为数据库名称。

  返回值：若成功打开数据库，返回 true；否则返回 false。

• bool NewDatabase(const QString &name)：创建新的数据库。

  参数：name 为数据库名称。

  返回值：若成功创建并打开数据库，返回 true；否则返回 false。

• int getTotalWordCount(int categoryId = -1)：获取数据库中单词的总数。

  参数：categoryId 为分类 ID，默认为 -1，表示不指定分类。

  返回值：返回数据库中符合条件的单词总数。

单词管理

• bool addWord(const Word &word)：向数据库中添加新单词。
• bool deleteWord(int id)：根据单词 ID 删除单词。
• QVector<Word> getAllWords()：获取数据库中所有的单词。
• Word getWordById(int id)：根据单词 ID 获取单词信息。
• QVector<Word> getWordsByName(const QString &wordName)：根据单词名称查找单词。
• QVector<Word> getWordsByCategory(int categoryId)：获取指定分类下的所有单词。
• QVector<Word> getWordsToReview(int count = 20, int userId = 1)：获取需要复习的单词。
• QVector<Word> getRandomWords(int count, int categoryId = -1)：从指定分类中随机获取指定数量的单词。
• QVector<Word> getWordsByReviewCount(int maxReviewCount, int count = -1, int categoryId = -1)：获取复习次数小于等于指定值的单词。
• bool updateWordLearningInfo(int wordId, bool correct, int difficultyChange = 0, int userId = 1)：更新单词学习信息并添加学习记录。

分类管理

• bool addCategory(const Category &category)：添加新的分类。
• bool deleteCategory(int id)：根据分类 ID 删除分类。
• QVector<Category> getAllCategories()：获取所有的分类。
• Category getCategoryById(int id)：根据分类 ID 获取分类信息。
• QVector<Category> getCategoriesByName(const QString &categoryName)：根据分类名称查找分类。
• bool assignWordToCategory(int wordId, int categoryId)：将单词添加到指定分类中。
• bool removeWordFromCategory(int wordId, int categoryId)：将单词从指定分类中移除。

用户管理

• bool addUser(const QString &username, const QString &password)：添加新用户。
• bool authenticateUser(const QString &username, const QString &password)：验证用户的用户名和密码。
• int getUserId(const QString &username)：根据用户名获取用户 ID。

学习记录管理

• bool addLearningRecord(const LearningRecord &record)：添加学习记录。
• QVector<LearningRecord> getUserLearningRecords(int days = 30, int userId = 1)：获取指定用户在指定天数内的学习记录。
• double getLearningAccuracy(int days = 30, int userId = 1)：计算指定用户在指定天数内的学习准确率。
• int getTotalLearningRecordCount(int days = -1, int userId = 1)：获取数据库中学习记录的总数。
• bool resetLearningRecords()：重置学习当前数据库的学习记录。

工具方法

• bool createTables()：创建数据库的表结构。
• bool insertSampleData()：插入示例数据。
• static QMap<QString, QString> getpath()：获取所有数据库文件的路径。
• static QVector<QString> getlist()：获取所有数据库的名称。
• const QString& getPath()：获取当前数据库的路径。

私有方法

• bool openDatabase(const QString &dbPath, bool isNew)：打开数据库。
• bool execSql(const QString &sql)：执行 SQL 语句。
• int getOrCreatePartOfSpeech(const QString &posName)：获取或创建词性。
• bool savePhonetics(int wordId, const QVector<Phonetic> &phonetics)：保存音标。
• bool saveDefinitions(int wordId, const QMap<QString, QVector<Definition>> &meanings)：保存释义。
• bool loadPhonetics(int wordId, QVector<Phonetic> &phonetics)：加载音标。
• bool loadDefinitions(int wordId, QMap<QString, QVector<Definition>> &meanings)：加载释义。
• bool createWordTable()：创建单词表。
• bool createCategoryTable()：创建分类表。
• bool createUserTable()：创建用户表。
• bool createLearningRecordTable()：创建学习记录表。
• bool createWordCategoryTable()：创建单词 - 分类关联表。
• bool createPhoneticsTable()：创建音标表。
• bool createPartsOfSpeechTable()：创建词性表。
• bool createDefinitionsTable()：创建释义表。
• bool createSynonymsTable()：创建同义词表。
• bool createAntonymsTable()：创建反义词表。