headless_lms_server/controllers/main_frontend/courses/

mod.rs

//! Controllers for requests starting with `/api/v0/main-frontend/courses`.

pub mod chatbots;
pub mod stats;
pub mod students;

use chrono::Utc;
use domain::csv_export::user_exercise_states_export::UserExerciseStatesExportOperation;
use headless_lms_models::{
    partner_block::PartnersBlock,
    suspected_cheaters::{CourseModuleThresholdInfo, SuspectedCheaterStatus, SuspectedCheaters},
};
use std::sync::Arc;
use utoipa::OpenApi;

use headless_lms_utils::strings::is_ietf_language_code_like;
use models::{
    chapters::Chapter,
    course_instances::{CourseInstance, CourseInstanceForm, NewCourseInstance},
    course_module_completions::CourseModuleCompletion,
    course_modules::ModuleUpdates,
    courses::{Course, CourseBreadcrumbInfo, CourseStructure, CourseUpdate, NewCourse},
    exercise_slide_submissions::{
        self, ExerciseAnswersInCourseRequiringAttentionCount, ExerciseSlideSubmissionCount,
        ExerciseSlideSubmissionCountByExercise, ExerciseSlideSubmissionCountByWeekAndHour,
    },
    exercises::{Exercise, ExerciseStatusSummaryForUser},
    feedback::{self, Feedback, FeedbackCount},
    glossary::{Term, TermUpdate},
    library,
    material_references::{MaterialReference, NewMaterialReference},
    page_visit_datum_summary_by_courses::PageVisitDatumSummaryByCourse,
    page_visit_datum_summary_by_courses_countries::PageVisitDatumSummaryByCoursesCountries,
    page_visit_datum_summary_by_courses_device_types::PageVisitDatumSummaryByCourseDeviceTypes,
    page_visit_datum_summary_by_pages::PageVisitDatumSummaryByPages,
    pages::Page,
    peer_or_self_review_configs::PeerOrSelfReviewConfig,
    peer_or_self_review_questions::PeerOrSelfReviewQuestion,
    user_course_settings::UserCourseSettings,
    user_exercise_states::{ExerciseUserCounts, UserCourseProgress},
};

use crate::{
    domain::models_requests::{self, JwtKey},
    prelude::*,
};

use headless_lms_models::course_language_groups;

use crate::domain::csv_export::course_instance_export::CourseInstancesExportOperation;
use crate::domain::csv_export::course_research_form_questions_answers_export::CourseResearchFormExportOperation;
use crate::domain::csv_export::exercise_tasks_export::CourseExerciseTasksExportOperation;
use crate::domain::csv_export::general_export;
use crate::domain::csv_export::submissions::CourseSubmissionExportOperation;
use crate::domain::csv_export::users_export::UsersExportOperation;

#[derive(OpenApi)]
#[openapi(
    paths(
        get_course,
        get_course_breadcrumb_info,
        get_all_exercise_statuses_by_course_id,
        get_all_course_module_completions_for_user_by_course_id,
        get_user_progress_for_course,
        get_user_course_settings,
        post_reprocess_module_completions,
        post_new_course,
        update_course,
        delete_course,
        get_course_structure,
        add_media_for_course,
        get_all_exercises,
        get_all_exercises_and_count_of_answers_requiring_attention,
        get_all_course_language_versions,
        create_course_copy,
        get_daily_submission_counts,
        get_daily_user_counts_with_submissions,
        get_weekday_hour_submission_counts,
        get_submission_counts_by_exercise,
        get_course_instances,
        get_feedback,
        get_feedback_count,
        new_course_instance,
        glossary,
        new_glossary_term,
        get_course_users_counts_by_exercise,
        post_new_page_ordering,
        post_new_chapter_ordering,
        get_material_references_by_course_id,
        insert_material_references,
        update_material_reference,
        delete_material_reference_by_id,
        update_modules,
        get_course_default_peer_review,
        post_update_peer_review_queue_reviews_received,
        submission_export,
        user_details_export,
        exercise_tasks_export,
        course_instances_export,
        course_consent_form_answers_export,
        user_exercise_states_export,
        get_page_visit_datum_summary,
        get_page_visit_datum_summary_by_pages,
        get_page_visit_datum_summary_by_device_types,
        get_page_visit_datum_summary_by_countries,
        teacher_reset_course_progress_for_themselves,
        teacher_reset_course_progress_for_everyone,
        get_all_suspected_cheaters,
        get_flagged_suspected_cheaters_count,
        get_all_thresholds,
        teacher_dismiss_suspected_cheater,
        teacher_confirm_suspected_cheater,
        add_user_to_course_with_join_code,
        set_join_code_for_course,
        get_course_with_join_code,
        post_partners_block,
        get_partners_block,
        delete_partners_block
    ),
    nest(
        (path = "/{course_id}/chatbots", api = chatbots::MainFrontendCourseChatbotsApiDoc),
        (path = "/{course_id}/stats", api = stats::MainFrontendCourseStatsApiDoc),
        (path = "/{course_id}/students", api = students::MainFrontendCourseStudentsApiDoc)
    )
)]
pub(crate) struct MainFrontendCoursesApiDoc;

/**
GET `/api/v0/main-frontend/courses/:course_id` - Get course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}",
    operation_id = "getCourse",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course", body = Course)
    )
)]
#[instrument(skip(pool))]
async fn get_course(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let token = authorize_access_to_course_material(&mut conn, Some(user.id), *course_id).await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    token.authorized_ok(web::Json(course))
}

/**
GET `/api/v0/main-frontend/courses/:course_id/breadcrumb-info` - Get information to display breadcrumbs on the manage course pages.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/breadcrumb-info",
    operation_id = "getCourseBreadcrumbInfo",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course breadcrumb information", body = CourseBreadcrumbInfo)
    )
)]
#[instrument(skip(pool))]
async fn get_course_breadcrumb_info(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<CourseBreadcrumbInfo>> {
    let mut conn = pool.acquire().await?;
    let user_id = Some(user.id);
    let token = authorize_access_to_course_material(&mut conn, user_id, *course_id).await?;
    let info = models::courses::get_course_breadcrumb_info(&mut conn, *course_id).await?;
    token.authorized_ok(web::Json(info))
}

/**
GET `/api/v0/main-frontend/courses/:course_id/status-for-all-exercises/:user_id` - Returns status for all exercises in the course for a given user.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/status-for-all-exercises/{user_id}",
    operation_id = "getCourseExerciseStatusesForUser",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "User id")
    ),
    responses(
        (status = 200, description = "Exercise statuses for course user", body = [ExerciseStatusSummaryForUser])
    )
)]
#[instrument(skip(pool))]
async fn get_all_exercise_statuses_by_course_id(
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseStatusSummaryForUser>>> {
    let (course_id, user_id) = params.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewUserProgressOrDetails,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;
    let res = models::exercises::get_all_exercise_statuses_by_user_id_and_course_id(
        &mut conn, course_id, user_id,
    )
    .await?;
    token.authorized_ok(web::Json(res))
}

/**
GET `/api/v0/main-frontend/courses/:course_id/course-module-completions/:user_id` - Returns all course module completions for a given user for this course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/course-module-completions/{user_id}",
    operation_id = "getCourseModuleCompletionsForUser",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "User id")
    ),
    responses(
        (status = 200, description = "Course module completions for course user", body = [CourseModuleCompletion])
    )
)]
#[instrument(skip(pool))]
async fn get_all_course_module_completions_for_user_by_course_id(
    params: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<CourseModuleCompletion>>> {
    let (course_id, user_id) = params.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewUserProgressOrDetails,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;
    let res = models::course_module_completions::get_all_by_course_id_and_user_id(
        &mut conn, course_id, user_id,
    )
    .await?;
    token.authorized_ok(web::Json(res))
}

/**
GET `/api/v0/main-frontend/courses/:course_id/progress/:user_id` - Returns user progress for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/progress/{user_id}",
    operation_id = "getCourseProgressForUser",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "User id")
    ),
    responses(
        (status = 200, description = "User progress for course", body = [UserCourseProgress])
    )
)]
#[instrument(skip(pool))]
async fn get_user_progress_for_course(
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<UserCourseProgress>>> {
    let (course_id, target_user_id) = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewUserProgressOrDetails,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;
    let user_course_progress = models::user_exercise_states::get_user_course_progress(
        &mut conn,
        course_id,
        target_user_id,
        false,
    )
    .await?;
    token.authorized_ok(web::Json(user_course_progress))
}

/**
GET `/api/v0/main-frontend/courses/:course_id/user-settings/:user_id` - Get current course settings for a specific user.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/user-settings/{user_id}",
    operation_id = "getCourseUserSettingsForUser",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "User id")
    ),
    responses(
        (status = 200, description = "User course settings", body = Option<UserCourseSettings>)
    )
)]
#[instrument(skip(pool))]
async fn get_user_course_settings(
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Option<UserCourseSettings>>> {
    let (course_id, target_user_id) = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;
    let settings = models::user_course_settings::get_user_course_settings_by_course_id(
        &mut conn,
        target_user_id,
        course_id,
    )
    .await?;
    token.authorized_ok(web::Json(settings))
}

/**
POST `/api/v0/main-frontend/courses/{course_id}/reprocess-completions`

Reprocesses all module completions for the given course instance. Only available to admins.
*/
#[utoipa::path(
    post,
    path = "/{course_id}/reprocess-completions",
    operation_id = "reprocessCourseCompletions",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course completions reprocessed", body = bool)
    )
)]
#[instrument(skip(pool, user))]
async fn post_reprocess_module_completions(
    pool: web::Data<PgPool>,
    user: AuthUser,
    course_id: web::Path<Uuid>,
) -> ControllerResult<web::Json<bool>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::GlobalPermissions).await?;
    models::library::progressing::process_all_course_completions(&mut conn, *course_id).await?;
    token.authorized_ok(web::Json(true))
}

/**
POST `/api/v0/main-frontend/courses` - Create a new course.
# Example

Request:
```http
POST /api/v0/main-frontend/courses HTTP/1.1
Content-Type: application/json

{
  "name": "Introduction to introduction",
  "slug": "introduction-to-introduction",
  "organization_id": "1b89e57e-8b57-42f2-9fed-c7a6736e3eec"
}
```
*/
#[utoipa::path(
    post,
    path = "",
    operation_id = "createCourse",
    tag = "courses",
    request_body = NewCourse,
    responses(
        (status = 200, description = "Created course", body = Course)
    )
)]
#[instrument(skip(pool, app_conf))]
async fn post_new_course(
    request_id: RequestId,
    pool: web::Data<PgPool>,
    payload: web::Json<NewCourse>,
    user: AuthUser,
    app_conf: web::Data<ApplicationConfiguration>,
    jwt_key: web::Data<JwtKey>,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let new_course = payload.0;
    if !is_ietf_language_code_like(&new_course.language_code) {
        return Err(ControllerError::new(
            ControllerErrorType::BadRequest,
            "Malformed language code.".to_string(),
            None,
        ));
    }
    let token = authorize(
        &mut conn,
        Act::CreateCoursesOrExams,
        Some(user.id),
        Res::Organization(new_course.organization_id),
    )
    .await?;

    let mut tx = conn.begin().await?;
    let (course, ..) = library::content_management::create_new_course(
        &mut tx,
        PKeyPolicy::Generate,
        new_course,
        user.id,
        models_requests::make_spec_fetcher(
            app_conf.base_url.clone(),
            request_id.0,
            Arc::clone(&jwt_key),
        ),
        models_requests::fetch_service_info,
    )
    .await?;
    models::roles::insert(
        &mut tx,
        user.id,
        models::roles::UserRole::Teacher,
        models::roles::RoleDomain::Course(course.id),
    )
    .await?;
    tx.commit().await?;

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

/**
POST `/api/v0/main-frontend/courses/:course_id` - Update course.
# Example

Request:
```http
PUT /api/v0/main-frontend/courses/ab4541d8-6db4-4561-bdb2-45f35b2544a1 HTTP/1.1
Content-Type: application/json

{
  "name": "Introduction to Introduction"
}

```
*/
#[utoipa::path(
    put,
    path = "/{course_id}",
    operation_id = "updateCourse",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = CourseUpdate,
    responses(
        (status = 200, description = "Updated course", body = Course)
    )
)]
#[instrument(skip(pool))]
async fn update_course(
    payload: web::Json<CourseUpdate>,
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let course_update = payload.0;
    let course_before_update = models::courses::get_course(&mut conn, *course_id).await?;
    if course_update.can_add_chatbot != course_before_update.can_add_chatbot {
        // Only global admins can change the chatbot status
        let _token2 =
            authorize(&mut conn, Act::Teach, Some(user.id), Res::GlobalPermissions).await?;
    }

    let locking_just_enabled =
        !course_before_update.chapter_locking_enabled && course_update.chapter_locking_enabled;

    let course = models::courses::update_course(&mut conn, *course_id, course_update).await?;

    if locking_just_enabled {
        use models::{user_chapter_locking_statuses, user_course_settings};

        let all_user_settings =
            user_course_settings::get_all_by_course_id(&mut conn, *course_id).await?;

        for settings in all_user_settings {
            let _ = user_chapter_locking_statuses::get_or_init_all_for_course(
                &mut conn,
                settings.user_id,
                *course_id,
            )
            .await?;
        }
    }

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

/**
DELETE `/api/v0/main-frontend/courses/:course_id` - Delete a course.
*/
#[utoipa::path(
    delete,
    path = "/{course_id}",
    operation_id = "deleteCourse",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Deleted course", body = serde_json::Value)
    )
)]
#[instrument(skip(pool))]
async fn delete_course(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::UsuallyUnacceptableDeletion,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course = models::courses::delete_course(&mut conn, *course_id).await?;

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

/**
GET `/api/v0/main-frontend/courses/:course_id/structure` - Returns the structure of a course.
# Example
```json
{
  "course": {
    "id": "d86cf910-4d26-40e9-8c9c-1cc35294fdbb",
    "slug": "introduction-to-everything",
    "created_at": "2021-04-28T10:40:54.503917",
    "updated_at": "2021-04-28T10:40:54.503917",
    "name": "Introduction to everything",
    "organization_id": "1b89e57e-8b57-42f2-9fed-c7a6736e3eec",
    "deleted_at": null,
    "language_code": "en-US",
    "copied_from": null,
    "language_version_of_course_id": null
  },
  "pages": [
    {
      "id": "f3b0d699-c9be-4d56-bd0a-9d40e5547e4d",
      "created_at": "2021-04-28T13:51:51.024118",
      "updated_at": "2021-04-28T14:36:18.179490",
      "course_id": "d86cf910-4d26-40e9-8c9c-1cc35294fdbb",
      "content": [],
      "url_path": "/",
      "title": "Welcome to Introduction to Everything",
      "deleted_at": null,
      "chapter_id": "d332f3d9-39a5-4a18-80f4-251727693c37"
    }
  ],
  "chapters": [
    {
      "id": "d332f3d9-39a5-4a18-80f4-251727693c37",
      "created_at": "2021-04-28T16:11:47.477850",
      "updated_at": "2021-04-28T16:11:47.477850",
      "name": "The Basics",
      "course_id": "d86cf910-4d26-40e9-8c9c-1cc35294fdbb",
      "deleted_at": null,
      "chapter_image_url": "http://project-331.local/api/v0/files/uploads/organizations/1b89e57e-8b57-42f2-9fed-c7a6736e3eec/courses/d86cf910-4d26-40e9-8c9c-1cc35294fdbb/images/mbPQh8th96TdUwX96Y0ch1fjbJLRFr.png",
      "chapter_number": 1,
      "front_page_id": null
    }
  ]
}
```
*/
#[utoipa::path(
    get,
    path = "/{course_id}/structure",
    operation_id = "getCourseStructure",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course structure", body = CourseStructure)
    )
)]
#[instrument(skip(pool, file_store, app_conf))]
async fn get_course_structure(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
    file_store: web::Data<dyn FileStore>,
    app_conf: web::Data<ApplicationConfiguration>,
) -> ControllerResult<web::Json<CourseStructure>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewInternalCourseStructure,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course_structure = models::courses::get_course_structure(
        &mut conn,
        *course_id,
        file_store.as_ref(),
        app_conf.as_ref(),
    )
    .await?;

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

/**
POST `/api/v0/main-frontend/courses/:course_id/upload` - Uploads a media (image, audio, file) for the course from Gutenberg page edit.

Put the the contents of the media in a form and add a content type header multipart/form-data.
# Example

Request:
```http
POST /api/v0/main-frontend/pages/d86cf910-4d26-40e9-8c9c-1cc35294fdbb/upload HTTP/1.1
Content-Type: multipart/form-data

BINARY_DATA
```
*/
#[utoipa::path(
    post,
    path = "/{course_id}/upload",
    operation_id = "uploadCourseMedia",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body(
        content = String,
        content_type = "multipart/form-data"
    ),
    responses(
        (status = 200, description = "Uploaded media result", body = UploadResult)
    )
)]
#[instrument(skip(payload, request, pool, file_store, app_conf))]
async fn add_media_for_course(
    course_id: web::Path<Uuid>,
    payload: Multipart,
    request: HttpRequest,
    pool: web::Data<PgPool>,
    user: AuthUser,
    file_store: web::Data<dyn FileStore>,
    app_conf: web::Data<ApplicationConfiguration>,
) -> ControllerResult<web::Json<UploadResult>> {
    let mut conn = pool.acquire().await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let media_path = upload_file_from_cms(
        request.headers(),
        payload,
        StoreKind::Course(course.id),
        file_store.as_ref(),
        &mut conn,
        user,
    )
    .await?;
    let download_url = file_store.get_download_url(media_path.as_path(), app_conf.as_ref());

    token.authorized_ok(web::Json(UploadResult { url: download_url }))
}

/**
GET `/api/v0/main-frontend/courses/:id/exercises` - Returns all exercises for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/exercises",
    operation_id = "getCourseExercises",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Exercises for course", body = [Exercise])
    )
)]
#[instrument(skip(pool))]
async fn get_all_exercises(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<Exercise>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let exercises = models::exercises::get_exercises_by_course_id(&mut conn, *course_id).await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/exercises-and-count-of-answers-requiring-attention` - Returns all exercises for the course and count of answers requiring attention in them.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/exercises-and-count-of-answers-requiring-attention",
    operation_id = "getCourseExercisesAndAnswersRequiringAttentionCounts",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (
            status = 200,
            description = "Exercises and answer attention counts",
            body = [ExerciseAnswersInCourseRequiringAttentionCount]
        )
    )
)]
#[instrument(skip(pool))]
async fn get_all_exercises_and_count_of_answers_requiring_attention(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseAnswersInCourseRequiringAttentionCount>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let _exercises = models::exercises::get_exercises_by_course_id(&mut conn, *course_id).await?;
    let count_of_answers_requiring_attention = models::exercise_slide_submissions::get_count_of_answers_requiring_attention_in_exercise_by_course_id(&mut conn, *course_id).await?;
    token.authorized_ok(web::Json(count_of_answers_requiring_attention))
}

/**
GET `/api/v0/main-frontend/courses/:id/language-versions` - Returns all language versions of the same course.

# Example

Request:
```http
GET /api/v0/main-frontend/courses/fd484707-25b6-4c51-a4ff-32d8259e3e47/language-versions HTTP/1.1
Content-Type: application/json
```
*/
#[utoipa::path(
    get,
    path = "/{course_id}/language-versions",
    operation_id = "getCourseLanguageVersions",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course language versions", body = [Course])
    )
)]
#[instrument(skip(pool))]
async fn get_all_course_language_versions(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<Course>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let language_versions =
        models::courses::get_all_language_versions_of_course(&mut conn, &course).await?;

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

#[derive(Deserialize, Debug, utoipa::ToSchema)]
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum CopyCourseMode {
    /// Create a completely separate copy with a new course language group
    Duplicate,
    /// Create a new language version within the same language group as the source
    SameLanguageGroup,
    /// Create a new language version in a specified language group
    ExistingLanguageGroup { target_course_id: Uuid },
    /// Create a new language version in a new language group
    NewLanguageGroup,
}

#[derive(Deserialize, Debug, utoipa::ToSchema)]

pub struct CopyCourseRequest {
    #[serde(flatten)]
    pub new_course: NewCourse,
    pub mode: CopyCourseMode,
}

/**
POST `/api/v0/main-frontend/courses/:id/create-copy` - Create a copy of a course with specified mode.

Different copy modes:
- `duplicate`: Creates a completely separate copy with new language group
- `same_language_group`: Creates a new language version within the same language group
- `existing_language_group`: Creates a new language version in the specified language group
- `new_language_group`: Creates a new language version in a new language group

# Example

Request:
```http
POST /api/v0/main-frontend/courses/fd484707-25b6-4c51-a4ff-32d8259e3e47/create-copy HTTP/1.1
Content-Type: application/json

{
  "name": "Johdatus kaikkeen",
  "slug": "johdatus-kaikkeen",
  "organization_id": "1b89e57e-8b57-42f2-9fed-c7a6736e3eec",
  "language_code": "fi-FI",
  "mode": "duplicate"
}
```

Or with an existing language group:
```http
POST /api/v0/main-frontend/courses/fd484707-25b6-4c51-a4ff-32d8259e3e47/create-copy HTTP/1.1
Content-Type: application/json

{
  "name": "Johdatus kaikkeen",
  "slug": "johdatus-kaikkeen",
  "organization_id": "1b89e57e-8b57-42f2-9fed-c7a6736e3eec",
  "language_code": "fi-FI",
  "mode": {
    "existing_language_group": {
      "target_course_id": "1b89e57e-8b57-42f2-9fed-c7a6736e3eec"
    }
  }
}
```
*/
#[utoipa::path(
    post,
    path = "/{course_id}/create-copy",
    operation_id = "createCourseCopy",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = CopyCourseRequest,
    responses(
        (status = 200, description = "Created course copy", body = Course)
    )
)]
#[instrument(skip(pool))]
pub async fn create_course_copy(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    payload: web::Json<CopyCourseRequest>,
    user: AuthUser,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::Duplicate,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let new_course = payload.new_course.clone();
    authorize(
        &mut conn,
        Act::CreateCoursesOrExams,
        Some(user.id),
        Res::Organization(new_course.organization_id),
    )
    .await?;

    let mut tx = conn.begin().await?;

    let copied_course = match &payload.mode {
        CopyCourseMode::Duplicate => {
            models::library::copying::copy_course(&mut tx, *course_id, &new_course, false, user.id)
                .await?
        }
        CopyCourseMode::SameLanguageGroup => {
            models::library::copying::copy_course(&mut tx, *course_id, &new_course, true, user.id)
                .await?
        }
        CopyCourseMode::ExistingLanguageGroup { target_course_id } => {
            let target_course = models::courses::get_course(&mut tx, *target_course_id).await?;
            // Verify that the user has permissions also to the course of the custom language group
            authorize(
                &mut tx,
                Act::Duplicate,
                Some(user.id),
                Res::Course(*target_course_id),
            )
            .await?;
            models::library::copying::copy_course_with_language_group(
                &mut tx,
                *course_id,
                target_course.course_language_group_id,
                &new_course,
                user.id,
            )
            .await?
        }
        CopyCourseMode::NewLanguageGroup => {
            let new_clg_id = course_language_groups::insert(
                &mut tx,
                PKeyPolicy::Generate,
                new_course.slug.as_str(),
            )
            .await?;
            models::library::copying::copy_course_with_language_group(
                &mut tx,
                *course_id,
                new_clg_id,
                &new_course,
                user.id,
            )
            .await?
        }
    };

    models::roles::insert(
        &mut tx,
        user.id,
        models::roles::UserRole::Teacher,
        models::roles::RoleDomain::Course(copied_course.id),
    )
    .await?;

    tx.commit().await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/daily-submission-counts` - Returns submission counts grouped by day.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/daily-submission-counts",
    operation_id = "getCourseDailySubmissionCounts",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course daily submission counts", body = [ExerciseSlideSubmissionCount])
    )
)]
#[instrument(skip(pool))]
async fn get_daily_submission_counts(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseSlideSubmissionCount>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let res =
        exercise_slide_submissions::get_course_daily_slide_submission_counts(&mut conn, &course)
            .await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/daily-users-who-have-submitted-something` - Returns a count of users who have submitted something grouped by day.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/daily-users-who-have-submitted-something",
    operation_id = "getCourseDailyUsersWhoSubmittedSomething",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course daily user submission counts", body = [ExerciseSlideSubmissionCount])
    )
)]
#[instrument(skip(pool))]
async fn get_daily_user_counts_with_submissions(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseSlideSubmissionCount>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let res = exercise_slide_submissions::get_course_daily_user_counts_with_submissions(
        &mut conn, &course,
    )
    .await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/weekday-hour-submission-counts` - Returns submission counts grouped by weekday and hour.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/weekday-hour-submission-counts",
    operation_id = "getCourseWeekdayHourSubmissionCounts",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course weekday and hour submission counts", body = [ExerciseSlideSubmissionCountByWeekAndHour])
    )
)]
#[instrument(skip(pool))]
async fn get_weekday_hour_submission_counts(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseSlideSubmissionCountByWeekAndHour>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let res = exercise_slide_submissions::get_course_exercise_slide_submission_counts_by_weekday_and_hour(
        &mut conn, &course,
    )
    .await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/submission-counts-by-exercise` - Returns submission counts grouped by weekday and hour.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/submission-counts-by-exercise",
    operation_id = "getCourseSubmissionCountsByExercise",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course submission counts by exercise", body = [ExerciseSlideSubmissionCountByExercise])
    )
)]
#[instrument(skip(pool))]
async fn get_submission_counts_by_exercise(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseSlideSubmissionCountByExercise>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course = models::courses::get_course(&mut conn, *course_id).await?;
    let res = exercise_slide_submissions::get_course_exercise_slide_submission_counts_by_exercise(
        &mut conn, &course,
    )
    .await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/course-instances` - Returns all course instances for given course id.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/course-instances",
    operation_id = "getCourseInstances",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course instances", body = [CourseInstance])
    )
)]
#[instrument(skip(pool))]
async fn get_course_instances(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<CourseInstance>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let course_instances =
        models::course_instances::get_course_instances_for_course(&mut conn, *course_id).await?;

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

#[derive(Debug, Deserialize)]

pub struct GetFeedbackQuery {
    read: bool,
    #[serde(flatten)]
    pagination: Pagination,
}

/**
GET `/api/v0/main-frontend/courses/:id/feedback?read=true` - Returns feedback for the given course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/feedback",
    operation_id = "getCourseFeedback",
    tag = "courses",
    params(
        ("course_id" = String, Path, description = "Course id"),
        ("read" = bool, Query, description = "Whether to fetch read feedback"),
        ("page" = Option<i64>, Query, description = "Page number"),
        ("limit" = Option<i64>, Query, description = "Page size")
    ),
    responses(
        (status = 200, description = "Feedback for the course", body = [Feedback])
    )
)]
#[instrument(skip(pool))]
pub async fn get_feedback(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    read: web::Query<GetFeedbackQuery>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<Feedback>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;
    let feedback =
        feedback::get_feedback_for_course(&mut conn, *course_id, read.read, read.pagination)
            .await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/feedback-count` - Returns the amount of feedback for the given course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/feedback-count",
    operation_id = "getCourseFeedbackCount",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Feedback counts for the course", body = FeedbackCount)
    )
)]
#[instrument(skip(pool))]
pub async fn get_feedback_count(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<FeedbackCount>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let feedback_count = feedback::get_feedback_count_for_course(&mut conn, *course_id).await?;

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

/**
POST `/api/v0/main-frontend/courses/:id/new-course-instance`
*/
#[utoipa::path(
    post,
    path = "/{course_id}/new-course-instance",
    operation_id = "createCourseInstance",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = CourseInstanceForm,
    responses(
        (status = 200, description = "Created course instance id", body = Uuid)
    )
)]
#[instrument(skip(pool))]
async fn new_course_instance(
    form: web::Json<CourseInstanceForm>,
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Uuid>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let form = form.into_inner();
    let new = NewCourseInstance {
        course_id: *course_id,
        name: form.name.as_deref(),
        description: form.description.as_deref(),
        support_email: form.support_email.as_deref(),
        teacher_in_charge_name: &form.teacher_in_charge_name,
        teacher_in_charge_email: &form.teacher_in_charge_email,
        opening_time: form.opening_time,
        closing_time: form.closing_time,
    };
    let ci = models::course_instances::insert(&mut conn, PKeyPolicy::Generate, new).await?;

    token.authorized_ok(web::Json(ci.id))
}

#[instrument(skip(pool))]
#[utoipa::path(
    get,
    path = "/{course_id}/glossary",
    operation_id = "getCourseGlossary",
    tag = "glossary",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Glossary terms for the course", body = [Term]),
        (status = 401, description = "Authentication required"),
        (status = 403, description = "User is not allowed to manage the course glossary")
    )
)]
pub(crate) async fn glossary(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<Term>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let glossary = models::glossary::fetch_for_course(&mut conn, *course_id).await?;

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

// unused?

#[instrument(skip(pool))]
async fn _new_term(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<Term>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let glossary = models::glossary::fetch_for_course(&mut conn, *course_id).await?;

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

#[instrument(skip(pool))]
#[utoipa::path(
    post,
    path = "/{course_id}/glossary",
    operation_id = "createCourseGlossaryTerm",
    tag = "glossary",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = TermUpdate,
    responses(
        (status = 200, description = "Created glossary term id", body = Uuid),
        (status = 401, description = "Authentication required"),
        (status = 403, description = "User is not allowed to manage the course glossary")
    )
)]
pub(crate) async fn new_glossary_term(
    pool: web::Data<PgPool>,
    course_id: web::Path<Uuid>,
    new_term: web::Json<TermUpdate>,
    user: AuthUser,
) -> ControllerResult<web::Json<Uuid>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;
    let TermUpdate { term, definition } = new_term.into_inner();
    let term = models::glossary::insert(&mut conn, &term, &definition, *course_id).await?;

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

/**
GET `/api/v0/main-frontend/courses/:id/course-users-counts-by-exercise` - Returns the amount of users for each exercise.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/course-users-counts-by-exercise",
    operation_id = "getCourseUsersCountsByExercise",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course users counts by exercise", body = [ExerciseUserCounts])
    )
)]
#[instrument(skip(pool))]
pub async fn get_course_users_counts_by_exercise(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<ExerciseUserCounts>>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;

    let res =
        models::user_exercise_states::get_course_users_counts_by_exercise(&mut conn, course_id)
            .await?;

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

/**
POST `/api/v0/main-frontend/courses/:id/new-page-ordering` - Reorders pages to the given order numbers and given chapters.

Note that the page objects posted here might have the content omitted because it is not needed here and the content makes the request body to be very large.

Creates redirects if url_path changes.
*/
#[utoipa::path(
    post,
    path = "/{course_id}/new-page-ordering",
    operation_id = "updateCoursePageOrdering",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = Vec<Page>,
    responses(
        (status = 200, description = "Course page ordering updated")
    )
)]
#[instrument(skip(pool))]
pub async fn post_new_page_ordering(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
    payload: web::Json<Vec<Page>>,
) -> ControllerResult<web::Json<()>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    models::pages::reorder_pages(&mut conn, &payload, course_id).await?;

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

/**
POST `/api/v0/main-frontend/courses/:id/new-chapter-ordering` - Reorders chapters based on modified chapter number.#

Creates redirects if url_path changes.
*/
#[utoipa::path(
    post,
    path = "/{course_id}/new-chapter-ordering",
    operation_id = "updateCourseChapterOrdering",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = Vec<Chapter>,
    responses(
        (status = 200, description = "Course chapter ordering updated")
    )
)]
#[instrument(skip(pool))]
pub async fn post_new_chapter_ordering(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
    payload: web::Json<Vec<Chapter>>,
) -> ControllerResult<web::Json<()>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    models::pages::reorder_chapters(&mut conn, &payload, course_id).await?;

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

#[utoipa::path(
    get,
    path = "/{course_id}/references",
    operation_id = "getCourseReferences",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course references", body = [MaterialReference])
    )
)]
#[instrument(skip(pool))]
async fn get_material_references_by_course_id(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<MaterialReference>>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;

    let res =
        models::material_references::get_references_by_course_id(&mut conn, *course_id).await?;
    token.authorized_ok(web::Json(res))
}

#[utoipa::path(
    post,
    path = "/{course_id}/references",
    operation_id = "createCourseReferences",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = [NewMaterialReference],
    responses(
        (status = 200, description = "Course references created")
    )
)]
#[instrument(skip(pool))]
async fn insert_material_references(
    course_id: web::Path<Uuid>,
    payload: web::Json<Vec<NewMaterialReference>>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<()>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;

    models::material_references::insert_reference(&mut conn, *course_id, payload.0).await?;

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

#[utoipa::path(
    post,
    path = "/{course_id}/references/{reference_id}",
    operation_id = "updateCourseReference",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("reference_id" = Uuid, Path, description = "Reference id")
    ),
    request_body = NewMaterialReference,
    responses(
        (status = 200, description = "Course reference updated")
    )
)]
#[instrument(skip(pool))]
async fn update_material_reference(
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
    payload: web::Json<NewMaterialReference>,
) -> ControllerResult<web::Json<()>> {
    let (course_id, reference_id) = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(course_id)).await?;

    models::material_references::update_by_id_and_course_id(
        &mut conn,
        reference_id,
        course_id,
        payload.0,
    )
    .await?;
    token.authorized_ok(web::Json(()))
}

#[utoipa::path(
    delete,
    path = "/{course_id}/references/{reference_id}",
    operation_id = "deleteCourseReference",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("reference_id" = Uuid, Path, description = "Reference id")
    ),
    responses(
        (status = 200, description = "Course reference deleted")
    )
)]
#[instrument(skip(pool))]
async fn delete_material_reference_by_id(
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<()>> {
    let (course_id, reference_id) = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(course_id)).await?;

    models::material_references::delete_by_id_and_course_id(&mut conn, reference_id, course_id)
        .await?;
    token.authorized_ok(web::Json(()))
}

#[utoipa::path(
    post,
    path = "/{course_id}/course-modules",
    operation_id = "updateCourseModules",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = ModuleUpdates,
    responses(
        (status = 200, description = "Course modules updated")
    )
)]
#[instrument(skip(pool))]
pub async fn update_modules(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
    payload: web::Json<ModuleUpdates>,
) -> ControllerResult<web::Json<()>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*course_id)).await?;

    models::course_modules::update_modules(&mut conn, *course_id, payload.into_inner()).await?;
    token.authorized_ok(web::Json(()))
}

#[utoipa::path(
    get,
    path = "/{course_id}/default-peer-review",
    operation_id = "getCourseDefaultPeerReview",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Default peer review configuration", body = serde_json::Value)
    )
)]
async fn get_course_default_peer_review(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<(PeerOrSelfReviewConfig, Vec<PeerOrSelfReviewQuestion>)>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let peer_review = models::peer_or_self_review_configs::get_default_for_course_by_course_id(
        &mut conn, *course_id,
    )
    .await?;
    let peer_or_self_review_questions =
        models::peer_or_self_review_questions::get_all_by_peer_or_self_review_config_id(
            &mut conn,
            peer_review.id,
        )
        .await?;
    token.authorized_ok(web::Json((peer_review, peer_or_self_review_questions)))
}

/**
POST `/api/v0/main-frontend/courses/${course_id}/update-peer-review-queue-reviews-received`

Updates reviews received for all the students in the peer review queue for a specific course. Updates only entries that have not received enough peer reviews in the table. Only available to admins.
*/
#[utoipa::path(
    post,
    path = "/{course_id}/update-peer-review-queue-reviews-received",
    operation_id = "updateCoursePeerReviewQueueReviewsReceived",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Peer review queue updated", body = bool)
    )
)]
#[instrument(skip(pool, user))]
async fn post_update_peer_review_queue_reviews_received(
    pool: web::Data<PgPool>,
    user: AuthUser,
    course_id: web::Path<Uuid>,
) -> ControllerResult<web::Json<bool>> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::GlobalPermissions).await?;
    models::library::peer_or_self_reviewing::update_peer_review_queue_reviews_received(
        &mut conn, *course_id,
    )
    .await?;
    token.authorized_ok(web::Json(true))
}

/**
GET `/api/v0/main-frontend/courses/${courseId}/export-submissions`

gets SCV of course exercise submissions
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-submissions",
    operation_id = "exportCourseSubmissionsCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course submissions CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn submission_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - Submissions (exercise tasks) {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        CourseSubmissionExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/export-user-details`

gets SCV of user details for all users having submitted an exercise in the course
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-user-details",
    operation_id = "exportCourseUserDetailsCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course user details CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn user_details_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - User Details {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        UsersExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/export-exercise-tasks`

gets SCV all exercise-tasks' private specs in course
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-exercise-tasks",
    operation_id = "exportCourseExerciseTasksCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course exercise tasks CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn exercise_tasks_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - Exercise tasks {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        CourseExerciseTasksExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/export-course-instances`

gets SCV course instances for course
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-course-instances",
    operation_id = "exportCourseInstancesCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course instances CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn course_instances_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - Instances {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        CourseInstancesExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/export-course-user-consents`

gets SCV course specific research form questions and user answers for course
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-course-user-consents",
    operation_id = "exportCourseUserConsentsCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course user consents CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn course_consent_form_answers_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - User Consents {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        CourseResearchFormExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/export-user-exercise-states`

gets CSV for course specific user exercise states
*/
#[utoipa::path(
    get,
    path = "/{course_id}/export-user-exercise-states",
    operation_id = "exportCourseUserExerciseStatesCsv",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course user exercise states CSV", body = String, content_type = "text/csv")
    )
)]
#[instrument(skip(pool))]
pub async fn user_exercise_states_export(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;

    let token = authorize(
        &mut conn,
        Act::Teach,
        Some(user.id),
        Res::Course(*course_id),
    )
    .await?;

    let course = models::courses::get_course(&mut conn, *course_id).await?;

    general_export(
        pool,
        &format!(
            "attachment; filename=\"Course: {} - User exercise states {}.csv\"",
            course.name,
            Utc::now().format("%Y-%m-%d")
        ),
        UserExerciseStatesExportOperation {
            course_id: *course_id,
        },
        token,
    )
    .await
}

/**
GET `/api/v0/main-frontend/courses/${course.id}/page-visit-datum-summary` - Gets aggregated statistics for page visits for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/page-visit-datum-summary",
    operation_id = "getCoursePageVisitDatumSummary",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course page visit summary", body = [PageVisitDatumSummaryByCourse])
    )
)]
pub async fn get_page_visit_datum_summary(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<PageVisitDatumSummaryByCourse>>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;

    let res = models::page_visit_datum_summary_by_courses::get_all_for_course(&mut conn, course_id)
        .await?;

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

/**
GET `/api/v0/main-frontend/courses/${course.id}/page-visit-datum-summary-by-pages` - Gets aggregated statistics for page visits for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/page-visit-datum-summary-by-pages",
    operation_id = "getCoursePageVisitDatumSummaryByPages",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course page visit summary by pages", body = [PageVisitDatumSummaryByPages])
    )
)]
pub async fn get_page_visit_datum_summary_by_pages(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<PageVisitDatumSummaryByPages>>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;

    let res =
        models::page_visit_datum_summary_by_pages::get_all_for_course(&mut conn, course_id).await?;

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

/**
GET `/api/v0/main-frontend/courses/${course.id}/page-visit-datum-summary-by-device-types` - Gets aggregated statistics for page visits for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/page-visit-datum-summary-by-device-types",
    operation_id = "getCoursePageVisitDatumSummaryByDeviceTypes",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course page visit summary by device types", body = [PageVisitDatumSummaryByCourseDeviceTypes])
    )
)]
pub async fn get_page_visit_datum_summary_by_device_types(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<PageVisitDatumSummaryByCourseDeviceTypes>>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;

    let res = models::page_visit_datum_summary_by_courses_device_types::get_all_for_course(
        &mut conn, course_id,
    )
    .await?;

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

/**
GET `/api/v0/main-frontend/courses/${course.id}/page-visit-datum-summary-by-countries` - Gets aggregated statistics for page visits for the course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/page-visit-datum-summary-by-countries",
    operation_id = "getCoursePageVisitDatumSummaryByCountries",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course page visit summary by countries", body = [PageVisitDatumSummaryByCoursesCountries])
    )
)]
pub async fn get_page_visit_datum_summary_by_countries(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<Vec<PageVisitDatumSummaryByCoursesCountries>>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(
        &mut conn,
        Act::ViewStats,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;

    let res = models::page_visit_datum_summary_by_courses_countries::get_all_for_course(
        &mut conn, course_id,
    )
    .await?;

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

/**
DELETE `/api/v0/main-frontend/courses/${course.id}/teacher-reset-course-progress-for-themselves` - Allows a teacher to reset the course progress for themselves. Cannot be used to reset the course for others.

Deletes submissions, user exercise states, and peer reviews etc. for all the course instances of this course.
*/
#[utoipa::path(
    delete,
    path = "/{course_id}/teacher-reset-course-progress-for-themselves",
    operation_id = "resetCourseProgressForTeacherThemselves",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Teacher course progress reset", body = bool)
    )
)]
pub async fn teacher_reset_course_progress_for_themselves(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<bool>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    let mut tx = conn.begin().await?;
    let course_instances =
        models::course_instances::get_course_instances_for_course(&mut tx, course_id).await?;
    for course_instance in course_instances {
        models::course_instances::reset_progress_on_course_instance_for_user(
            &mut tx,
            user.id,
            course_instance.course_id,
        )
        .await?;
    }

    tx.commit().await?;
    token.authorized_ok(web::Json(true))
}

/**
DELETE `/api/v0/main-frontend/courses/${course.id}/teacher-reset-course-progress-for-everyone` - Can be used by teachers to reset the course progress for all students. Only works when the course is a draft and not published to students. Cannot be used to delete a course that some students have taken.

Deletes submissions, user exercise states, and peer reviews etc. for all the course instances of this course.
*/
#[utoipa::path(
    delete,
    path = "/{course_id}/teacher-reset-course-progress-for-everyone",
    operation_id = "resetCourseProgressForEveryone",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course progress reset for everyone", body = bool)
    )
)]
pub async fn teacher_reset_course_progress_for_everyone(
    course_id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<bool>> {
    let mut conn = pool.acquire().await?;
    let course_id = course_id.into_inner();
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;
    let course = models::courses::get_course(&mut conn, course_id).await?;
    if !course.is_draft {
        return Err(ControllerError::new(
            ControllerErrorType::BadRequest,
            "Can only reset progress for a draft course.".to_string(),
            None,
        ));
    }
    // To prevent teachers from deleting courses that real students have been taking, we need to address the case where the teacher turns the course back to draft to enable resetting progress for everyone. We'll counteract this by checking the number of course module completions to the course.
    let n_course_module_completions =
        models::course_module_completions::get_count_of_distinct_completors_by_course_id(
            &mut conn, course_id,
        )
        .await?;
    let n_completions_registered_to_study_registry = models::course_module_completion_registered_to_study_registries::get_count_of_distinct_users_with_registrations_by_course_id(
        &mut conn, course_id,
    ).await?;
    if n_course_module_completions > 200 {
        return Err(ControllerError::new(
            ControllerErrorType::BadRequest,
            "Too many students have completed the course.".to_string(),
            None,
        ));
    }
    if n_completions_registered_to_study_registry > 2 {
        return Err(ControllerError::new(
            ControllerErrorType::BadRequest,
            "Too many students have registered their completion to a study registry".to_string(),
            None,
        ));
    }

    let mut tx = conn.begin().await?;
    let course_instances =
        models::course_instances::get_course_instances_for_course(&mut tx, course_id).await?;

    // Looping though the data since this is only for draft courses and the amount of data is not expected to be large.
    for course_instance in course_instances {
        let users_in_course_instance =
            models::users::get_users_by_course_instance_enrollment(&mut tx, course_instance.id)
                .await?;
        for user_in_course_instance in users_in_course_instance {
            models::course_instances::reset_progress_on_course_instance_for_user(
                &mut tx,
                user_in_course_instance.id,
                course_instance.course_id,
            )
            .await?;
        }
    }

    tx.commit().await?;
    token.authorized_ok(web::Json(true))
}

#[derive(Debug, Deserialize)]

pub struct GetSuspectedCheatersQuery {
    status: SuspectedCheaterStatus,
}

/**
 GET /api/v0/main-frontend/courses/${course.id}/suspected-cheaters?status=Flagged - returns the suspected cheaters in the given review state for a course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/suspected-cheaters",
    operation_id = "getCourseSuspectedCheaters",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("status" = SuspectedCheaterStatus, Query, description = "Which review state of suspected cheaters to fetch")
    ),
    responses(
        (status = 200, description = "Suspected cheaters for course", body = [SuspectedCheaters])
    )
)]
#[instrument(skip(pool))]
async fn get_all_suspected_cheaters(
    user: AuthUser,
    params: web::Path<Uuid>,
    query: web::Query<GetSuspectedCheatersQuery>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<SuspectedCheaters>>> {
    let course_id = params.into_inner();

    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    let course_cheaters = models::suspected_cheaters::get_all_suspected_cheaters_in_course(
        &mut conn,
        course_id,
        query.status,
    )
    .await?;

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

/**
 GET /api/v0/main-frontend/courses/${course.id}/suspected-cheaters/flagged-count - number of suspected cheaters awaiting review (status flagged). Used to show a review notification to teachers.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/suspected-cheaters/flagged-count",
    operation_id = "getCourseFlaggedSuspectedCheatersCount",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Number of suspected cheaters awaiting review", body = i64, content_type = "application/json")
    )
)]
#[instrument(skip(pool))]
async fn get_flagged_suspected_cheaters_count(
    user: AuthUser,
    params: web::Path<Uuid>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<i64>> {
    let course_id = params.into_inner();

    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    let count = models::suspected_cheaters::get_count_in_course_by_status(
        &mut conn,
        course_id,
        SuspectedCheaterStatus::Flagged,
    )
    .await?;

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

/**
 GET /api/v0/main-frontend/courses/${course.id}/thresholds - get all thresholds for all modules in a course.
*/
#[utoipa::path(
    get,
    path = "/{course_id}/thresholds",
    operation_id = "getCourseThresholds",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course thresholds", body = Vec<CourseModuleThresholdInfo>)
    )
)]
#[instrument(skip(pool))]
async fn get_all_thresholds(
    user: AuthUser,
    params: web::Path<Uuid>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Vec<CourseModuleThresholdInfo>>> {
    let mut conn = pool.acquire().await?;
    let course_id = params.into_inner();

    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    let thresholds =
        models::suspected_cheaters::get_threshold_info_for_course(&mut conn, course_id).await?;

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

/**
 POST /api/v0/main-frontend/courses/${course.id}/suspected-cheaters/dismiss/:user_id - dismisses the suspicion as a false alarm (sets status to 'Dismissed').
*/
#[utoipa::path(
    post,
    path = "/{course_id}/suspected-cheaters/dismiss/{user_id}",
    operation_id = "dismissCourseSuspectedCheater",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "Suspected cheater's user id")
    ),
    responses(
        (status = 200, description = "Suspicion dismissed")
    )
)]
#[instrument(skip(pool))]
async fn teacher_dismiss_suspected_cheater(
    user: AuthUser,
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<()>> {
    let (course_id, user_id) = path.into_inner();

    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    models::suspected_cheaters::dismiss_by_user_id_and_course_id(&mut conn, user_id, course_id)
        .await?;

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

/**
 POST /api/v0/main-frontend/courses/${course.id}/suspected-cheaters/confirm/:user_id - confirms the student cheated (sets status to 'ConfirmedCheating') and fails the student.
*/
#[utoipa::path(
    post,
    path = "/{course_id}/suspected-cheaters/confirm/{user_id}",
    operation_id = "confirmCourseSuspectedCheater",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id"),
        ("user_id" = Uuid, Path, description = "Suspected cheater's user id")
    ),
    responses(
        (status = 200, description = "Cheating confirmed")
    )
)]
#[instrument(skip(pool))]
async fn teacher_confirm_suspected_cheater(
    user: AuthUser,
    path: web::Path<(Uuid, Uuid)>,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<()>> {
    let (course_id, user_id) = path.into_inner();

    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    // Confirming sets the status and fails the student's completions (snapshotting the previous
    // grade so a later dismiss can restore it); see confirm_cheater_by_user_id_and_course_id.
    models::suspected_cheaters::confirm_cheater_by_user_id_and_course_id(
        &mut conn, user_id, course_id,
    )
    .await?;

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

#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct JoinCourseWithJoinCodePayload {
    join_code: String,
}

/**
POST /courses/:course_id/join-course-with-join-code - Adds the user to join_code_uses so the user gets access to the course
*/
#[utoipa::path(
    post,
    path = "/{course_id}/join-course-with-join-code",
    operation_id = "joinCourseWithJoinCode",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = JoinCourseWithJoinCodePayload,
    responses(
        (status = 200, description = "Joined course id", body = Uuid)
    )
)]
#[instrument(skip(pool))]
async fn add_user_to_course_with_join_code(
    course_id: web::Path<Uuid>,
    payload: web::Json<JoinCourseWithJoinCodePayload>,
    user: AuthUser,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Uuid>> {
    let mut conn = pool.acquire().await?;
    let token = skip_authorize();

    models::courses::get_by_id_and_join_code(&mut conn, *course_id, &payload.join_code).await?;
    let joined =
        models::join_code_uses::insert(&mut conn, PKeyPolicy::Generate, user.id, *course_id)
            .await?;
    token.authorized_ok(web::Json(joined))
}

/**
 POST /api/v0/main-frontend/courses/:course_id/generate-join-code - Generates a code that is used as a part of URL to join course
*/
#[utoipa::path(
    post,
    path = "/{course_id}/set-join-code",
    operation_id = "setCourseJoinCode",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Course join code set")
    )
)]
#[instrument(skip(pool))]
async fn set_join_code_for_course(
    id: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<HttpResponse> {
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Edit, Some(user.id), Res::Course(*id)).await?;

    const CHARSET: &[u8] = b"ABCDEFGHJKMNPQRSTUVWXYZ\
                            abcdefghjkmnpqrstuvwxyz";
    const PASSWORD_LEN: usize = 64;
    let mut rng = rand::rng();

    let code: String = (0..PASSWORD_LEN)
        .map(|_| {
            let idx = rng.random_range(0..CHARSET.len());
            CHARSET[idx] as char
        })
        .collect();

    models::courses::set_join_code_for_course(&mut conn, *id, code).await?;
    token.authorized_ok(HttpResponse::Ok().finish())
}

/**
GET /courses/join/:join_code - Gets the course related to join code
*/
#[utoipa::path(
    get,
    path = "/join/{join_code}",
    operation_id = "getCourseByJoinCode",
    tag = "courses",
    params(
        ("join_code" = String, Path, description = "Course join code")
    ),
    responses(
        (status = 200, description = "Course for join code", body = Course)
    )
)]
#[instrument(skip(pool))]
async fn get_course_with_join_code(
    join_code: web::Path<String>,
    user: AuthUser,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<Course>> {
    let mut conn = pool.acquire().await?;
    let token = skip_authorize();
    let course =
        models::courses::get_course_with_join_code(&mut conn, join_code.to_string()).await?;

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

/**
 POST /api/v0/main-frontend/courses/:course_id/partners_block - Create or updates a partners block for a course
*/
#[utoipa::path(
    post,
    path = "/{course_id}/partners-block",
    operation_id = "upsertCoursePartnersBlock",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    request_body = Option<serde_json::Value>,
    responses(
        (status = 200, description = "Partners block", body = serde_json::Value)
    )
)]
#[instrument(skip(payload, pool))]
async fn post_partners_block(
    path: web::Path<Uuid>,
    payload: web::Json<Option<serde_json::Value>>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<PartnersBlock>> {
    let course_id = path.into_inner();

    let content = payload.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    let upserted_partner_block =
        models::partner_block::upsert_partner_block(&mut conn, course_id, content).await?;

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

/**
GET /courses/:course_id/partners_blocks - Gets a partners block related to a course
*/
#[utoipa::path(
    get,
    path = "/{course_id}/partners-block",
    operation_id = "getCoursePartnersBlock",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Partners block", body = serde_json::Value)
    )
)]
#[instrument(skip(pool))]
async fn get_partners_block(
    path: web::Path<Uuid>,
    user: AuthUser,
    pool: web::Data<PgPool>,
) -> ControllerResult<web::Json<PartnersBlock>> {
    let course_id = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(&mut conn, Act::Teach, Some(user.id), Res::Course(course_id)).await?;

    // Check if the course exists in the partners_blocks table
    let course_exists = models::partner_block::check_if_course_exists(&mut conn, course_id).await?;

    let partner_block = if course_exists {
        // If the course exists, fetch the partner block
        models::partner_block::get_partner_block(&mut conn, course_id).await?
    } else {
        // If the course does not exist, create a new partner block with an empty content array
        let empty_content: Option<serde_json::Value> = Some(serde_json::Value::Array(vec![]));

        // Upsert the partner block with the empty content
        models::partner_block::upsert_partner_block(&mut conn, course_id, empty_content).await?
    };

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

/**
DELETE `/api/v0/main-frontend/courses/:course_id` - Delete a partners block in a course.
*/
#[utoipa::path(
    delete,
    path = "/{course_id}/partners-block",
    operation_id = "deleteCoursePartnersBlock",
    tag = "courses",
    params(
        ("course_id" = Uuid, Path, description = "Course id")
    ),
    responses(
        (status = 200, description = "Deleted partners block", body = serde_json::Value)
    )
)]
#[instrument(skip(pool))]
async fn delete_partners_block(
    path: web::Path<Uuid>,
    pool: web::Data<PgPool>,
    user: AuthUser,
) -> ControllerResult<web::Json<PartnersBlock>> {
    let course_id = path.into_inner();
    let mut conn = pool.acquire().await?;
    let token = authorize(
        &mut conn,
        Act::UsuallyUnacceptableDeletion,
        Some(user.id),
        Res::Course(course_id),
    )
    .await?;
    let deleted_partners_block =
        models::partner_block::delete_partner_block(&mut conn, course_id).await?;

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

/**
Add a route for each controller in this module.

The name starts with an underline in order to appear before other functions in the module documentation.

We add the routes by calling the route method instead of using the route annotations because this method preserves the function signatures for documentation.
*/
pub fn _add_routes(cfg: &mut ServiceConfig) {
    cfg.service(web::scope("/{course_id}/stats").configure(stats::_add_routes))
        .service(web::scope("/{course_id}/chatbots").configure(chatbots::_add_routes))
        .service(web::scope("/{course_id}/students").configure(students::_add_routes))
        .route("/{course_id}", web::get().to(get_course))
        .route("", web::post().to(post_new_course))
        .route("/{course_id}", web::put().to(update_course))
        .route("/{course_id}", web::delete().to(delete_course))
        .route(
            "/{course_id}/status-for-all-exercises/{user_id}",
            web::get().to(get_all_exercise_statuses_by_course_id),
        )
        .route(
            "/{course_id}/course-module-completions/{user_id}",
            web::get().to(get_all_course_module_completions_for_user_by_course_id),
        )
        .route(
            "/{course_id}/daily-submission-counts",
            web::get().to(get_daily_submission_counts),
        )
        .route(
            "/{course_id}/daily-users-who-have-submitted-something",
            web::get().to(get_daily_user_counts_with_submissions),
        )
        .route("/{course_id}/exercises", web::get().to(get_all_exercises))
        .route(
            "/{course_id}/exercises-and-count-of-answers-requiring-attention",
            web::get().to(get_all_exercises_and_count_of_answers_requiring_attention),
        )
        .route(
            "/{course_id}/structure",
            web::get().to(get_course_structure),
        )
        .route(
            "/{course_id}/language-versions",
            web::get().to(get_all_course_language_versions),
        )
        .route(
            "/{course_id}/create-copy",
            web::post().to(create_course_copy),
        )
        .route("/{course_id}/upload", web::post().to(add_media_for_course))
        .route(
            "/{course_id}/weekday-hour-submission-counts",
            web::get().to(get_weekday_hour_submission_counts),
        )
        .route(
            "/{course_id}/submission-counts-by-exercise",
            web::get().to(get_submission_counts_by_exercise),
        )
        .route(
            "/{course_id}/course-instances",
            web::get().to(get_course_instances),
        )
        .route("/{course_id}/feedback", web::get().to(get_feedback))
        .route(
            "/{course_id}/feedback-count",
            web::get().to(get_feedback_count),
        )
        .route(
            "/{course_id}/new-course-instance",
            web::post().to(new_course_instance),
        )
        .route("/{course_id}/glossary", web::get().to(glossary))
        .route("/{course_id}/glossary", web::post().to(new_glossary_term))
        .route(
            "/{course_id}/course-users-counts-by-exercise",
            web::get().to(get_course_users_counts_by_exercise),
        )
        .route(
            "/{course_id}/new-page-ordering",
            web::post().to(post_new_page_ordering),
        )
        .route(
            "/{course_id}/new-chapter-ordering",
            web::post().to(post_new_chapter_ordering),
        )
        .route(
            "/{course_id}/references",
            web::get().to(get_material_references_by_course_id),
        )
        .route(
            "/{course_id}/references",
            web::post().to(insert_material_references),
        )
        .route(
            "/{course_id}/references/{reference_id}",
            web::post().to(update_material_reference),
        )
        .route(
            "/{course_id}/references/{reference_id}",
            web::delete().to(delete_material_reference_by_id),
        )
        .route(
            "/{course_id}/course-modules",
            web::post().to(update_modules),
        )
        .route(
            "/{course_id}/default-peer-review",
            web::get().to(get_course_default_peer_review),
        )
        .route(
            "/{course_id}/update-peer-review-queue-reviews-received",
            web::post().to(post_update_peer_review_queue_reviews_received),
        )
        .route(
            "/{course_id}/breadcrumb-info",
            web::get().to(get_course_breadcrumb_info),
        )
        .route(
            "/{course_id}/progress/{user_id}",
            web::get().to(get_user_progress_for_course),
        )
        .route(
            "/{course_id}/user-settings/{user_id}",
            web::get().to(get_user_course_settings),
        )
        .route(
            "/{course_id}/export-submissions",
            web::get().to(submission_export),
        )
        .route(
            "/{course_id}/export-user-details",
            web::get().to(user_details_export),
        )
        .route(
            "/{course_id}/export-exercise-tasks",
            web::get().to(exercise_tasks_export),
        )
        .route(
            "/{course_id}/export-course-instances",
            web::get().to(course_instances_export),
        )
        .route(
            "/{course_id}/export-course-user-consents",
            web::get().to(course_consent_form_answers_export),
        )
        .route(
            "/{course_id}/export-user-exercise-states",
            web::get().to(user_exercise_states_export),
        )
        .route(
            "/{course_id}/page-visit-datum-summary",
            web::get().to(get_page_visit_datum_summary),
        )
        .route(
            "/{course_id}/page-visit-datum-summary-by-pages",
            web::get().to(get_page_visit_datum_summary_by_pages),
        )
        .route(
            "/{course_id}/page-visit-datum-summary-by-device-types",
            web::get().to(get_page_visit_datum_summary_by_device_types),
        )
        .route(
            "/{course_id}/page-visit-datum-summary-by-countries",
            web::get().to(get_page_visit_datum_summary_by_countries),
        )
        .route(
            "/{course_id}/teacher-reset-course-progress-for-themselves",
            web::delete().to(teacher_reset_course_progress_for_themselves),
        )
        .route("/{course_id}/thresholds", web::get().to(get_all_thresholds))
        .route(
            "/{course_id}/suspected-cheaters",
            web::get().to(get_all_suspected_cheaters),
        )
        .route(
            "/{course_id}/suspected-cheaters/flagged-count",
            web::get().to(get_flagged_suspected_cheaters_count),
        )
        .route(
            "/{course_id}/suspected-cheaters/dismiss/{user_id}",
            web::post().to(teacher_dismiss_suspected_cheater),
        )
        .route(
            "/{course_id}/suspected-cheaters/confirm/{user_id}",
            web::post().to(teacher_confirm_suspected_cheater),
        )
        .route(
            "/{course_id}/teacher-reset-course-progress-for-everyone",
            web::delete().to(teacher_reset_course_progress_for_everyone),
        )
        .route(
            "/{course_id}/join-course-with-join-code",
            web::post().to(add_user_to_course_with_join_code),
        )
        .route(
            "/{course_id}/partners-block",
            web::post().to(post_partners_block),
        )
        .route(
            "/{course_id}/partners-block",
            web::get().to(get_partners_block),
        )
        .route(
            "/{course_id}/partners-block",
            web::delete().to(delete_partners_block),
        )
        .route(
            "/{course_id}/set-join-code",
            web::post().to(set_join_code_for_course),
        )
        .route(
            "/{course_id}/reprocess-completions",
            web::post().to(post_reprocess_module_completions),
        )
        .route(
            "/join/{join_code}",
            web::get().to(get_course_with_join_code),
        );
}