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():创建反义词表。