feat:add exam notice

Author: CutebreadCat

internal/course/service/exam_snapshot.go

@@ -33,6 +33,7 @@ type CourseExamInfo struct {
 }
 
 func buildCourseExamInfo(courses []*jwch.Course) []CourseExamInfo {
+	// 从选课接口结果中提取考试快照；没有考试时间的课程不参与考试通知。
 	exams := make([]CourseExamInfo, 0, len(courses))
 	for _, course := range courses {
 		if course == nil || strings.TrimSpace(course.RawExamTime) == "" {
@@ -46,6 +47,7 @@ func buildCourseExamInfo(courses []*jwch.Course) []CourseExamInfo {
 		})
 	}
 
+	// 统一考试快照的顺序，避免教务处返回顺序变化导致 hash 变化。
 	sort.Slice(exams, func(i, j int) bool {
 		left, right := courseExamIdentity(exams[i]), courseExamIdentity(exams[j])
 		if left != right {
@@ -71,6 +73,7 @@ type courseExamChange struct {
 }
 
 func buildCourseExamChanges(term string, oldExams, newExams []CourseExamInfo) []courseExamChange {
+	// 按课程身份比较新旧考试时间，支持考试新增、时间变更和考试信息清除。
 	oldByIdentity := make(map[string]CourseExamInfo, len(oldExams))
 	for _, exam := range oldExams {
 		oldByIdentity[courseExamIdentity(exam)] = exam
@@ -102,13 +105,15 @@ func buildCourseExamChanges(term string, oldExams, newExams []CourseExamInfo) []
 		}
 		changes = append(changes, newCourseExamChange(term, oldExam, newExam))
 	}
+	// map 遍历顺序不固定，排序后保证多条考试变化的处理顺序稳定。
 	sort.Slice(changes, func(i, j int) bool {
 		return changes[i].ExamHash < changes[j].ExamHash
 	})
 	return changes
 }
 
 func newCourseExamChange(term string, oldExam, newExam CourseExamInfo) courseExamChange {
+	// Hash 描述一次具体的考试状态迁移，用于跨用户全局去重。
 	examHash := utils.SHA256(strings.Join([]string{
 		newExam.Name,
 		term,
@@ -125,7 +130,9 @@ func newCourseExamChange(term string, oldExam, newExam CourseExamInfo) courseExa
 }
 
 func courseExamInfoHash(exams []CourseExamInfo) (string, error) {
+	// 快照 hash 只反映考试内容，不依赖教务处返回的课程排列顺序。
 	ordered := append([]CourseExamInfo(nil), exams...)
+	// 对副本排序，保证相同考试内容始终生成相同的快照 hash。
 	sort.Slice(ordered, func(i, j int) bool {
 		left, right := courseExamIdentity(ordered[i]), courseExamIdentity(ordered[j])
 		if left != right {

internal/course/service/get_course_list.go

@@ -174,6 +174,8 @@ func (s *CourseService) putCourseToDatabase(stuId string, term string, courses [
 }
 
 func (s *CourseService) putExamToDatabase(stuId string, term string, rawCourses []*jwch.Course) error {
+	// 考试通知采用“先抢占全局去重记录，再异步发送，成功后提交快照”的顺序。
+	// 发送或快照提交失败时释放去重记录，确保后续刷新仍然可以重试。
 	exams := buildCourseExamInfo(rawCourses)
 	examInfo, err := utils.JSONEncode(exams)
 	if err != nil {
@@ -205,21 +207,27 @@ func (s *CourseService) putExamToDatabase(stuId string, term string, rawCourses
 		}
 	}
 	if old.ExamInfoSHA256 == "" {
+		// 历史数据没有考试快照时只建立基线，不把已有考试信息当作新增变化通知。
 		return s.updateExamSnapshot(old.Id, examInfo, examInfoSHA256)
 	}
 
 	changes := buildCourseExamChanges(term, oldExams, exams)
 	if len(changes) == 0 {
+		// 内容没有实际变化时只更新快照，避免重复进入全局去重和推送流程。
 		return s.updateExamSnapshot(old.Id, examInfo, examInfoSHA256)
 	}
 
 	claimed := make([]courseExamChange, 0, len(changes))
 	for _, change := range changes {
+		// CreateExamOffering 依赖 exam_hash 唯一索引原子抢占发送资格。
+		// 返回 nil 表示其他用户已经处理过相同变化，本次不再重复推送。
 		offering, createErr := s.db.Course.CreateExamOffering(s.ctx, &model.ExamOffering{
 			ExamHash: change.ExamHash,
 			Tag:      change.Tag,
 		})
 		if createErr != nil {
+			// 本批次后续无法继续抢占时，释放已经抢到的去重记录。
+			// 否则这些考试变化虽然没有完成通知流程，却会被全局去重表永久拦截。
 			return errors.Join(createErr, s.releaseExamOfferings(claimed))
 		}
 		if offering != nil {
@@ -228,17 +236,26 @@ func (s *CourseService) putExamToDatabase(stuId string, term string, rawCourses
 	}
 
 	if len(claimed) == 0 {
+		// 所有变化都已被其他任务去重，本次只同步本地快照，不重复发送通知。
 		return s.updateExamSnapshot(old.Id, examInfo, examInfoSHA256)
 	}
+	// 去重记录已经抢占成功，但通知和快照更新放入同一个异步任务。
+	// 只有两步都成功，exam_offerings 记录才会继续保留。
 	if !umeng.EnqueueAsync(func() error {
 		if err := s.sendExamNotifications(claimed); err != nil {
+			// 推送失败时释放去重记录；考试快照也不会更新，后续刷新仍能识别到这次变化。
+			// 这样可以允许后续课程刷新重新抢占并重试通知。
 			return errors.Join(err, s.releaseExamOfferings(claimed))
 		}
 		if err := s.updateExamSnapshot(old.Id, examInfo, examInfoSHA256); err != nil {
+			// 快照更新失败时释放去重记录，避免通知状态未完整落库却被永久去重。
+			// 下次刷新会再次发现变化，并重新执行通知流程。
 			return errors.Join(err, s.releaseExamOfferings(claimed))
 		}
 		return nil
 	}) {
+		// 队列已满时任务没有进入异步流程，当前请求不会再发送这些通知。
+		// 因此需要释放已抢到的去重记录，避免这次未发送的变化无法重试。
 		return errors.Join(
 			errno.NewErrNo(errno.InternalQueueErrorCode, "service.putExamToDatabase: exam notification queue is full"),
 			s.releaseExamOfferings(claimed),
@@ -248,6 +265,7 @@ func (s *CourseService) putExamToDatabase(stuId string, term string, rawCourses
 }
 
 func (s *CourseService) updateExamSnapshot(id int64, examInfo, examInfoSHA256 string) error {
+	// 快照更新是本次考试变化处理的提交步骤；成功后下一次刷新不会再次识别同一变化。
 	_, err := s.db.Course.UpdateUserTermCourse(s.ctx, &model.UserCourse{
 		Id:             id,
 		ExamInfo:       examInfo,
@@ -257,8 +275,13 @@ func (s *CourseService) updateExamSnapshot(id int64, examInfo, examInfoSHA256 st
 }
 
 func (s *CourseService) releaseExamOfferings(changes []courseExamChange) error {
+	// exam_offerings 既是全局去重记录，也是本次通知流程的占位状态。
+	// 仅在发送或快照提交失败时调用，释放后下一次刷新可以重新抢占并重试。
 	var releaseErr error
 	for _, change := range changes {
+		// exam_offerings 记录表示本次变化已经被某个刷新任务抢占。
+		// 只有通知发送和考试快照更新都成功后才应保留；失败时删除该记录，
+		// 让后续刷新可以重新抢占，避免考试变化被错误地永久去重。
 		if err := s.db.Course.DeleteExamOfferingByHash(s.ctx, change.ExamHash); err != nil {
 			releaseErr = errors.Join(releaseErr, err)
 		}
@@ -267,6 +290,7 @@ func (s *CourseService) releaseExamOfferings(changes []courseExamChange) error {
 }
 
 func (s *CourseService) sendExamNotifications(changes []courseExamChange) error {
+	// 同一批变化同时发送 Android 和 iOS；记录首个错误，但继续处理剩余通知。
 	var firstErr error
 	for _, change := range changes {
 		title := fmt.Sprintf("%v考试信息更新啦", change.Exam.Name)

pkg/db/course/exam_offering.go

@@ -28,6 +28,7 @@ import (
 )
 
 func (c *DBCourse) GetExamOfferingByHash(ctx context.Context, examHash string) (*model.ExamOffering, error) {
+	// 查询全局考试变化是否已经被其他刷新任务占用。
 	offering := new(model.ExamOffering)
 	if err := c.client.WithContext(ctx).
 		Table(constants.ExamOfferingsTableName).
@@ -42,6 +43,7 @@ func (c *DBCourse) GetExamOfferingByHash(ctx context.Context, examHash string) (
 }
 
 func (c *DBCourse) CreateExamOffering(ctx context.Context, offering *model.ExamOffering) (*model.ExamOffering, error) {
+	// 依靠 exam_hash 唯一索引原子抢占发送资格；重复键表示已经被全局去重。
 	if err := c.client.WithContext(ctx).
 		Table(constants.ExamOfferingsTableName).
 		Create(offering).Error; err != nil {
@@ -54,6 +56,7 @@ func (c *DBCourse) CreateExamOffering(ctx context.Context, offering *model.ExamO
 }
 
 func (c *DBCourse) DeleteExamOfferingByHash(ctx context.Context, examHash string) error {
+	// 释放失败通知的全局去重记录，使用硬删除确保后续可以再次插入相同 hash。
 	if err := c.client.WithContext(ctx).
 		Table(constants.ExamOfferingsTableName).
 		Where("exam_hash = ?", examHash).