sm-quizzes-plugin/classes/review.go

package classes

// The owner's review queue of open answers: one service shared by the MCP
// review routes (/api/v1/quiz-reviews) and the admin "Do oceny" screen.
// Reviewers hold the golem15.quizzes.access_quizzes permission (D-13); the
// routes and the admin controller check it, this file trusts its caller.
//
// Every write runs in lagoon.Transaction on s.DB, so a Service whose DB is
// an outer transaction (an admin save) nests as a savepoint. A write locks
// the answer's attempt first, as grading does, recalculates a completed
// attempt and fires its events only after the commit (D-14).

import (
	"context"
	"errors"
	"slices"
	"strings"
	"time"

	"git.golem15.com/golem15/sm-quizzes-plugin/events"
	"git.golem15.com/golem15/sm-quizzes-plugin/models"
	"git.golem15.com/golem15/summercms/modules/lagoon"
	"gorm.io/gorm"
)

// Review status filters besides the grading statuses themselves.
const (
	// ReviewStatusOpen is every answer the owner has not reviewed yet:
	// pending, graded and failed. It is the default filter.
	ReviewStatusOpen = "open"
	// ReviewStatusAll lists every open answer, reviewed ones included.
	ReviewStatusAll = "all"
)

// ReviewExcerptRunes is how much of a student's text a queue row shows.
const ReviewExcerptRunes = 300

// ErrNoGraderScore is a confirm of an answer that has no grader score: it
// is pending or failed, so the owner sets the score instead.
var ErrNoGraderScore = errors.New("quizzes: the answer has no grader score to confirm")

// ReviewFilter narrows the review queue. Zero values do not filter; Status
// is one CheckReviewStatus accepts.
type ReviewFilter struct {
	QuizSlug  string
	Status    string
	UserID    uint
	AttemptID uint
}

// Reviewer is who reviews: a frontend user over MCP (UserID, the API
// token's user) or a backend administrator (AdminID). A zero id is stored
// as NULL (Pitfall 7: the two live in different tables).
type Reviewer struct {
	UserID  uint
	AdminID uint
}

func (r Reviewer) ids() (user, admin *uint) {
	if r.UserID != 0 {
		id := r.UserID
		user = &id
	}
	if r.AdminID != 0 {
		id := r.AdminID
		admin = &id
	}
	return user, admin
}

// unreviewedStatuses are the grading statuses the owner still has to act
// on.
func unreviewedStatuses() []string {
	return []string{models.GradingPending, models.GradingGraded, models.GradingFailed}
}

// CheckReviewStatus maps a status filter to the grading statuses to list:
// "" and open give pending, graded and failed, a grading status gives
// itself and all gives nil (no filter). Anything else is a problem naming
// the valid values.
func CheckReviewStatus(status string) ([]string, []string) {
	status = strings.TrimSpace(status)
	switch status {
	case "", ReviewStatusOpen:
		return unreviewedStatuses(), nil
	case ReviewStatusAll:
		return nil, nil
	}
	if slices.Contains(models.GradingStatuses, status) {
		return []string{status}, nil
	}
	return nil, []string{"status must be one of open, pending, graded, failed, reviewed, all"}
}

// ReviewRow is one open answer of the review queue. In a queue row Text is
// cut to ReviewExcerptRunes+1 runes, enough to tell that it was cut; the
// detail carries the whole text.
type ReviewRow struct {
	AnswerID           uint
	Status             string
	QuizID             uint
	QuizSlug           string
	QuizTitle          string
	QuizMode           string
	QuestionID         uint
	QuestionText       string
	QuestionPoints     int
	AttemptID          uint
	AttemptCompletedAt *time.Time
	UserID             uint
	Email              string
	Name               *string
	Surname            *string
	Text               string
	GraderPoints       *float64
	Points             float64
	GradedAt           *time.Time
	ReviewedAt         *time.Time
	UpdatedAt          time.Time
}

// ReviewDetail is one open answer with everything the owner reviews it
// against: the model answer and the rubric (owner-only), the grader's
// result or error and the review so far. MaxLength is the question's
// effective limit.
type ReviewDetail struct {
	ReviewRow
	AnswerText        *string
	Rubric            *string
	MaxLength         int
	Grader            *string
	GraderFeedback    *string
	GradingError      *string
	ReviewComment     *string
	GradingAttempts   int
	IsCorrect         bool
	ReviewedByUserID  *uint
	ReviewedByAdminID *uint
}

// reviewFromSQL joins an open answer to its question, attempt, quiz and
// student. Only open answers (a grading status) are in the queue.
const reviewFromSQL = `
FROM golem15_quizzes_attempt_answers aa
JOIN golem15_quizzes_questions q ON q.id = aa.question_id
JOIN golem15_quizzes_attempts a ON a.id = aa.attempt_id
JOIN golem15_quizzes_quizzes qz ON qz.id = a.quiz_id
JOIN users u ON u.id = a.user_id
WHERE aa.grading_status IS NOT NULL`

// reviewRowColumnsSQL are the columns of a ReviewRow but the text.
const reviewRowColumnsSQL = `aa.id AS answer_id, aa.grading_status AS status,
	qz.id AS quiz_id, qz.slug AS quiz_slug, qz.title AS quiz_title, qz.mode AS quiz_mode,
	q.id AS question_id, q.text AS question_text, q.points AS question_points,
	a.id AS attempt_id, a.completed_at AS attempt_completed_at,
	a.user_id AS user_id, COALESCE(u.email, '') AS email, u.name AS name, u.surname AS surname,
	aa.grader_points AS grader_points, aa.points AS points,
	aa.graded_at AS graded_at, aa.reviewed_at AS reviewed_at, aa.updated_at AS updated_at`

// reviewQueueSQL selects the queue rows; the filter predicates, the order
// and the page are appended as bound parameters.
const reviewQueueSQL = `SELECT ` + reviewRowColumnsSQL + `,
	LEFT(COALESCE(aa.text_answer, ''), 301) AS text` + reviewFromSQL

// reviewDetailSQL selects one open answer by id with the detail columns.
const reviewDetailSQL = `SELECT ` + reviewRowColumnsSQL + `,
	COALESCE(aa.text_answer, '') AS text,
	q.answer_text AS answer_text, q.rubric AS rubric, q.max_length AS max_length,
	aa.grader AS grader, aa.grader_feedback AS grader_feedback, aa.grading_error AS grading_error,
	aa.review_comment AS review_comment, aa.grading_attempts AS grading_attempts,
	aa.is_correct AS is_correct,
	aa.reviewed_by_user_id AS reviewed_by_user_id, aa.reviewed_by_admin_id AS reviewed_by_admin_id` +
	reviewFromSQL + ` AND aa.id = ?`

// reviewScan is what the review queries scan into.
type reviewScan struct {
	ReviewRow
	AnswerText        *string
	Rubric            *string
	MaxLength         *int
	Grader            *string
	GraderFeedback    *string
	GradingError      *string
	ReviewComment     *string
	GradingAttempts   int
	IsCorrect         bool
	ReviewedByUserID  *uint
	ReviewedByAdminID *uint
}

func (r reviewScan) detail() *ReviewDetail {
	maxLength := models.DefaultMaxLength
	if r.MaxLength != nil {
		maxLength = *r.MaxLength
	}
	return &ReviewDetail{
		ReviewRow:         r.ReviewRow,
		AnswerText:        r.AnswerText,
		Rubric:            r.Rubric,
		MaxLength:         maxLength,
		Grader:            r.Grader,
		GraderFeedback:    r.GraderFeedback,
		GradingError:      r.GradingError,
		ReviewComment:     r.ReviewComment,
		GradingAttempts:   r.GradingAttempts,
		IsCorrect:         r.IsCorrect,
		ReviewedByUserID:  r.ReviewedByUserID,
		ReviewedByAdminID: r.ReviewedByAdminID,
	}
}

// reviewWhere turns a filter into predicates appended to reviewFromSQL.
func reviewWhere(f ReviewFilter, statuses []string) (string, []any) {
	var b strings.Builder
	var args []any
	if statuses != nil {
		b.WriteString(" AND aa.grading_status IN ?")
		args = append(args, statuses)
	}
	if slug := strings.TrimSpace(f.QuizSlug); slug != "" {
		b.WriteString(" AND qz.slug = ?")
		args = append(args, slug)
	}
	if f.UserID != 0 {
		b.WriteString(" AND a.user_id = ?")
		args = append(args, f.UserID)
	}
	if f.AttemptID != 0 {
		b.WriteString(" AND aa.attempt_id = ?")
		args = append(args, f.AttemptID)
	}
	return b.String(), args
}

// ReviewQueue lists the open answers matching f, oldest change first, one
// page at a time (perPage 1..100, default 20), with the total count. An
// invalid status is a *ValidationError.
func (s *Service) ReviewQueue(ctx context.Context, f ReviewFilter, page, perPage int) ([]ReviewRow, int64, error) {
	statuses, problems := CheckReviewStatus(f.Status)
	if len(problems) > 0 {
		return nil, 0, &ValidationError{Problems: problems}
	}
	if page < 1 {
		page = 1
	}
	if perPage < 1 {
		perPage = 20
	}
	perPage = min(perPage, 100)
	where, args := reviewWhere(f, statuses)
	var total int64
	if err := s.db(ctx).Raw("SELECT COUNT(*)"+reviewFromSQL+where, args...).Scan(&total).Error; err != nil {
		return nil, 0, err
	}
	var scans []reviewScan
	q := reviewQueueSQL + where + " ORDER BY aa.updated_at ASC, aa.id ASC LIMIT ? OFFSET ?"
	if err := s.db(ctx).Raw(q, append(args, perPage, (page-1)*perPage)...).Scan(&scans).Error; err != nil {
		return nil, 0, err
	}
	out := make([]ReviewRow, 0, len(scans))
	for _, sc := range scans {
		out = append(out, sc.ReviewRow)
	}
	return out, total, nil
}

// ReviewItem loads one open answer with its detail. A missing answer, or
// one that is not an open answer, is ErrNotFound.
func (s *Service) ReviewItem(ctx context.Context, answerID uint) (*ReviewDetail, error) {
	return reviewItem(ctx, s.db(ctx), answerID)
}

func reviewItem(ctx context.Context, db *gorm.DB, answerID uint) (*ReviewDetail, error) {
	var scans []reviewScan
	if err := db.WithContext(ctx).Raw(reviewDetailSQL, answerID).Scan(&scans).Error; err != nil {
		return nil, err
	}
	if len(scans) == 0 {
		return nil, ErrNotFound
	}
	return scans[0].detail(), nil
}

// reviewTarget is an open answer loaded for a review write, with its
// question and its attempt (quiz set); the attempt row is locked.
type reviewTarget struct {
	Answer   models.AttemptAnswer
	Question models.Question
	Attempt  *models.Attempt
}

// lockReviewTarget locks the attempt of an open answer and reads the
// answer again under the lock, so a grading job or a re-answer cannot
// change it in between. A missing answer or attempt, or an answer that is
// not open, is ErrNotFound.
func lockReviewTarget(ctx context.Context, tx *gorm.DB, answerID uint) (*reviewTarget, error) {
	tx = tx.WithContext(ctx)
	var row models.AttemptAnswer
	if err := tx.Where("id = ? AND grading_status IS NOT NULL", answerID).Take(&row).Error; err != nil {
		return nil, notFound(err)
	}
	attempt, err := lockAttempt(ctx, tx, row.AttemptID)
	if err != nil {
		return nil, notFound(err)
	}
	if err := tx.Where("id = ? AND grading_status IS NOT NULL", answerID).Take(&row).Error; err != nil {
		return nil, notFound(err)
	}
	var quiz models.Quiz
	if err := tx.Where("id = ?", attempt.QuizID).Take(&quiz).Error; err != nil {
		return nil, notFound(err)
	}
	attempt.Quiz = &quiz
	var question models.Question
	if err := tx.Where("id = ?", row.QuestionID).Take(&question).Error; err != nil {
		return nil, notFound(err)
	}
	return &reviewTarget{Answer: row, Question: question, Attempt: attempt}, nil
}

// notFound maps gorm.ErrRecordNotFound to ErrNotFound.
func notFound(err error) error {
	if errors.Is(err, gorm.ErrRecordNotFound) {
		return ErrNotFound
	}
	return err
}

// Confirm makes the grader's score of a graded answer final: status
// reviewed, points = grader_points (D-12). A reviewed answer is returned
// unchanged, without a write or an event; a pending or failed answer has
// no score to confirm (ErrNoGraderScore). A completed attempt is
// recalculated, and AnswerReviewedEvent, plus AttemptReviewedEvent when
// the attempt is now fully reviewed, fire after the commit.
func (s *Service) Confirm(ctx context.Context, answerID uint, by Reviewer) (*ReviewDetail, error) {
	var detail *ReviewDetail
	err := lagoon.Transaction(ctx, s.DB, func(ctx context.Context, tx *gorm.DB) error {
		t, err := lockReviewTarget(ctx, tx, answerID)
		if err != nil {
			return err
		}
		if done, err := s.confirmTarget(ctx, tx, t, by); err != nil {
			return err
		} else if done {
			if err := s.recalcAttempt(ctx, tx, t.Attempt.ID); err != nil {
				return err
			}
			if err := s.fireAttemptReviewedIfDone(ctx, tx, t.Attempt.ID); err != nil {
				return err
			}
		}
		detail, err = reviewItem(ctx, tx, answerID)
		return err
	})
	if err != nil {
		return nil, err
	}
	return detail, nil
}

// confirmTarget confirms one locked answer and reports whether it wrote:
// false for a reviewed answer, ErrNoGraderScore without a grader score.
// The caller recalculates the attempt.
func (s *Service) confirmTarget(ctx context.Context, tx *gorm.DB, t *reviewTarget, by Reviewer) (bool, error) {
	status := ""
	if t.Answer.GradingStatus != nil {
		status = *t.Answer.GradingStatus
	}
	switch {
	case status == models.GradingReviewed:
		return false, nil
	case status != models.GradingGraded || t.Answer.GraderPoints == nil:
		return false, ErrNoGraderScore
	}
	return true, s.storeReview(ctx, tx, t, *t.Answer.GraderPoints, t.Answer.ReviewComment, false, by)
}

// storeReview writes the owner's decision on one locked open answer and
// registers its AnswerReviewedEvent. setComment replaces review_comment
// with comment (nil clears it); otherwise the comment stays. grader_points
// and grader_feedback stay for the record.
func (s *Service) storeReview(ctx context.Context, tx *gorm.DB, t *reviewTarget, points float64, comment *string, setComment bool, by Reviewer) error {
	now := s.now().UTC()
	user, admin := by.ids()
	cols := map[string]any{
		"grading_status":       models.GradingReviewed,
		"points":               points,
		"is_correct":           OpenCorrect(points, t.Question.Points),
		"reviewed_at":          now,
		"reviewed_by_user_id":  user,
		"reviewed_by_admin_id": admin,
		"updated_at":           now,
	}
	if setComment {
		cols["review_comment"] = comment
	} else {
		comment = t.Answer.ReviewComment
	}
	if err := tx.WithContext(ctx).Model(&models.AttemptAnswer{}).Where("id = ?", t.Answer.ID).Updates(cols).Error; err != nil {
		return err
	}
	fireAfterCommit(ctx, s, tx, events.AnswerReviewedEventName, &events.AnswerReviewedEvent{
		QuizID:          t.Attempt.QuizID,
		QuestionID:      t.Question.ID,
		AttemptID:       t.Attempt.ID,
		AnswerID:        t.Answer.ID,
		UserID:          t.Attempt.UserID,
		Points:          points,
		MaxPoints:       t.Question.Points,
		GraderPoints:    t.Answer.GraderPoints,
		Comment:         comment,
		ReviewerUserID:  user,
		ReviewerAdminID: admin,
	})
	return nil
}

// fireAttemptReviewedIfDone registers AttemptReviewedEvent for a completed
// attempt that has at least one open answer and none left pending, graded
// or failed, with the attempt's stored score; passed compares its percent
// with the quiz's passing score. Call it after the attempt is
// recalculated, inside the transaction that holds its lock. Without an
// event bus it reads nothing.
func (s *Service) fireAttemptReviewedIfDone(ctx context.Context, tx *gorm.DB, attemptID uint) error {
	if s == nil || s.Events == nil {
		return nil
	}
	tx = tx.WithContext(ctx)
	var a models.Attempt
	if err := tx.Preload("Quiz").Where("id = ?", attemptID).Take(&a).Error; err != nil {
		if errors.Is(err, gorm.ErrRecordNotFound) {
			return nil
		}
		return err
	}
	if a.CompletedAt == nil || a.Quiz == nil {
		return nil
	}
	counts, err := answerCounts(ctx, tx, []uint{attemptID})
	if err != nil {
		return err
	}
	if c := counts[attemptID]; c.OpenN == 0 || c.UnreviewedN > 0 {
		return nil
	}
	fireAfterCommit(ctx, s, tx, events.AttemptReviewedEventName, &events.AttemptReviewedEvent{
		QuizID:       a.QuizID,
		AttemptID:    a.ID,
		UserID:       a.UserID,
		ScorePoints:  a.ScorePoints,
		MaxPoints:    a.MaxPoints,
		ScorePercent: a.ScorePercent,
		Passed:       a.ScorePercent != nil && *a.ScorePercent >= float64(a.Quiz.PassingScore),
	})
	return nil
}