headless_lms_server/controllers/course_material/

course_instances.rs

//! Controllers for requests starting with `/api/v0/course-material/course-instances`.

use headless_lms_utils::numbers::option_f32_to_f32_two_decimals_with_none_as_zero;
use models::{
    chapters::UserCourseInstanceChapterProgress,
    course_background_question_answers::NewCourseBackgroundQuestionAnswer,
    course_background_questions::CourseBackgroundQuestionsAndAnswers,
    course_instance_enrollments::CourseInstanceEnrollment,
    course_module_completions::CourseModuleCompletion,
    library::progressing::UserModuleCompletionStatus,
    points_breakdowns::ChapterPointsBreakdown,
    user_exercise_states::{UserCourseChapterExerciseProgress, UserCourseProgress},
};
use utoipa::{OpenApi, ToSchema};

use crate::{
    domain::authorization::{authorize_access_to_course_material, skip_authorize},
    prelude::*,
};

#[derive(OpenApi)]
#[openapi(paths(
    get_user_progress_for_course_instance,
    get_user_progress_for_course_instance_chapter,
    get_user_progress_for_course_instance_chapter_exercises,
    get_user_points_breakdown_for_course_module,
    get_module_completions_for_course_instance,
    save_course_settings,
    get_all_get_all_course_module_completions_for_user_by_course_instance_id,
    get_background_questions_and_answers
))]
pub(crate) struct CourseMaterialCourseInstancesApiDoc;

/**
 GET /api/v0/course-material/course-instance/:course_intance_id/progress - returns user progress information.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/progress",
    operation_id = "getCourseMaterialUserCourseProgress",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id")
    ),
    responses(
        (status = 200, description = "User course progress", body = Vec<UserCourseProgress>)
    )
)]
#[instrument(skip(pool))]
async fn get_user_progress_for_course_instance(
    user: AuthUser,
    course_instance_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<UserCourseProgress>>> {
    let mut conn = pool.acquire().await?;
    let course_instance =
        models::course_instances::get_course_instance(&mut conn, *course_instance_id).await?;
    let user_course_progress = models::user_exercise_states::get_user_course_progress(
        &mut conn,
        course_instance.course_id,
        user.id,
        false,
    )
    .await?;
    let token = skip_authorize();
    token.authorized_ok(web::Json(user_course_progress))
}

/**
GET `/api/v0/course-material/course-instance/:course_instance_id/chapters/:chapter_id/progress - Returns user progress for chapter in course instance.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/chapters/{chapter_id}/progress",
    operation_id = "getCourseMaterialChapterProgress",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id"),
        ("chapter_id" = Uuid, Path, description = "Chapter id")
    ),
    responses(
        (status = 200, description = "Course instance chapter progress", body = UserCourseInstanceChapterProgress)
    )
)]
#[instrument(skip(pool))]
async fn get_user_progress_for_course_instance_chapter(
    user: AuthUser,
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<UserCourseInstanceChapterProgress>> {
    let mut conn = pool.acquire().await?;
    let (course_instance_id, chapter_id) = params.into_inner();
    let course_instance =
        models::course_instances::get_course_instance(&mut conn, course_instance_id).await?;
    let chapter = models::chapters::get_chapter(&mut conn, chapter_id).await?;
    if chapter.course_id != course_instance.course_id {
        return Err(controller_err!(
            Forbidden,
            "Chapter does not belong to the requested course instance".to_string()
        ));
    }
    let token =
        authorize_access_to_course_material(&mut conn, Some(user.id), course_instance.course_id)
            .await?;
    let user_course_instance_chapter_progress =
        models::chapters::get_user_course_instance_chapter_progress(
            &mut conn,
            course_instance_id,
            chapter_id,
            user.id,
        )
        .await?;
    token.authorized_ok(web::Json(user_course_instance_chapter_progress))
}

/**
GET /api/v0/course-material/course-instance/:course_instance_id/chapters/:chapter_id/exercises/progress - Returns user progress for an exercise in given course instance.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/chapters/{chapter_id}/exercises/progress",
    operation_id = "getCourseMaterialChapterExerciseProgress",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id"),
        ("chapter_id" = Uuid, Path, description = "Chapter id")
    ),
    responses(
        (status = 200, description = "Course instance chapter exercise progress", body = Vec<UserCourseChapterExerciseProgress>)
    )
)]
#[instrument(skip(pool))]
async fn get_user_progress_for_course_instance_chapter_exercises(
    user: AuthUser,
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<UserCourseChapterExerciseProgress>>> {
    let mut conn = pool.acquire().await?;
    let (course_instance_id, chapter_id) = params.into_inner();
    let course_instance =
        models::course_instances::get_course_instance(&mut conn, course_instance_id).await?;
    let chapter = models::chapters::get_chapter(&mut conn, chapter_id).await?;
    if chapter.course_id != course_instance.course_id {
        return Err(controller_err!(
            Forbidden,
            "Chapter does not belong to the requested course instance".to_string()
        ));
    }
    let token =
        authorize_access_to_course_material(&mut conn, Some(user.id), course_instance.course_id)
            .await?;
    let chapter_exercises =
        models::exercises::get_exercises_by_chapter_id(&mut conn, chapter_id).await?;
    let exercise_ids: Vec<Uuid> = chapter_exercises.into_iter().map(|e| e.id).collect();
    let user_course_instance_exercise_progress =
        models::user_exercise_states::get_user_course_chapter_exercises_progress(
            &mut conn,
            course_instance.course_id,
            &exercise_ids,
            user.id,
        )
        .await?;
    let rounded_score_given_instances: Vec<UserCourseChapterExerciseProgress> =
        user_course_instance_exercise_progress
            .into_iter()
            .map(|i| UserCourseChapterExerciseProgress {
                score_given: option_f32_to_f32_two_decimals_with_none_as_zero(i.score_given),
                exercise_id: i.exercise_id,
            })
            .collect();
    token.authorized_ok(web::Json(rounded_score_given_instances))
}

/**
GET `/api/v0/course-material/course-instances/:course_instance_id/course-modules/:course_module_id/points-breakdown` - Returns the user's points in the module's opened chapters, exercise by exercise.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/course-modules/{course_module_id}/points-breakdown",
    operation_id = "getCourseMaterialCourseModulePointsBreakdown",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id"),
        ("course_module_id" = Uuid, Path, description = "Course module id")
    ),
    responses(
        (status = 200, description = "The user's points by chapter, page and exercise", body = Vec<ChapterPointsBreakdown>)
    )
)]
#[instrument(skip(pool))]
async fn get_user_points_breakdown_for_course_module(
    user: AuthUser,
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<ChapterPointsBreakdown>>> {
    let mut conn = pool.acquire().await?;
    let (course_instance_id, course_module_id) = params.into_inner();
    let course_instance =
        models::course_instances::get_course_instance(&mut conn, course_instance_id).await?;
    let course_module = models::course_modules::get_by_id(&mut conn, course_module_id).await?;
    if course_module.course_id != course_instance.course_id {
        return Err(controller_err!(
            Forbidden,
            "Course module does not belong to the requested course instance".to_string()
        ));
    }
    let token =
        authorize_access_to_course_material(&mut conn, Some(user.id), course_instance.course_id)
            .await?;
    let breakdown = models::points_breakdowns::get_user_course_module_points_breakdown(
        &mut conn,
        course_module_id,
        user.id,
    )
    .await?;
    token.authorized_ok(web::Json(breakdown))
}

/**
GET `/api/v0/course-material/course-instance/{course_instance_id}/module-completions`
 */
#[utoipa::path(
    get,
    path = "/{course_instance_id}/module-completions",
    operation_id = "getCourseMaterialUserModuleCompletions",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id")
    ),
    responses(
        (status = 200, description = "User module completion statuses", body = Vec<UserModuleCompletionStatus>)
    )
)]
#[instrument(skip(pool))]
async fn get_module_completions_for_course_instance(
    user: AuthUser,
    course_instance_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<UserModuleCompletionStatus>>> {
    let mut conn = pool.acquire().await?;
    let token = skip_authorize();

    let course_instance =
        models::course_instances::get_course_instance(&mut conn, *course_instance_id).await?;
    let mut module_completion_statuses =
        models::library::progressing::get_user_module_completion_statuses_for_course(
            &mut conn,
            user.id,
            course_instance.course_id,
        )
        .await?;
    // Override individual completions in modules with insufficient prerequisites
    module_completion_statuses.iter_mut().for_each(|module| {
        if !module.prerequisite_modules_completed {
            module.completed = false;
            module.certificate_configuration_id = None;
        }
    });
    token.authorized_ok(web::Json(module_completion_statuses))
}

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

pub struct SaveCourseSettingsPayload {
    pub background_question_answers: Vec<NewCourseBackgroundQuestionAnswer>,
}

/**
POST /api/v0/course-material/course-instance/:course_instance_id/save-course-settings - enrolls user to the course instance and save background questions.
*/
#[utoipa::path(
    post,
    path = "/{course_instance_id}/save-course-settings",
    operation_id = "saveCourseMaterialCourseSettings",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id")
    ),
    request_body = SaveCourseSettingsPayload,
    responses(
        (status = 200, description = "Course instance enrollment", body = CourseInstanceEnrollment)
    )
)]
#[instrument(skip(pool))]
async fn save_course_settings(
    pool: web::Data<PgPool>,
    course_instance_id: web::Path<Uuid>,
    payload: web::Json<SaveCourseSettingsPayload>,
    user: AuthUser,
) -> ControllerResult<web::Json<CourseInstanceEnrollment>> {
    let mut conn = pool.acquire().await?;

    let enrollment = models::library::course_instances::enroll(
        &mut conn,
        user.id,
        *course_instance_id,
        payload.background_question_answers.as_slice(),
    )
    .await?;
    let token = skip_authorize();
    token.authorized_ok(web::Json(enrollment))
}

/**
GET /course-instances/:id/course-module-completions/:user_id - Returns a list of all course module completions for a given user for this course instance.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/course-module-completions/{user_id}",
    operation_id = "getCourseMaterialCourseModuleCompletionsForUser",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id"),
        ("user_id" = Uuid, Path, description = "User id")
    ),
    responses(
        (status = 200, description = "Course module completions for user", body = Vec<CourseModuleCompletion>)
    )
)]
#[instrument(skip(pool))]

async fn get_all_get_all_course_module_completions_for_user_by_course_instance_id(
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<CourseModuleCompletion>>> {
    let (course_instance_id, user_id) = params.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewUserProgressOrDetails,
        Some(user.id),
        Res::CourseInstance(course_instance_id),
    )
    .await?;

    let course_instance =
        models::course_instances::get_course_instance(&mut conn, course_instance_id).await?;

    let res = models::course_module_completions::get_all_by_course_id_and_user_id(
        &mut conn,
        course_instance.course_id,
        user_id,
    )
    .await?;

    token.authorized_ok(web::Json(res))
}

/**
GET /api/v0/course-material/course-instance/:course_instance_id/background-questions-and-answers - Gets background questions and answers for an course instance.
*/
#[utoipa::path(
    get,
    path = "/{course_instance_id}/background-questions-and-answers",
    operation_id = "getCourseMaterialBackgroundQuestionsAndAnswers",
    tag = "course-material-course-instances",
    params(
        ("course_instance_id" = Uuid, Path, description = "Course instance id")
    ),
    responses(
        (status = 200, description = "Background questions and answers", body = CourseBackgroundQuestionsAndAnswers)
    )
)]
#[instrument(skip(pool))]
async fn get_background_questions_and_answers(
    pool: web::Data<PgPool>,
    course_instance_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<CourseBackgroundQuestionsAndAnswers>> {
    let mut conn = pool.acquire().await?;

    let instance =
        models::course_instances::get_course_instance(&mut conn, *course_instance_id).await?;
    let res = models::course_background_questions::get_background_questions_and_answers(
        &mut conn, &instance, user.id,
    )
    .await?;
    let token = skip_authorize();
    token.authorized_ok(web::Json(res))
}

pub fn _add_routes(cfg: &mut ServiceConfig) {
    cfg.route(
        "/{course_instance_id}/save-course-settings",
        web::post().to(save_course_settings),
    )
    .route(
        "/{course_instance_id}/progress",
        web::get().to(get_user_progress_for_course_instance),
    )
    .route(
        "/{course_instance_id}/chapters/{chapter_id}/exercises/progress",
        web::get().to(get_user_progress_for_course_instance_chapter_exercises),
    )
    .route(
        "/{course_instance_id}/chapters/{chapter_id}/progress",
        web::get().to(get_user_progress_for_course_instance_chapter),
    )
    .route(
        "/{course_instance_id}/course-modules/{course_module_id}/points-breakdown",
        web::get().to(get_user_points_breakdown_for_course_module),
    )
    .route(
        "/{course_instance_id}/module-completions",
        web::get().to(get_module_completions_for_course_instance),
    )
    .route(
        "/{course_instance_id}/course-module-completions/{user_id}",
        web::get().to(get_all_get_all_course_module_completions_for_user_by_course_instance_id),
    )
    .route(
        "/{course_instance_id}/background-questions-and-answers",
        web::get().to(get_background_questions_and_answers),
    );
}