DAO 代码说明文档

DAO 代码说明文档

目录结构

• base_dao.py：DAO 基础类，封装通用的 MongoDB 操作。
• db.py：数据库连接与获取集合的工具类。
• user_dao.py：用户相关数据操作。
• history_dao.py：对话历史相关数据操作。
• homework_dao.py：作业相关数据操作。
• student_homework_dao.py：学生作业相关数据操作。
• teach_dao.py：师生关系相关数据操作。
• question_dao.py：题目相关数据操作。
• main.py：FastAPI 路由接口实现。

---

1. base_dao.py

作用

封装了 MongoDB 的基础增删改查（CRUD）操作，所有具体 DAO 均继承自该类。

主要方法

• insert_one(data)：插入单条数据，返回插入的 _id。
• insert_many(data_list)：批量插入，返回所有插入的 _id。
• find_one(query)：查找单条数据。
• find_many(query, skip=0, limit=100)：查找多条数据，支持分页。
• update_one(query, update_data)：更新单条数据，返回修改数量。
• update_many(query, update_data)：批量更新，返回修改数量。
• delete_one(query)：删除单条数据，返回删除数量。
• delete_many(query)：批量删除，返回删除数量。
• aggregate(pipeline)：聚合查询。
• snake_to_camel(snake_str)：蛇形转驼峰命名。
• map(d)：递归转换 MongoDB 文档为前端友好格式（如 _id 转为 id，键名驼峰化）。

---

2. db.py

作用

封装 MongoDB 连接，提供获取集合的方法。

主要方法

• get_collection(collection_name)：获取指定集合对象。

---

3. 具体 DAO 类

3.1 user_dao.py

• find_by_id(id)：根据用户 _id 查询用户。
• find_by_account(account)：根据账号查询用户。
• find_users()：查询所有用户。
• update_user(id, name, type, password)：更新用户信息。
• delete_user(id)：删除用户。
• add_user(account, name, type, password)：新增用户。

3.2 history_dao.py

• find_histories(student_id)：查询学生的所有对话历史。
• find_by_id(id)：根据对话 _id 查询。
• add_history(student_id, time, contents)：新增对话历史。
• update_history(id, contents)：更新对话内容。
• delete_user_callback(user_id)：删除用户时的回调，清理相关历史。

3.3 homework_dao.py

• add_homework(...)：新增作业。
• update_homework(...)：更新作业。
• find_by_teacher_id(teacher_id)：查询老师的所有作业。
• find_by_id(id)：查询作业详情（含题目）。
• delete_by_id(id)：删除作业。
• find_all_student_homework_by_id(id)：查询作业下所有学生作业。
• delete_user_callback(user_id)：删除用户时的回调，清理相关作业和学生作业。

3.4 student_homework_dao.py

• find_by_student_id(student_id)：查询学生的所有作业。
• find_by_homework_id(homework_id)：查询作业下所有学生作业。
• find_by_id(id)：查询单个学生作业。
• delete_by_id(id)：删除学生作业。
• delete_many_by_homework_id(homework_id)：批量删除作业下所有学生作业。
• add_student_homework(...)：新增学生作业。
• update_student_homework(...)：更新学生作业。
• update_many_student_homework_status(homework_id, status)：批量更新作业状态。
• get_all_student_homeworks(student_id)：聚合查询学生所有作业及作业详情。
• get_student_homework_info(id)：聚合查询学生作业详情（含题目）。
• delete_student_from_teacher_callback(student_id, teacher_id)：删除师生关系时的回调。
• delete_user_callback(user_id)：删除用户时的回调。

3.5 teach_dao.py

• add_teach(student_id, teacher_id)：新增师生关系。
• delete_teach(student_id, teacher_id)：删除师生关系。
• find_teacher_by_student_id(student_id)：查询学生的所有老师。
• find_student_by_teacher_id(teacher_id)：查询老师的所有学生。
• is_teach_exists(student_id, teacher_id)：判断师生关系是否存在。
• delete_user_callback(user_id)：删除用户时的回调。

3.6 question_dao.py

• add_question(stem, type, options, correct_answer, label)：新增题目。
• find_all()：查询所有题目。
• find_by_id(id)：根据 _id 查询题目。
• find_with_query_and_pagination(query, limit, skip)：条件分页查询题目。
• count_documents(query)：统计题目数量。

---

4. main.py

作用

实现基于 FastAPI 的后端接口路由，调用各 DAO 层方法，提供 RESTful API 服务，支持学生、教师、用户管理等功能。

主要内容与接口说明

4.1 学生相关接口

• 查询学生作业列表
  GET /dao/student/getHomeworkList?studentId=xxx
  查询指定学生的所有作业。

• 查询学生作业详情
  GET /dao/student/getHomework?studentHomeworkId=xxx
  查询某条学生作业的详细信息。

• 更新学生作业
  PUT /dao/student/updateHomework
  请求体：{id, status, scores, answers, analysis, recommendations}
  更新学生作业信息。

• 新建对话
  POST /dao/student/addDialog
  请求体：{studentId}
  新增一条对话历史。

• 修改对话
  PUT /dao/student/updateDialog
  请求体：{id, contents}
  更新对话内容。

• 查询对话列表
  GET /dao/student/getDialogList?studentId=xxx
  查询学生的所有对话历史。

• 查询单条对话
  GET /dao/student/getDialog?dialogId=xxx
  查询某条对话的详细内容。

• 查询学生所有老师
  GET /dao/student/getTeacherList?studentId=xxx
  查询该学生的所有老师。

4.2 教师相关接口

• 新增师生关系
  POST /dao/teacher/addStudentToTeacher
  请求体：{studentId, teacherId}
  将学生添加到教师名下。

• 删除师生关系
  DELETE /dao/teacher/deleteStudentFromTeacher?studentId=xxx&teacherId=xxx
  删除指定师生关系。

• 查询老师所有学生
  GET /dao/teacher/getStudentList?teacherId=xxx
  查询该老师的所有学生。

• 新增题目
  POST /dao/teacher/addQuestion
  请求体：{stem, type, options, correctAnswer, label}
  新增题目。

• 查询题目（分页、模糊）
  GET /dao/teacher/getQuestions?page=1&pageSize=10&stem=xxx&label=xxx
  查询题目列表，支持分页和模糊查询。

• 新增作业
  POST /dao/teacher/addHomework
  请求体：{teacherId, date, status, questions}
  新增作业并为所有学生生成作业记录。

• 查询老师所有作业
  GET /dao/teacher/getHomeworkList?teacherId=xxx
  查询该老师的所有作业。

• 查询作业详情
  GET /dao/teacher/getHomework?homeworkId=xxx
  查询作业详细信息（含题目）。

• 查询作业下所有学生作业
  GET /dao/teacher/getStudentHomeworkListByHomeworkId?homeworkId=xxx
  查询该作业下所有学生作业。

• 修改作业
  PUT /dao/teacher/updateHomework
  请求体：{id, teacherId, date, status, questions, analysis, statistics}
  更新作业信息。

• 删除作业
  DELETE /dao/teacher/deleteHomework?id=xxx
  删除指定作业及其学生作业。

4.3 用户管理接口

• 新增用户
  POST /dao/user
  请求体：{account, name, type, password}
  新增用户。

• 删除用户
  DELETE /dao/user?id=xxx
  删除用户及其相关数据。

• 查找用户
  GET /dao/user?id=xxx 或 GET /dao/user?account=xxx
  根据 id 或账号查找用户。

• 更新用户信息
  PUT /dao/user
  请求体：{id, name, type, password}
  更新用户信息。

• 查询全部用户
  GET /dao/user/getUserList
  查询所有用户。

4.4 返回格式

所有接口统一返回如下格式：

{"code": 0, "message": "提示信息","data": {} 
}

5. 数据模型说明

5.1 User 用户

{"_id": ObjectId,"account": String,    // 账号"name": String,       // 姓名"type": Number,       // 用户类型(0:学生, 1:教师)"password": String    // 密码
}

5.2 History 对话历史

{"_id": ObjectId,"studentId": ObjectId,  // 学生ID"time": DateTime,       // 创建时间"contents": Array      // 对话内容
}

5.3 Homework 作业

{"_id": ObjectId,"teacherId": ObjectId,  // 教师ID"date": {              // 作业时间"begin": String,     // 开始时间"end": String        // 结束时间},"status": Number,      // 作业状态(0:未发布, 1:已发布)"questions": Array,    // 题目ID列表"analysis": String,    // 作业分析"statistics": {        // 统计信息"average": Number,   // 平均分"mostIncorrects": Array  // 错误最多的题目}
}

5.4 StudentHomework 学生作业

{"_id": ObjectId,"studentId": ObjectId,  // 学生ID"homeworkId": ObjectId, // 作业ID"status": Number,       // 完成状态(0:未完成, 1:已完成)"scores": Array,        // 每题得分"answers": Array,       // 答案"analysis": String,     // 答案分析"recommendations": Array // 推荐练习
}

5.5 Question 题目

{"_id": ObjectId,"stem": String,        // 题干"type": Number,        // 题目类型"options": Array,      // 选项"correctAnswer": String,// 正确答案"label": String        // 标签
}

5.6 Teach 师生关系

{"_id": ObjectId,"studentId": ObjectId,  // 学生ID"teacherId": ObjectId   // 教师ID
}

6. 重要流程说明

6.1 删除用户相关联数据流程

当删除一个用户时，会触发以下级联删除：

1. 删除该用户的基本信息(User表)
2. 删除相关作业数据(Homework表)
3. 删除相关学生作业记录(StudentHomework表)
4. 删除相关师生关系(Teach表)
5. 删除相关对话历史(History表)

6.2 新增作业流程

1. 教师创建作业基本信息
2. 系统自动为该教师的所有学生创建对应的学生作业记录
3. 教师可选择发布或暂存作业

---

7. 详细接口参数说明

7.1 基础 DAO 方法参数说明

insert_one(data)

• 功能：插入单条数据
• 参数：
  • data: dict - 要插入的数据字典
• 返回：ObjectId - 插入数据的_id
• 示例：

data = {"name": "张三", "age": 18}
_id = dao.insert_one(data)

find_one(query)

• 功能：查询单条数据
• 参数：
  • query: dict - 查询条件
• 返回：dict/None - 查询结果或None
• 示例：

result = dao.find_one({"_id": ObjectId("xxx")})

find_many(query, skip=0, limit=100)

• 功能：查询多条数据
• 参数：
  • query: dict - 查询条件
  • skip: int - 跳过记录数
  • limit: int - 返回记录数
• 返回：list - 查询结果列表
• 示例：

results = dao.find_many({"age": {"$gt": 18}}, skip=10, limit=20)

7.2 业务实体关系图

7.3 主要业务流程详解

作业发布流程

1. 教师创建作业

   homework_id = homework_dao.add_homework(teacher_id, date, status, questions)
   

2. 系统查询该教师的所有学生

   students = teach_dao.find_student_by_teacher_id(teacher_id)
   

3. 为每个学生创建作业记录

   for student in students:student_homework_dao.add_student_homework(student_id, homework_id)
   

作业完成与批改流程

1. 学生提交作业

   student_homework_dao.update_student_homework(id=homework_id,status=1,  # 已完成answers=student_answers
   )
   

2. 系统自动评分

   scores = calculate_scores(student_answers, correct_answers)
   analysis = analyze_answers(student_answers, scores)
   recommendations = generate_recommendations(analysis)
   

3. 更新作业统计信息

   homework_dao.update_homework(id=homework_id,statistics={"average": calculate_average(scores),"mostIncorrects": find_most_incorrect_questions()}
   )