headless_lms_models/library/

progressing.rs

use chrono::{DateTime, Utc};
use itertools::Itertools;
use std::collections::{HashMap, HashSet};
use utoipa::ToSchema;

use crate::{
    course_exams,
    course_instance_enrollments::{self, NewCourseInstanceEnrollment},
    course_instances::{self, CourseInstance},
    course_module_completions::{
        self, CourseModuleCompletion, CourseModuleCompletionGranter,
        CourseModuleCompletionWithRegistrationInfo, NewCourseModuleCompletion,
    },
    course_modules::{self, AutomaticCompletionRequirements, CompletionPolicy, CourseModule},
    courses, exams,
    library::credit_registration::StudentFacingCreditRegistrationStatus,
    open_university_registration_links,
    prelude::*,
    suspected_cheaters, user_course_settings,
    user_details::UserDetail,
    user_exercise_states,
    users::{self, User},
};

/// Checks whether the course module can be completed automatically and creates an entry for completion
/// if the user meets the criteria. Also re-checks module completion prerequisites if the module is
/// completed.
pub async fn update_automatic_completion_status_and_grant_if_eligible(
    conn: &mut PgConnection,
    course_module: &CourseModule,
    user_id: Uuid,
) -> ModelResult<()> {
    let mut tx = conn.begin().await?;
    let completion =
        create_automatic_course_module_completion_if_eligible(&mut tx, course_module, user_id)
            .await?;
    if let Some(completion) = completion {
        let course = courses::get_course(&mut tx, course_module.course_id).await?;
        let submodule_completions_required = course
            .base_module_completion_requires_n_submodule_completions
            .try_into()?;
        update_module_completion_prerequisite_statuses_for_user(
            &mut tx,
            user_id,
            course_module.course_id,
            submodule_completions_required,
        )
        .await?;

        if course.cheater_detection_enabled {
            // Detection is on by default. When the course has no explicit threshold configured,
            // fall back to the default (3 hours).
            let threshold_seconds = suspected_cheaters::get_thresholds_by_module_id(
                &mut tx,
                completion.course_module_id,
            )
            .await?
            .map(|t| t.duration_seconds)
            .unwrap_or(suspected_cheaters::DEFAULT_CHEATER_THRESHOLD_SECONDS);
            // A threshold of 0 (or less) is the documented per-module off-switch for the duration
            // check. Only an explicitly configured 0 disables it -- the default fallback above is
            // always positive.
            if threshold_seconds > 0 {
                check_and_insert_suspected_cheaters(
                    &mut tx,
                    user_id,
                    course.id,
                    threshold_seconds,
                    completion,
                )
                .await?;
            }
        }
    }
    tx.commit().await?;
    Ok(())
}

pub async fn check_and_insert_suspected_cheaters(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_id: Uuid,
    threshold_seconds: i32,
    completion: CourseModuleCompletion,
) -> ModelResult<()> {
    // A teacher-granted (manual) completion means the teacher has vouched for the student, so they
    // are not subject to automatic cheating suspicion for this course.
    if course_module_completions::user_has_manual_completion_in_course(conn, user_id, course_id)
        .await?
    {
        return Ok(());
    }

    let total_points = user_exercise_states::get_user_total_course_points(conn, user_id, course_id)
        .await?
        .unwrap_or(0.0);

    let completed_module = course_modules::get_by_id(conn, completion.course_module_id).await?;
    let is_default_module = completed_module.is_default_module();

    let student_duration_seconds = if is_default_module {
        course_instances::get_student_duration(conn, completion.user_id, course_id)
            .await?
            .unwrap_or(0)
    } else {
        let default_module = course_modules::get_default_by_course_id(conn, course_id).await?;
        let default_completion = course_module_completions::get_all_by_course_module_and_user_ids(
            conn,
            default_module.id,
            completion.user_id,
        )
        .await?
        .into_iter()
        .max_by_key(|c| c.completion_date);

        if let Some(default_completion) = default_completion {
            let duration =
                (completion.completion_date - default_completion.completion_date).num_seconds();
            duration.max(0)
        } else {
            // No default completion exists yet, fall back to calculating duration from enrollment time.
            course_instances::get_student_duration(conn, completion.user_id, course_id)
                .await?
                .unwrap_or(0)
        }
    };

    if (student_duration_seconds as i32) < threshold_seconds {
        let suspicion_is_active = suspected_cheaters::insert(
            conn,
            completion.user_id,
            course_id,
            completion.course_module_id,
            Some(student_duration_seconds as i32),
            total_points as i32,
        )
        .await?;

        if suspicion_is_active {
            course_module_completions::update_needs_to_be_reviewed(conn, completion.id, true)
                .await?;
        }
    }

    Ok(())
}

/// Creates completion for the user if eligible and previous one doesn't exist. Returns an Option containing
/// the completion if one exists after calling this function.
#[instrument(skip(conn))]
async fn create_automatic_course_module_completion_if_eligible(
    conn: &mut PgConnection,
    course_module: &CourseModule,
    user_id: Uuid,
) -> ModelResult<Option<CourseModuleCompletion>> {
    let existing_completion =
        course_module_completions::get_automatic_completion_by_course_module_course_and_user_ids(
            conn,
            course_module.id,
            course_module.course_id,
            user_id,
        )
        .await
        .optional()?;
    if let Some(existing_completion) = existing_completion {
        // If user already has a completion, do not attempt to create a new one.
        Ok(Some(existing_completion))
    } else {
        let eligible =
            user_is_eligible_for_automatic_completion(conn, course_module, user_id).await?;
        if eligible {
            let course = courses::get_course(conn, course_module.course_id).await?;
            let user = users::get_by_id(conn, user_id).await?;
            if user.deleted_at.is_some() {
                warn!("Cannot create a completion for a deleted user");
                return Ok(None);
            }
            let user_details =
                crate::user_details::get_user_details_by_user_id(conn, user.id).await?;
            let completion = course_module_completions::insert(
                conn,
                PKeyPolicy::Generate,
                &NewCourseModuleCompletion {
                    course_id: course_module.course_id,
                    course_module_id: course_module.id,
                    user_id,
                    completion_date: Utc::now(),
                    completion_registration_attempt_date: None,
                    completion_language: course.language_code,
                    eligible_for_ects: true,
                    email: user_details.email,
                    grade: None,
                    passed: true,
                },
                CourseModuleCompletionGranter::Automatic,
            )
            .await?;
            info!("Created a completion");
            Ok(Some(completion))
        } else {
            // Can't grant automatic completion; no-op.
            Ok(None)
        }
    }
}

#[instrument(skip(conn))]
async fn user_is_eligible_for_automatic_completion(
    conn: &mut PgConnection,
    course_module: &CourseModule,
    user_id: Uuid,
) -> ModelResult<bool> {
    match &course_module.completion_policy {
        CompletionPolicy::Automatic(requirements) => {
            let eligible = user_passes_automatic_completion_exercise_tresholds(
                conn,
                user_id,
                requirements,
                course_module.course_id,
            )
            .await?;
            if eligible {
                // Do not grant an automatic completion while the user still has answers in this
                // module waiting for manual grading; a teacher must review them first.
                if user_exercise_states::has_pending_manual_reviews_in_module(
                    conn,
                    user_id,
                    course_module.course_id,
                    requirements.course_module_id,
                )
                .await?
                {
                    info!(
                        "The user has answers pending manual review in this module; not granting an automatic completion yet."
                    );
                    return Ok(false);
                }
                if requirements.requires_exam {
                    info!("To complete this module automatically, the user must pass an exam.");
                    user_has_passed_exam_for_the_course_based_on_points(
                        conn,
                        user_id,
                        course_module.course_id,
                    )
                    .await
                } else {
                    Ok(true)
                }
            } else {
                Ok(false)
            }
        }
        CompletionPolicy::Manual => Ok(false),
    }
}

/// Checks whether the student can partake in an exam.
///
/// The result of this process depends on the configuration for the exam. If the exam is not linked
/// to any course, the user will always be able to take it by default. Otherwise the student
/// progress in their current selected instances is compared against any of the linked courses, and
/// checked whether any pass the exercise completion tresholds. Finally, if none of the courses have
/// automatic completion configuration, the exam is once again allowed to be taken by default.
#[instrument(skip(conn))]
pub async fn user_can_take_exam(
    conn: &mut PgConnection,
    exam_id: Uuid,
    user_id: Uuid,
) -> ModelResult<bool> {
    let course_ids = course_exams::get_course_ids_by_exam_id(conn, exam_id).await?;
    let settings = user_course_settings::get_all_by_user_and_multiple_current_courses(
        conn,
        &course_ids,
        user_id,
    )
    .await?;
    // User can take the exam by default if course_ids is an empty array.
    let mut can_take_exam = true;
    for course_id in course_ids {
        let default_module = course_modules::get_default_by_course_id(conn, course_id).await?;
        if let CompletionPolicy::Automatic(requirements) = &default_module.completion_policy {
            if let Some(s) = settings.iter().find(|x| x.current_course_id == course_id) {
                let eligible = user_passes_automatic_completion_exercise_tresholds(
                    conn,
                    s.user_id,
                    requirements,
                    s.current_course_id,
                )
                .await?;
                if eligible {
                    // Only one current instance needs to pass the tresholds.
                    can_take_exam = true;
                    break;
                }
            }
            // If there is at least one associated course with requirements, make sure that the user
            // passes one of them.
            can_take_exam = false;
        }
    }
    Ok(can_take_exam)
}

/// Returns true if there is at least one exam associated with the course, that has ended and the
/// user has received enough points from it.
pub async fn user_has_passed_exam_for_the_course_based_on_points(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_id: Uuid,
) -> ModelResult<bool> {
    let now = Utc::now();
    let exam_ids = course_exams::get_exam_ids_by_course_id(conn, course_id).await?;
    for exam_id in exam_ids {
        let exam = exams::get(conn, exam_id).await?;
        // A minimum points threshold of 0 indicates that the "Related courses can be completed automatically" option has not been enabled by the teacher. If you wish to remove this condition, please first store this information in a separate column in the exams table.
        if exam.minimum_points_treshold == 0 || exam.grade_manually {
            continue;
        }
        if exam.ended_at_or(now, false) {
            let points =
                user_exercise_states::get_user_total_exam_points(conn, user_id, exam_id).await?;
            if let Some(points) = points
                && points >= exam.minimum_points_treshold as f32
            {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

async fn user_passes_automatic_completion_exercise_tresholds(
    conn: &mut PgConnection,
    user_id: Uuid,
    requirements: &AutomaticCompletionRequirements,
    course_id: Uuid,
) -> ModelResult<bool> {
    let user_metrics = user_exercise_states::get_single_module_metrics(
        conn,
        course_id,
        requirements.course_module_id,
        user_id,
    )
    .await?;
    let attempted_exercises: i32 = user_metrics.attempted_exercises.unwrap_or(0) as i32;
    let exercise_points = user_metrics.score_given.unwrap_or(0.0) as i32;
    let eligible = requirements.passes_exercise_tresholds(attempted_exercises, exercise_points);
    Ok(eligible)
}

/// Fetches all course module completions for the given user on the given course and updates the
/// prerequisite module completion statuses for any completions that are missing them.
#[instrument(skip(conn))]
async fn update_module_completion_prerequisite_statuses_for_user(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_id: Uuid,
    base_module_completion_requires_n_submodule_completions: u32,
) -> ModelResult<()> {
    let default_course_module = course_modules::get_default_by_course_id(conn, course_id).await?;
    let course_module_completions =
        course_module_completions::get_all_by_course_id_and_user_id(conn, course_id, user_id)
            .await?;
    let default_module_is_completed = course_module_completions
        .iter()
        .any(|x| x.course_module_id == default_course_module.id);
    let submodule_completions = course_module_completions
        .iter()
        .filter(|x| x.course_module_id != default_course_module.id)
        .unique_by(|x| x.course_module_id)
        .count();
    let enough_submodule_completions = submodule_completions
        >= base_module_completion_requires_n_submodule_completions.try_into()?;
    let completions_needing_processing: Vec<_> = course_module_completions
        .into_iter()
        .filter(|x| !x.prerequisite_modules_completed)
        .collect();
    for completion in completions_needing_processing {
        if completion.course_module_id == default_course_module.id {
            if enough_submodule_completions {
                course_module_completions::update_prerequisite_modules_completed(
                    conn,
                    completion.id,
                    true,
                )
                .await?;
            }
        } else if default_module_is_completed {
            course_module_completions::update_prerequisite_modules_completed(
                conn,
                completion.id,
                true,
            )
            .await?;
        }
    }
    Ok(())
}

/// Goes through all user on a course and grants completions where eligible.
#[instrument(skip(conn))]
pub async fn process_all_course_completions(
    conn: &mut PgConnection,
    course_id: Uuid,
) -> ModelResult<()> {
    info!("Reprocessing course completions");
    let course = courses::get_course(conn, course_id).await?;
    let submodule_completions_required = course
        .base_module_completion_requires_n_submodule_completions
        .try_into()?;
    let course_modules = course_modules::get_by_course_id(conn, course_id).await?;
    // If user has an user exercise state, they might have returned an exercise so we need to check whether they have completed modules.
    let users =
        crate::users::get_all_user_ids_with_user_exercise_states_on_course(conn, course_id).await?;
    info!(users = ?users.len(), course_modules = ?course_modules.len(), ?submodule_completions_required, "Completion reprocessing info");
    for course_module in course_modules.iter() {
        info!(?course_module, "Course module information");
    }
    let mut tx = conn.begin().await?;
    for user_id in users {
        let mut num_completions = 0;
        for course_module in course_modules.iter() {
            let completion = create_automatic_course_module_completion_if_eligible(
                &mut tx,
                course_module,
                user_id,
            )
            .await?;
            if completion.is_some() {
                num_completions += 1;
            }
        }
        if num_completions > 0 {
            update_module_completion_prerequisite_statuses_for_user(
                &mut tx,
                user_id,
                course_id,
                submodule_completions_required,
            )
            .await?;
        }
    }
    tx.commit().await?;
    info!("Reprocessing course module completions complete");
    Ok(())
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct CourseInstanceCompletionSummary {
    pub course_modules: Vec<CourseModule>,
    pub users_with_course_module_completions: Vec<UserWithModuleCompletions>,
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct UserWithModuleCompletions {
    pub completed_modules: Vec<CourseModuleCompletionWithRegistrationInfo>,
    pub email: String,
    pub first_name: Option<String>,
    pub last_name: Option<String>,
    pub user_id: Uuid,
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]

pub struct UserCourseModuleCompletion {
    pub course_module_id: Uuid,
    pub grade: Option<i32>,
    pub passed: bool,
}

impl From<CourseModuleCompletion> for UserCourseModuleCompletion {
    fn from(course_module_completion: CourseModuleCompletion) -> Self {
        Self {
            course_module_id: course_module_completion.course_module_id,
            grade: course_module_completion.grade,
            passed: course_module_completion.passed,
        }
    }
}

impl UserWithModuleCompletions {
    fn from_user_and_details(user: User, user_details: UserDetail) -> Self {
        Self {
            user_id: user.id,
            first_name: user_details.first_name,
            last_name: user_details.last_name,
            email: user_details.email,
            completed_modules: vec![],
        }
    }
}

pub async fn get_course_instance_completion_summary(
    conn: &mut PgConnection,
    course_instance: &CourseInstance,
) -> ModelResult<CourseInstanceCompletionSummary> {
    let course_modules = course_modules::get_by_course_id(conn, course_instance.course_id).await?;
    let users_with_course_module_completions_list =
        users::get_users_by_course_instance_enrollment(conn, course_instance.id).await?;
    let user_id_to_details_map = crate::user_details::get_users_details_by_user_id_map(
        conn,
        &users_with_course_module_completions_list,
    )
    .await?;
    let mut users_with_course_module_completions: HashMap<Uuid, UserWithModuleCompletions> =
        users_with_course_module_completions_list
            .into_iter()
            .filter_map(|o| {
                let details = user_id_to_details_map.get(&o.id);
                details.map(|details| (o, details))
            })
            .map(|u| {
                (
                    u.0.id,
                    UserWithModuleCompletions::from_user_and_details(u.0, u.1.clone()),
                )
            })
            .collect();
    let completions =
        course_module_completions::get_all_with_registration_information_by_course_instance_id(
            conn,
            course_instance.id,
            course_instance.course_id,
        )
        .await?;
    completions.into_iter().for_each(|x| {
        let user_with_completions = users_with_course_module_completions.get_mut(&x.user_id);
        if let Some(completion) = user_with_completions {
            completion.completed_modules.push(x);
        }
    });
    Ok(CourseInstanceCompletionSummary {
        course_modules,
        users_with_course_module_completions: users_with_course_module_completions
            .into_values()
            .collect(),
    })
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct TeacherManualCompletionRequest {
    pub course_module_id: Uuid,
    pub new_completions: Vec<TeacherManualCompletion>,
    pub skip_duplicate_completions: bool,
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct TeacherManualCompletion {
    pub user_id: Uuid,
    pub grade: Option<i32>,
    pub passed: bool,
    pub completion_date: Option<DateTime<Utc>>,
}

pub async fn add_manual_completions(
    conn: &mut PgConnection,
    completion_giver_user_id: Uuid,
    course_instance: &CourseInstance,
    manual_completion_request: &TeacherManualCompletionRequest,
) -> ModelResult<()> {
    let course_module =
        course_modules::get_by_id(conn, manual_completion_request.course_module_id).await?;
    if course_module.course_id != course_instance.course_id {
        return Err(ModelError::new(
            ModelErrorType::PreconditionFailed,
            "Course module not part of the course.".to_string(),
            None,
        ));
    }
    let course = courses::get_course(conn, course_instance.course_id).await?;
    let mut tx = conn.begin().await?;
    for completion in manual_completion_request.new_completions.iter() {
        let completion_receiver = users::get_by_id(&mut tx, completion.user_id).await?;
        let completion_receiver_user_details =
            crate::user_details::get_user_details_by_user_id(&mut tx, completion_receiver.id)
                .await?;
        let module_completed = course_module_completions::user_has_completed_course_module(
            &mut tx,
            completion.user_id,
            manual_completion_request.course_module_id,
        )
        .await?;
        if !module_completed || !manual_completion_request.skip_duplicate_completions {
            course_instance_enrollments::insert_enrollment_if_it_doesnt_exist(
                &mut tx,
                NewCourseInstanceEnrollment {
                    user_id: completion_receiver.id,
                    course_id: course.id,
                    course_instance_id: course_instance.id,
                },
            )
            .await?;

            if completion.grade.is_some()
                && (completion.grade > Some(5) || completion.grade < Some(0))
            {
                return Err(ModelError::new(
                    ModelErrorType::PreconditionFailed,
                    "Invalid grade".to_string(),
                    None,
                ));
            }
            course_module_completions::insert(
                &mut tx,
                PKeyPolicy::Generate,
                &NewCourseModuleCompletion {
                    course_id: course_instance.course_id,
                    course_module_id: manual_completion_request.course_module_id,
                    user_id: completion.user_id,
                    completion_date: completion.completion_date.unwrap_or_else(Utc::now),
                    completion_registration_attempt_date: None,
                    completion_language: course.language_code.clone(),
                    eligible_for_ects: true,
                    email: completion_receiver_user_details.email,
                    grade: completion.grade,
                    passed: if completion.grade == Some(0) {
                        false
                    } else {
                        completion.passed
                    },
                },
                CourseModuleCompletionGranter::User(completion_giver_user_id),
            )
            .await?;

            // User may not have enrolled to the course at all, or they may have enrolled to a different instance. By inserting the enrollment
            crate::course_instance_enrollments::insert_enrollment_and_set_as_current(
                &mut tx,
                NewCourseInstanceEnrollment {
                    user_id: completion_receiver.id,
                    course_id: course.id,
                    course_instance_id: course_instance.id,
                },
            )
            .await?;

            update_module_completion_prerequisite_statuses_for_user(
                &mut tx,
                completion_receiver.id,
                course.id,
                course
                    .base_module_completion_requires_n_submodule_completions
                    .try_into()?,
            )
            .await?;
        }

        // Adding a manual completion vouches for the student, so any cheating suspicion for this
        // course (flagged or confirmed) is cleared and any grade a confirmation had failed is
        // restored. This runs regardless of `skip_duplicate_completions` (a teacher vouching for an
        // already-completed student should still clear the flag) and regardless of the completion's
        // grade (recording any manual completion defers the decision to the teacher). The existence
        // check is needed because `dismiss_...` errors when no suspicion row exists.
        if suspected_cheaters::get_by_user_id_and_course_id(&mut tx, completion.user_id, course.id)
            .await
            .optional()?
            .is_some()
        {
            suspected_cheaters::dismiss_by_user_id_and_course_id(
                &mut tx,
                completion.user_id,
                course.id,
            )
            .await?;
        }
    }
    tx.commit().await?;
    Ok(())
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct ManualCompletionPreview {
    pub already_completed_users: Vec<ManualCompletionPreviewUser>,
    pub first_time_completing_users: Vec<ManualCompletionPreviewUser>,
    pub non_enrolled_users: Vec<ManualCompletionPreviewUser>,
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]

pub struct ManualCompletionPreviewUser {
    pub user_id: Uuid,
    pub first_name: Option<String>,
    pub last_name: Option<String>,
    pub grade: Option<i32>,
    pub passed: bool,
    pub previous_best_grade: Option<i32>,
}

/// Gets a preview of changes that will occur to completions with the given manual completion data.
pub async fn get_manual_completion_result_preview(
    conn: &mut PgConnection,
    course_instance: &CourseInstance,
    manual_completion_request: &TeacherManualCompletionRequest,
) -> ModelResult<ManualCompletionPreview> {
    let course_module =
        course_modules::get_by_id(conn, manual_completion_request.course_module_id).await?;
    if course_module.course_id != course_instance.course_id {
        return Err(ModelError::new(
            ModelErrorType::PreconditionFailed,
            "Course module not part of the course.".to_string(),
            None,
        ));
    }
    let mut already_completed_users = vec![];
    let mut first_time_completing_users = vec![];
    let mut non_enrolled_users = vec![];
    for completion in manual_completion_request.new_completions.iter() {
        let user = users::get_by_id(conn, completion.user_id).await?;
        let user_details = crate::user_details::get_user_details_by_user_id(conn, user.id).await?;
        let user = ManualCompletionPreviewUser {
            user_id: user.id,
            first_name: user_details.first_name,
            last_name: user_details.last_name,
            grade: completion.grade,
            passed: completion.passed,
            previous_best_grade: None,
        };
        let enrollment = course_instance_enrollments::get_by_user_and_course_instance_id(
            conn,
            completion.user_id,
            course_instance.id,
        )
        .await
        .optional()?;
        if enrollment.is_none() {
            non_enrolled_users.push(user.clone());
        }
        let module_completed = course_module_completions::user_has_completed_course_module(
            conn,
            completion.user_id,
            manual_completion_request.course_module_id,
        )
        .await?;
        if module_completed {
            already_completed_users.push(user);
        } else {
            first_time_completing_users.push(user);
        }
    }
    Ok(ManualCompletionPreview {
        already_completed_users,
        first_time_completing_users,
        non_enrolled_users,
    })
}

#[derive(Clone, PartialEq, Deserialize, Serialize, utoipa::ToSchema)]

pub struct UserCompletionInformation {
    pub course_module_completion_id: Uuid,
    /// The course's own name, never the module's; the module is named by `course_module_name`.
    pub course_name: String,
    /// The module's own name, `None` on a course's default module.
    pub course_module_name: Option<String>,
    /// `None` only on a module registering through credit registration.
    pub uh_course_code: Option<String>,
    pub email: String,
    pub ects_credits: Option<f32>,
    pub enable_registering_completion_to_uh_open_university: bool,
    pub enable_credit_registration_via_suotar: bool,
    /// Whether this completion in particular goes through the push path. Decides which flow the
    /// page shows: the module flag above only says the module takes part.
    pub register_credits_via_suotar: bool,
    /// What the student is told while the completion has no credit registration: `sending` when
    /// the push path will create one, `not_registering` when it never will.
    pub status_before_registration: StudentFacingCreditRegistrationStatus,
    /// `Some` only when the student can generate a certificate for this module right now, which is
    /// also the id `/generate-certificate` wants.
    ///
    /// Read off the same completion as the rest of this object, the one
    /// [`course_module_completions::select_registration_completion`] picks. The course page's
    /// congratulations card reads off the best one instead, so a student whose registration
    /// completion is not their best can see a certificate there and none here.
    pub certificate_configuration_id: Option<Uuid>,
    /// Why the student said they need the credits rather than a certificate, if they have been
    /// asked and answered. Advisory; it seeds the field when they come back to the page.
    pub credit_justification: Option<String>,
}

/// The default certificate configuration a completion of this module alone earns.
///
/// `configurations` must come from
/// [`crate::certificate_configurations::get_default_certificate_configurations_and_requirements_by_course`],
/// which has already dropped the configurations that require more than one module; a configuration
/// merely naming this module among several is not one this module satisfies.
fn default_certificate_configuration_id_for_module(
    configurations: &[crate::certificate_configurations::CertificateConfigurationAndRequirements],
    course_module_id: Uuid,
) -> Option<Uuid> {
    configurations
        .iter()
        .find(|configuration| {
            configuration
                .requirements
                .course_module_ids
                .contains(&course_module_id)
        })
        .map(|configuration| configuration.certificate_configuration.id)
}

pub async fn get_user_completion_information(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_module: &CourseModule,
) -> ModelResult<UserCompletionInformation> {
    let user = users::get_by_id(conn, user_id).await?;
    let course = courses::get_course(conn, course_module.course_id).await?;
    let course_module_completion =
        course_module_completions::get_registration_completion_by_user_and_course_module_id(
            conn,
            user.id,
            course_module.id,
        )
        .await?;
    let credit_registration_config =
        course_modules::get_credit_registration_config(conn, course_module.id).await?;
    // The push path explains a missing course code on its own status page, so failing here would
    // hide the error instead of showing it.
    if course_module.uh_course_code.is_none()
        && !course_module_completion.register_credits_via_suotar
    {
        return Err(ModelError::new(
            ModelErrorType::InvalidRequest,
            "Course module is missing uh_course_code.".to_string(),
            None,
        ));
    }
    // A completion still awaiting review is treated as if it were not there, so a flagged student
    // cannot read their own flag off the certificate the page would otherwise offer them.
    let certificate_configuration_id = if course_module.certification_enabled
        && course_module_completion.passed
        && !course_module_completion.needs_to_be_reviewed
    {
        let configurations = crate::certificate_configurations::get_default_certificate_configurations_and_requirements_by_course(
            conn,
            course_module.course_id,
        )
        .await?;
        let configuration_id =
            default_certificate_configuration_id_for_module(&configurations, course_module.id);
        if configuration_id.is_none() {
            debug!(
                course_module_id = ?course_module.id,
                "Certification is enabled for the module but no default certificate configuration names it, so the student is offered no certificate."
            );
        }
        configuration_id
    } else {
        None
    };
    let credit_justification =
        crate::completion_registration_credit_justifications::get_by_completion_id(
            conn,
            course_module_completion.id,
        )
        .await?
        .map(|row| row.justification);
    let status_before_registration =
        if course_module_completions::get_credit_registration_expected_ids(
            conn,
            &[course_module_completion.id],
        )
        .await?
        .is_empty()
        {
            StudentFacingCreditRegistrationStatus::NotRegistering
        } else {
            StudentFacingCreditRegistrationStatus::Sending
        };
    Ok(UserCompletionInformation {
        course_module_completion_id: course_module_completion.id,
        course_name: course.name.clone(),
        course_module_name: course_module.name.clone(),
        uh_course_code: course_module.uh_course_code.clone(),
        ects_credits: course_module.ects_credits,
        email: course_module_completion.email,
        enable_registering_completion_to_uh_open_university: course_module
            .enable_registering_completion_to_uh_open_university,
        enable_credit_registration_via_suotar: credit_registration_config
            .enable_credit_registration_via_suotar,
        register_credits_via_suotar: course_module_completion.register_credits_via_suotar,
        status_before_registration,
        certificate_configuration_id,
        credit_justification,
    })
}

#[derive(Clone, PartialEq, Deserialize, Serialize, ToSchema)]

pub struct UserModuleCompletionStatus {
    pub completed: bool,
    pub default: bool,
    pub module_id: Uuid,
    pub name: String,
    pub order_number: i32,
    pub prerequisite_modules_completed: bool,
    pub grade: Option<i32>,
    pub passed: Option<bool>,
    pub enable_registering_completion_to_uh_open_university: bool,
    pub enable_credit_registration_via_suotar: bool,
    /// Whether the module's registration flow is the push path, decided by
    /// [`course_module_completions::select_registration_completion`] rather than by the shown
    /// completion. False when no completion is shown.
    pub register_credits_via_suotar: bool,
    pub certification_enabled: bool,
    pub certificate_configuration_id: Option<Uuid>,
}

/// Gets course modules with user's completion status for the given instance.
pub async fn get_user_module_completion_statuses_for_course(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_id: Uuid,
) -> ModelResult<Vec<UserModuleCompletionStatus>> {
    let course = courses::get_course(conn, course_id).await?;
    let course_modules = course_modules::get_by_course_id(conn, course_id).await?;

    let course_module_completions_raw =
        course_module_completions::get_all_by_course_id_and_user_id(conn, course_id, user_id)
            .await?;

    let completions_by_module: HashMap<Uuid, Vec<CourseModuleCompletion>> =
        course_module_completions_raw
            .into_iter()
            .into_group_map_by(|c| c.course_module_id);
    // A completion that still needs review (e.g. because the student was auto-flagged as a
    // suspected cheater) is hidden from the student, as if it did not exist yet, so a flagged
    // student cannot infer from the API that they are under suspicion.
    let best_visible_completions: HashMap<Uuid, CourseModuleCompletion> = completions_by_module
        .iter()
        .filter_map(|(module_id, completions)| {
            course_module_completions::select_best_completion(
                completions.iter().filter(|c| !c.needs_to_be_reviewed),
            )
            .map(|best| (*module_id, best.clone()))
        })
        .collect();
    let registers_via_suotar_module_ids: HashSet<Uuid> = completions_by_module
        .into_iter()
        .filter_map(|(module_id, completions)| {
            course_module_completions::select_registration_completion(completions)
                .filter(|c| c.register_credits_via_suotar)
                .map(|_| module_id)
        })
        .collect();

    let all_default_certificate_configurations = crate::certificate_configurations::get_default_certificate_configurations_and_requirements_by_course(conn, course_id).await?;

    let credit_registration_enabled_module_ids: HashSet<Uuid> =
        course_modules::get_credit_registration_enabled_ids_for_course(conn, course_id)
            .await?
            .into_iter()
            .collect();

    let course_module_completion_statuses = course_modules
        .into_iter()
        .map(|module| {
            let completion = best_visible_completions.get(&module.id);
            let passed = completion.map(|x| x.passed);
            let certificate_configuration_id =
                if module.certification_enabled && passed == Some(true) {
                    default_certificate_configuration_id_for_module(
                        &all_default_certificate_configurations,
                        module.id,
                    )
                } else {
                    None
                };
            UserModuleCompletionStatus {
                completed: completion.is_some(),
                default: module.is_default_module(),
                module_id: module.id,
                name: module.name.unwrap_or_else(|| course.name.clone()),
                order_number: module.order_number,
                passed,
                grade: completion.and_then(|x| x.grade),
                prerequisite_modules_completed: completion
                    .is_some_and(|x| x.prerequisite_modules_completed),
                enable_registering_completion_to_uh_open_university: module
                    .enable_registering_completion_to_uh_open_university,
                enable_credit_registration_via_suotar: credit_registration_enabled_module_ids
                    .contains(&module.id),
                register_credits_via_suotar: completion.is_some()
                    && registers_via_suotar_module_ids.contains(&module.id),
                certification_enabled: module.certification_enabled,
                certificate_configuration_id,
            }
        })
        .collect();
    Ok(course_module_completion_statuses)
}

#[derive(Clone, PartialEq, Deserialize, Serialize, utoipa::ToSchema)]

pub struct CompletionRegistrationLink {
    pub url: String,
}

pub async fn get_completion_registration_link_and_save_attempt(
    conn: &mut PgConnection,
    user_id: Uuid,
    course_module: &CourseModule,
) -> ModelResult<CompletionRegistrationLink> {
    if !course_module.enable_registering_completion_to_uh_open_university {
        return Err(ModelError::new(
            ModelErrorType::InvalidRequest,
            "Completion registration is not enabled for this course module.".to_string(),
            None,
        ));
    }
    let user = users::get_by_id(conn, user_id).await?;

    let course_module_completion =
        course_module_completions::get_registration_completion_by_user_and_course_module_id(
            conn,
            user.id,
            course_module.id,
        )
        .await?;
    // Same condition as the registration page's choice of flow.
    if course_module.enable_credit_registration_via_suotar
        && course_module_completion.register_credits_via_suotar
    {
        return Err(model_err!(
            InvalidRequest,
            "This completion is registered through the study registry.".to_string()
        ));
    }
    course_module_completions::update_completion_registration_attempt_date(
        conn,
        course_module_completion.id,
        Utc::now(),
    )
    .await?;
    let registration_link = if let Some(link_override) = course_module
        .completion_registration_link_override
        .as_deref()
        .map(str::trim)
        .filter(|link| !link.is_empty())
    {
        link_override.to_owned()
    } else {
        let uh_course_code = course_module.uh_course_code.clone().ok_or_else(|| {
            ModelError::new(
                ModelErrorType::PreconditionFailed,
                "Course module doesn't have an assossiated University of Helsinki course code."
                    .to_string(),
                None,
            )
        })?;
        open_university_registration_links::get_link_by_course_code(conn, &uh_course_code).await?
    };

    Ok(CompletionRegistrationLink {
        url: registration_link,
    })
}

#[cfg(test)]
mod tests {
    use chrono::Duration;
    use user_exercise_states::{ReviewingStage, UserExerciseStateUpdate};

    use super::*;

    use crate::{
        exercises::{ActivityProgress, GradingProgress},
        suspected_cheaters::SuspectedCheaterStatus,
        test_helper::*,
    };

    mod user_completion_information {
        use super::*;
        use crate::{
            certificate_configuration_to_requirements,
            certificate_configurations::{self, DatabaseCertificateConfiguration},
            file_uploads,
        };

        const UH_COURSE_CODE: &str = "TKT00000";

        /// A module the old registration page can actually be opened for: it needs a course code,
        /// and the certificate the detour offers needs certification switched on.
        async fn registrable_module(
            conn: &mut PgConnection,
            course_module_id: Uuid,
            certification_enabled: bool,
        ) -> CourseModule {
            course_modules::update_certification_enabled(
                conn,
                course_module_id,
                certification_enabled,
            )
            .await
            .unwrap();
            course_modules::update_uh_course_code(
                conn,
                course_module_id,
                Some(UH_COURSE_CODE.to_string()),
            )
            .await
            .unwrap()
        }

        async fn complete(
            conn: &mut PgConnection,
            course_id: Uuid,
            course_module_id: Uuid,
            user_id: Uuid,
            passed: bool,
        ) -> CourseModuleCompletion {
            course_module_completions::insert(
                conn,
                PKeyPolicy::Generate,
                &NewCourseModuleCompletion {
                    course_id,
                    course_module_id,
                    user_id,
                    completion_date: Utc::now(),
                    completion_registration_attempt_date: None,
                    completion_language: "en-US".to_string(),
                    eligible_for_ects: true,
                    email: "student@example.com".to_string(),
                    grade: None,
                    passed,
                },
                CourseModuleCompletionGranter::Automatic,
            )
            .await
            .unwrap()
        }

        /// A certificate configuration requiring exactly the given modules. One module makes it a
        /// default configuration; more than one makes it the kind no single module earns.
        async fn certificate_configuration_requiring(
            conn: &mut PgConnection,
            course_module_ids: &[Uuid],
        ) -> Uuid {
            let background_svg_file_upload_id = file_uploads::insert(
                conn,
                "background.svg",
                "certificates/background.svg",
                "image/svg+xml",
                None,
                None,
            )
            .await
            .unwrap();
            let configuration = certificate_configurations::insert(
                conn,
                &DatabaseCertificateConfiguration {
                    id: Uuid::new_v4(),
                    certificate_owner_name_y_pos: None,
                    certificate_owner_name_x_pos: None,
                    certificate_owner_name_font_size: None,
                    certificate_owner_name_text_color: None,
                    certificate_owner_name_text_anchor: None,
                    certificate_validate_url_y_pos: None,
                    certificate_validate_url_x_pos: None,
                    certificate_validate_url_font_size: None,
                    certificate_validate_url_text_color: None,
                    certificate_validate_url_text_anchor: None,
                    certificate_date_y_pos: None,
                    certificate_date_x_pos: None,
                    certificate_date_font_size: None,
                    certificate_date_text_color: None,
                    certificate_date_text_anchor: None,
                    certificate_locale: None,
                    paper_size: None,
                    background_svg_path: "certificates/background.svg".to_string(),
                    background_svg_file_upload_id,
                    overlay_svg_path: None,
                    overlay_svg_file_upload_id: None,
                    render_certificate_grade: false,
                    certificate_grade_y_pos: None,
                    certificate_grade_x_pos: None,
                    certificate_grade_font_size: None,
                    certificate_grade_text_color: None,
                    certificate_grade_text_anchor: None,
                },
            )
            .await
            .unwrap();
            for course_module_id in course_module_ids {
                certificate_configuration_to_requirements::insert(
                    conn,
                    configuration.id,
                    Some(*course_module_id),
                )
                .await
                .unwrap();
            }
            configuration.id
        }

        #[tokio::test]
        async fn offers_the_certificate_a_passed_completion_has_earned() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, true).await;
            complete(tx.as_mut(), course, module.id, user, true).await;
            let configuration_id =
                certificate_configuration_requiring(tx.as_mut(), &[module.id]).await;

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(
                information.certificate_configuration_id,
                Some(configuration_id)
            );
        }

        #[tokio::test]
        async fn offers_no_certificate_when_the_module_has_certification_off() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, false).await;
            complete(tx.as_mut(), course, module.id, user, true).await;
            certificate_configuration_requiring(tx.as_mut(), &[module.id]).await;

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(information.certificate_configuration_id, None);
        }

        #[tokio::test]
        async fn offers_no_certificate_for_a_failed_completion() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, true).await;
            complete(tx.as_mut(), course, module.id, user, false).await;
            certificate_configuration_requiring(tx.as_mut(), &[module.id]).await;

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(information.certificate_configuration_id, None);
        }

        #[tokio::test]
        async fn offers_no_certificate_while_the_completion_is_under_review() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, true).await;
            let completion = complete(tx.as_mut(), course, module.id, user, true).await;
            certificate_configuration_requiring(tx.as_mut(), &[module.id]).await;
            course_module_completions::update_needs_to_be_reviewed(
                tx.as_mut(),
                completion.id,
                true,
            )
            .await
            .unwrap();

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(information.certificate_configuration_id, None);
        }

        #[tokio::test]
        async fn offers_no_certificate_this_module_alone_does_not_earn() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, true).await;
            let other_module = course_modules::get_default_by_course_id(tx.as_mut(), course)
                .await
                .unwrap();
            complete(tx.as_mut(), course, module.id, user, true).await;
            certificate_configuration_requiring(tx.as_mut(), &[module.id, other_module.id]).await;

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(information.certificate_configuration_id, None);
        }

        #[tokio::test]
        async fn carries_back_the_answer_the_student_already_gave() {
            insert_data!(:tx, :user, :org, :course, instance: _instance, :course_module);
            let module = registrable_module(tx.as_mut(), course_module.id, true).await;
            let completion = complete(tx.as_mut(), course, module.id, user, true).await;
            crate::completion_registration_credit_justifications::upsert(
                tx.as_mut(),
                completion.id,
                user,
                "My employer needs them in the registry.",
            )
            .await
            .unwrap();

            let information = get_user_completion_information(tx.as_mut(), user, &module)
                .await
                .unwrap();

            assert_eq!(
                information.credit_justification.as_deref(),
                Some("My employer needs them in the registry.")
            );
        }
    }

    mod grant_automatic_completion_if_eligible {
        use super::*;
        use crate::{
            chapters::NewChapter,
            course_modules::{
                self, AutomaticCompletionRequirements, CompletionPolicy, NewCourseModule,
            },
            exercises::{self, ActivityProgress, GradingProgress},
            library::content_management,
            user_exercise_states::{self, ReviewingStage, UserExerciseStateUpdate},
        };

        #[tokio::test]
        async fn grants_automatic_completion_but_no_prerequisite_for_default_module() {
            insert_data!(:tx);
            let (mut tx, user, course, _instance, default_module, _submodule_1, _submodule_2) =
                create_test_data(tx).await;
            update_automatic_completion_status_and_grant_if_eligible(
                tx.as_mut(),
                &default_module,
                user,
            )
            .await
            .unwrap();
            let statuses =
                get_user_module_completion_statuses_for_course(tx.as_mut(), user, course)
                    .await
                    .unwrap();
            let status = statuses
                .iter()
                .find(|x| x.module_id == default_module.id)
                .unwrap();
            assert!(status.completed);
            assert!(!status.prerequisite_modules_completed);
        }

        #[tokio::test]
        async fn grants_automatic_completion_but_no_prerequisite_for_submodule() {
            insert_data!(:tx);
            let (mut tx, user, course, _instance, _default_module, submodule_1, _submodule_2) =
                create_test_data(tx).await;
            update_automatic_completion_status_and_grant_if_eligible(
                tx.as_mut(),
                &submodule_1,
                user,
            )
            .await
            .unwrap();
            let statuses =
                get_user_module_completion_statuses_for_course(tx.as_mut(), user, course)
                    .await
                    .unwrap();
            let status = statuses
                .iter()
                .find(|x| x.module_id == submodule_1.id)
                .unwrap();
            assert!(status.completed);
            assert!(!status.prerequisite_modules_completed);
        }

        #[tokio::test]
        async fn grants_automatic_completion_for_eligible_submodule_when_completing_default_module()
        {
            insert_data!(:tx);
            let (mut tx, user, course, _instance, default_module, submodule_1, submodule_2) =
                create_test_data(tx).await;
            update_automatic_completion_status_and_grant_if_eligible(
                tx.as_mut(),
                &default_module,
                user,
            )
            .await
            .unwrap();
            update_automatic_completion_status_and_grant_if_eligible(
                tx.as_mut(),
                &submodule_1,
                user,
            )
            .await
            .unwrap();
            update_automatic_completion_status_and_grant_if_eligible(
                tx.as_mut(),
                &submodule_2,
                user,
            )
            .await
            .unwrap();
            let statuses =
                get_user_module_completion_statuses_for_course(tx.as_mut(), user, course)
                    .await
                    .unwrap();
            statuses.iter().for_each(|x| {
                assert!(x.completed);
                assert!(x.prerequisite_modules_completed);
            });
        }

        async fn create_test_data(
            mut tx: Tx<'_>,
        ) -> (
            Tx<'_>,
            Uuid,
            Uuid,
            Uuid,
            CourseModule,
            CourseModule,
            CourseModule,
        ) {
            insert_data!(tx: tx; :user, :org, :course, :instance, :course_module, :chapter, :page, :exercise);
            // These tests complete modules instantly, which would trip suspected-cheater detection
            // (on by default) and hide the completion. Detection is exercised by its own tests, so
            // disable it here to test automatic-completion granting in isolation.
            courses::set_cheater_detection_enabled(tx.as_mut(), course, false)
                .await
                .unwrap();
            let automatic_completion_policy =
                CompletionPolicy::Automatic(AutomaticCompletionRequirements {
                    course_module_id: course_module.id,
                    number_of_exercises_attempted_treshold: Some(0),
                    number_of_points_treshold: Some(0),
                    requires_exam: false,
                });
            courses::update_course_base_module_completion_count_requirement(tx.as_mut(), course, 1)
                .await
                .unwrap();
            let course_module_2 = course_modules::insert(
                tx.as_mut(),
                PKeyPolicy::Generate,
                &NewCourseModule::new(course, Some("Module 2".to_string()), 1),
            )
            .await
            .unwrap();
            let (chapter_2, page2) = content_management::create_new_chapter(
                tx.as_mut(),
                PKeyPolicy::Generate,
                &NewChapter {
                    name: "chapter 2".to_string(),
                    color: None,
                    course_id: course,
                    chapter_number: 2,
                    front_page_id: None,
                    opens_at: None,
                    deadline: None,
                    course_module_id: Some(course_module_2.id),
                },
                user,
                |_, _, _| unimplemented!(),
                |_| unimplemented!(),
            )
            .await
            .unwrap();

            let exercise_2 = exercises::insert(
                tx.as_mut(),
                PKeyPolicy::Generate,
                course,
                "",
                page2.id,
                chapter_2.id,
                0,
            )
            .await
            .unwrap();
            let user_exercise_state = user_exercise_states::get_or_create_user_exercise_state(
                tx.as_mut(),
                user,
                exercise,
                Some(course),
                None,
            )
            .await
            .unwrap();
            user_exercise_states::update(
                tx.as_mut(),
                UserExerciseStateUpdate {
                    id: user_exercise_state.id,
                    score_given: Some(0.0),
                    activity_progress: ActivityProgress::Completed,
                    reviewing_stage: ReviewingStage::NotStarted,
                    grading_progress: GradingProgress::FullyGraded,
                },
            )
            .await
            .unwrap();
            let user_exercise_state_2 = user_exercise_states::get_or_create_user_exercise_state(
                tx.as_mut(),
                user,
                exercise_2,
                Some(course),
                None,
            )
            .await
            .unwrap();
            user_exercise_states::update(
                tx.as_mut(),
                UserExerciseStateUpdate {
                    id: user_exercise_state_2.id,
                    score_given: Some(0.0),
                    activity_progress: ActivityProgress::Completed,
                    reviewing_stage: ReviewingStage::NotStarted,
                    grading_progress: GradingProgress::FullyGraded,
                },
            )
            .await
            .unwrap();
            let default_module = course_modules::get_default_by_course_id(tx.as_mut(), course)
                .await
                .unwrap();
            let default_module = course_modules::update_automatic_completion_status(
                tx.as_mut(),
                default_module.id,
                &automatic_completion_policy,
            )
            .await
            .unwrap();
            let course_module = course_modules::update_automatic_completion_status(
                tx.as_mut(),
                course_module.id,
                &automatic_completion_policy,
            )
            .await
            .unwrap();
            let course_module_2 = course_modules::update_automatic_completion_status(
                tx.as_mut(),
                course_module_2.id,
                &automatic_completion_policy,
            )
            .await
            .unwrap();
            (
                tx,
                user,
                course,
                instance.id,
                default_module,
                course_module,
                course_module_2,
            )
        }
    }

    #[tokio::test]
    async fn tags_suspected_cheater() {
        insert_data!(:tx, user:user, :org, course:course, instance:instance, course_module:course_module, :chapter, :page, :exercise);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();
        let state = user_exercise_states::get_or_create_user_exercise_state(
            tx.as_mut(),
            user,
            exercise,
            Some(course),
            None,
        )
        .await
        .unwrap();
        user_exercise_states::update(
            tx.as_mut(),
            UserExerciseStateUpdate {
                id: state.id,
                score_given: Some(10.0),
                activity_progress: ActivityProgress::Completed,
                reviewing_stage: ReviewingStage::NotStarted,
                grading_progress: GradingProgress::FullyGraded,
            },
        )
        .await
        .unwrap();

        let completion = course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(1),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: None,
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        let thresholds = suspected_cheaters::insert_thresholds_by_module_id(
            tx.as_mut(),
            course_module.id,
            259200,
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            completion,
        )
        .await
        .unwrap();

        let cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        assert_eq!(cheaters.len(), 1);
        assert_eq!(cheaters[0].user_id, user);
    }

    #[tokio::test]
    async fn tagging_suspected_cheater_is_idempotent() {
        insert_data!(:tx, user:user, :org, course:course, instance:instance, course_module:course_module, :chapter, :page, :exercise);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();
        let state = user_exercise_states::get_or_create_user_exercise_state(
            tx.as_mut(),
            user,
            exercise,
            Some(course),
            None,
        )
        .await
        .unwrap();
        user_exercise_states::update(
            tx.as_mut(),
            UserExerciseStateUpdate {
                id: state.id,
                score_given: Some(10.0),
                activity_progress: ActivityProgress::Completed,
                reviewing_stage: ReviewingStage::NotStarted,
                grading_progress: GradingProgress::FullyGraded,
            },
        )
        .await
        .unwrap();

        let completion = course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(1),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: None,
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        let thresholds = suspected_cheaters::insert_thresholds_by_module_id(
            tx.as_mut(),
            course_module.id,
            259200,
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            completion.clone(),
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            completion,
        )
        .await
        .unwrap();

        let cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        assert_eq!(cheaters.len(), 1);
        let completion_needing_review =
            course_module_completions::get_latest_by_course_and_user_ids(
                tx.as_mut(),
                course_module.id,
                user,
            )
            .await
            .unwrap();
        assert!(completion_needing_review.needs_to_be_reviewed);

        suspected_cheaters::dismiss_by_user_id_and_course_id(tx.as_mut(), user, course)
            .await
            .unwrap();
        let archived_completion = course_module_completions::get_latest_by_course_and_user_ids(
            tx.as_mut(),
            course_module.id,
            user,
        )
        .await
        .unwrap();
        assert!(!archived_completion.needs_to_be_reviewed);
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            archived_completion,
        )
        .await
        .unwrap();

        let visible_cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        let archived_cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Dismissed,
        )
        .await
        .unwrap();
        assert!(visible_cheaters.is_empty());
        assert_eq!(archived_cheaters.len(), 1);
        let rechecked_completion = course_module_completions::get_latest_by_course_and_user_ids(
            tx.as_mut(),
            course_module.id,
            user,
        )
        .await
        .unwrap();
        assert!(!rechecked_completion.needs_to_be_reviewed);
    }

    #[tokio::test]
    async fn confirming_then_dismissing_restores_grade() {
        insert_data!(:tx, user:user, :org, course:course, instance:instance, course_module:course_module, :chapter, :page, :exercise);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();
        let state = user_exercise_states::get_or_create_user_exercise_state(
            tx.as_mut(),
            user,
            exercise,
            Some(course),
            None,
        )
        .await
        .unwrap();
        user_exercise_states::update(
            tx.as_mut(),
            UserExerciseStateUpdate {
                id: state.id,
                score_given: Some(10.0),
                activity_progress: ActivityProgress::Completed,
                reviewing_stage: ReviewingStage::NotStarted,
                grading_progress: GradingProgress::FullyGraded,
            },
        )
        .await
        .unwrap();

        // A graded, passing completion so we can prove the exact grade is restored, not just pass/fail.
        let completion = course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(1),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: Some(4),
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        let thresholds = suspected_cheaters::insert_thresholds_by_module_id(
            tx.as_mut(),
            course_module.id,
            259200,
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            completion,
        )
        .await
        .unwrap();

        // Confirm: the student is failed and the previous grade is snapshotted.
        suspected_cheaters::confirm_cheater_by_user_id_and_course_id(tx.as_mut(), user, course)
            .await
            .unwrap();
        let failed = course_module_completions::get_latest_by_course_and_user_ids(
            tx.as_mut(),
            course_module.id,
            user,
        )
        .await
        .unwrap();
        assert!(!failed.passed);
        assert_eq!(failed.grade, Some(0));
        let confirmed = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::ConfirmedCheating,
        )
        .await
        .unwrap();
        assert_eq!(confirmed.len(), 1);

        // Dismiss: the confirmation is undone and the exact previous grade is restored.
        suspected_cheaters::dismiss_by_user_id_and_course_id(tx.as_mut(), user, course)
            .await
            .unwrap();
        let restored = course_module_completions::get_latest_by_course_and_user_ids(
            tx.as_mut(),
            course_module.id,
            user,
        )
        .await
        .unwrap();
        assert!(restored.passed);
        assert_eq!(restored.grade, Some(4));
        assert!(!restored.needs_to_be_reviewed);
        let dismissed = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Dismissed,
        )
        .await
        .unwrap();
        assert_eq!(dismissed.len(), 1);
    }

    #[tokio::test]
    async fn manual_completion_prevents_flagging() {
        insert_data!(:tx, user:user, :org, course:course, instance:instance, course_module:course_module);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();

        // A teacher has manually granted a completion for this student.
        let teacher = users::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            "teacher-vouching@example.com",
            Some("Teacher"),
            Some("McVouch"),
        )
        .await
        .unwrap();
        course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now(),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: Some(5),
                passed: true,
            },
            CourseModuleCompletionGranter::User(teacher),
        )
        .await
        .unwrap();

        // An automatic completion well inside the threshold would normally flag the student.
        let automatic_completion = course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(1),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: None,
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        let thresholds = suspected_cheaters::insert_thresholds_by_module_id(
            tx.as_mut(),
            course_module.id,
            259200,
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            automatic_completion,
        )
        .await
        .unwrap();

        // The teacher's manual completion exempts the student, so no suspicion is created.
        let cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        assert!(cheaters.is_empty());
    }

    #[tokio::test]
    async fn adding_manual_completion_dismisses_confirmed_suspicion_and_restores_grade() {
        insert_data!(:tx, user:user, :org, course:course, instance:instance, course_module:course_module, :chapter, :page, :exercise);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();
        let state = user_exercise_states::get_or_create_user_exercise_state(
            tx.as_mut(),
            user,
            exercise,
            Some(course),
            None,
        )
        .await
        .unwrap();
        user_exercise_states::update(
            tx.as_mut(),
            UserExerciseStateUpdate {
                id: state.id,
                score_given: Some(10.0),
                activity_progress: ActivityProgress::Completed,
                reviewing_stage: ReviewingStage::NotStarted,
                grading_progress: GradingProgress::FullyGraded,
            },
        )
        .await
        .unwrap();

        // Flag the student via a fast automatic completion, then confirm cheating (fails the grade).
        let completion = course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(1),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: Some(4),
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        let thresholds = suspected_cheaters::insert_thresholds_by_module_id(
            tx.as_mut(),
            course_module.id,
            259200,
        )
        .await
        .unwrap();
        check_and_insert_suspected_cheaters(
            tx.as_mut(),
            user,
            course,
            thresholds.duration_seconds,
            completion,
        )
        .await
        .unwrap();
        suspected_cheaters::confirm_cheater_by_user_id_and_course_id(tx.as_mut(), user, course)
            .await
            .unwrap();

        // A teacher manually adds a completion for the same student. `skip_duplicate_completions` is
        // false so the completion is inserted even though the module is already completed.
        let teacher = users::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            "teacher-vouching@example.com",
            Some("Teacher"),
            Some("McVouch"),
        )
        .await
        .unwrap();
        add_manual_completions(
            tx.as_mut(),
            teacher,
            &instance,
            &TeacherManualCompletionRequest {
                course_module_id: course_module.id,
                new_completions: vec![TeacherManualCompletion {
                    user_id: user,
                    grade: Some(5),
                    passed: true,
                    completion_date: None,
                }],
                skip_duplicate_completions: false,
            },
        )
        .await
        .unwrap();

        // The suspicion is dismissed and the confirmed-cheating grade failure is undone.
        let flagged = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        let confirmed = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::ConfirmedCheating,
        )
        .await
        .unwrap();
        let dismissed = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Dismissed,
        )
        .await
        .unwrap();
        assert!(flagged.is_empty());
        assert!(confirmed.is_empty());
        assert_eq!(dismissed.len(), 1);

        // The automatic completion's failed grade is restored and its review flag is cleared.
        let restored =
            course_module_completions::get_automatic_completion_by_course_module_course_and_user_ids(
                tx.as_mut(),
                course_module.id,
                course,
                user,
            )
            .await
            .unwrap();
        assert!(restored.passed);
        assert_eq!(restored.grade, Some(4));
        assert!(!restored.needs_to_be_reviewed);
    }

    #[tokio::test]
    async fn doesnt_tag_suspected_cheater() {
        insert_data!(:tx, user:user, :org, :course, instance:instance, course_module:course_module, :chapter, :page, :exercise);

        crate::library::course_instances::enroll(tx.as_mut(), user, instance.id, &[])
            .await
            .unwrap();
        let state = user_exercise_states::get_or_create_user_exercise_state(
            tx.as_mut(),
            user,
            exercise,
            Some(course),
            None,
        )
        .await
        .unwrap();
        user_exercise_states::update(
            tx.as_mut(),
            UserExerciseStateUpdate {
                id: state.id,
                score_given: Some(9.0),
                activity_progress: ActivityProgress::Completed,
                reviewing_stage: ReviewingStage::NotStarted,
                grading_progress: GradingProgress::FullyGraded,
            },
        )
        .await
        .unwrap();

        course_module_completions::insert(
            tx.as_mut(),
            PKeyPolicy::Generate,
            &NewCourseModuleCompletion {
                course_id: course,
                course_module_id: course_module.id,
                user_id: user,
                completion_date: Utc::now() + Duration::days(3),
                completion_registration_attempt_date: None,
                completion_language: "en-US".to_string(),
                eligible_for_ects: false,
                email: "email".to_string(),
                grade: Some(9),
                passed: true,
            },
            CourseModuleCompletionGranter::Automatic,
        )
        .await
        .unwrap();
        suspected_cheaters::insert_thresholds_by_module_id(tx.as_mut(), course_module.id, 172800)
            .await
            .unwrap();
        update_automatic_completion_status_and_grant_if_eligible(tx.as_mut(), &course_module, user)
            .await
            .unwrap();

        let cheaters = suspected_cheaters::get_all_suspected_cheaters_in_course(
            tx.as_mut(),
            course,
            SuspectedCheaterStatus::Flagged,
        )
        .await
        .unwrap();
        assert!(cheaters.is_empty());
    }

    // TODO: New automatic completion tests?
}