starr-philproperties/controllers/client/course_reading_progress.controller.js

/***********************************************************************************************************************************************************************
 * File Name: course_reading_progress.controller.js  (client)
 * Type of Program: Controller
 * Description: Tracks user reading progress through a course hierarchy (course → unit → lesson).
 *
 *   GET  /client/courses/in-progress
 *        → courses where the current user has status = 'in_progress', with lesson counts
 *
 *   GET  /client/courses/:courseId/progress/summary
 *        → compact snapshot: lesson counts + percentage + course status
 *
 *   GET  /client/courses/:courseId/progress
 *        → all progress rows for this user + course (flat, frontend builds the map)
 *
 *   GET  /client/courses/:courseId/task-context
 *        → all pending task requirements (read_*) for this course's UUIDs that the user is assigned to
 *
 *   POST /client/courses/:courseId/units/:unitId/lessons/:lessonId/progress
 *        → UPSERT lesson + derives + UPSERTs parent unit + course in one transaction
 *        → side-effects: writes to lesson_reading_progress / unit_reading_progress,
 *                        syncs task_progress for matching task requirements,
 *                        returns completed_tasks for any task whose read requirements are now all done
 *
 * Author: Kenneth Obsequio (@lash0000)
 * Date Created: Jun. 21, 2026
 ***********************************************************************************************************************************************************************/
'use strict';

const { Op }                        = require('sequelize');
const R                             = require('../../utils/response.util');
const logActivity                   = require('../../utils/logActivity.util');
const { recomputeCascade, recordWatchProgress, recordManualComplete } = require('../../services/completion_requirements.service');
const CourseReadingProgress         = require('../../models/courses/course_reading_progress.mdl');
const Certificate                   = require('../../models/courses/certificate.mdl');
const {
    Course, Unit, Lesson,
    CourseUnit, UnitLesson,
    UnitQuiz, CourseAssessment, QuizAttempt,
} = require('../../models/courses/courses.associations');
const { countCourseLessons, getCourseUnitIds, flattenUnits } = require('../../utils/courses/hierarchy.util');

const { Task, TaskRequirement, TaskListGroup } = require('../../models/task/task.mdl');
const { TaskProgress }                         = require('../../models/task/task_progress.mdl');
const { mdl_UserGroupMembers }                 = require('../../models/users/user_groups.mdl');

const notDeleted = { deletedAt: null };

// ─── Internal helper: get task list IDs accessible to a user ─────────────────
async function getAccessibleTaskListIds(userId) {
    const memberships = await mdl_UserGroupMembers.findAll({
        where: { user_id: userId, deletedAt: null },
        attributes: ['group_id'],
    });
    const groupIds = memberships.map((m) => m.group_id);
    if (!groupIds.length) return { taskListIds: [], taskListToGroup: {} };

    const taskListGroups = await TaskListGroup.findAll({
        where: { group_id: groupIds },
        attributes: ['task_list_id', 'group_id'],
    });
    const taskListToGroup = Object.fromEntries(taskListGroups.map((tlg) => [tlg.task_list_id, tlg.group_id]));
    return { taskListIds: Object.keys(taskListToGroup), taskListToGroup };
}

// Task-progress auto-sync (read_lesson/read_unit/read_course requirements) now lives in
// services/task_reading_progress_sync.service.js#syncCompletedEntitiesToTaskProgress, called
// directly from completion_requirements.service.js's cascade/recompute functions — covers every
// completion trigger (scroll, watch_percent, manual_complete, pass_quiz, assessment), not just
// this endpoint. getAccessibleTaskListIds stays here (below) since getCourseTaskContext still
// needs its richer { taskListIds, taskListToGroup } shape.

// =============================================================================
// ── IN-PROGRESS COURSES — profile learning progress card ──────────────────────
// =============================================================================

exports.getMyInProgressCourses = async (req, res) => {
    try {
        const userId = req.user.user_id;

        const courseRows = await CourseReadingProgress.findAll({
            where:      { user_id: userId, type: 'course' },
            attributes: ['course_id', 'status', 'last_accessed_at'],
            include: [{
                model:      Course,
                as:         'course',
                attributes: ['course_id', 'title'],
                where:      notDeleted,
                required:   true,
            }],
            order: [['last_accessed_at', 'DESC']],
        });

        if (!courseRows.length) return R.success(res, 'No courses in progress.', []);

        const certificates = await Certificate.findAll({
            where:      { user_id: userId },
            attributes: ['course_id'],
        });
        const certSet = new Set(certificates.map((c) => String(c.course_id)));

        const pending = courseRows.filter((r) => !certSet.has(String(r.course_id)));
        if (!pending.length) return R.success(res, 'No courses in progress.', []);

        const result = await Promise.all(pending.map(async (row) => {
            const courseId = row.course_id;

            const [lessons_total, lessons_completed] = await Promise.all([
                countCourseLessons(courseId),
                CourseReadingProgress.count({
                    where: { user_id: userId, course_id: courseId, type: 'lesson', status: 'completed' },
                }),
            ]);

            // "Reading done" is derived independently from lesson counts — row.status now also
            // requires the course assessment to be passed, so it can't be used as the reading gate.
            const readingDone = lessons_total > 0 && lessons_completed === lessons_total;

            let pending_quizzes      = [];
            let pending_assessment   = null;
            let assessment_configured = true;

            if (readingDone) {
                const courseUnitIds = await getCourseUnitIds(courseId);
                const unitQuizzes = courseUnitIds.length ? await UnitQuiz.findAll({
                    attributes: ['quiz_id', 'title', 'is_required', 'passing_score'],
                    include: [{
                        model:      Unit,
                        as:         'unit',
                        attributes: ['unit_id', 'title'],
                        where:      notDeleted,
                        required:   true,
                    }],
                    where: { unit_id: courseUnitIds, ...notDeleted },
                }) : [];

                for (const quiz of unitQuizzes) {
                    const [hasPassed, attemptCount] = await Promise.all([
                        QuizAttempt.findOne({ where: { user_id: userId, quiz_id: quiz.quiz_id, passed: true } }),
                        QuizAttempt.count({ where: { user_id: userId, quiz_id: quiz.quiz_id } }),
                    ]);
                    if (!hasPassed) {
                        pending_quizzes.push({
                            quiz_id:       quiz.quiz_id,
                            title:         quiz.title,
                            unit_title:    quiz.unit.title,
                            is_required:   quiz.is_required,
                            passing_score: quiz.passing_score,
                            attempt_count: attemptCount,
                        });
                    }
                }

                const assessment = await CourseAssessment.findOne({
                    attributes: ['assessment_id', 'title', 'is_required', 'passing_score'],
                    where:      { course_id: courseId },
                });
                assessment_configured = !!assessment;
                if (assessment) {
                    const [hasPassed, attemptCount] = await Promise.all([
                        QuizAttempt.findOne({ where: { user_id: userId, assessment_id: assessment.assessment_id, passed: true } }),
                        QuizAttempt.count({ where: { user_id: userId, assessment_id: assessment.assessment_id } }),
                    ]);
                    if (!hasPassed) {
                        pending_assessment = {
                            assessment_id: assessment.assessment_id,
                            title:         assessment.title,
                            is_required:   assessment.is_required,
                            passing_score: assessment.passing_score,
                            attempt_count: attemptCount,
                        };
                    }
                }
            }

            return {
                course_id:            courseId,
                title:                row.course.title,
                reading_status:       readingDone ? 'completed' : 'in_progress',
                assessment_configured,
                lessons_total,
                lessons_completed,
                last_accessed_at:     row.last_accessed_at,
                pending_quizzes,
                pending_assessment,
            };
        }));

        return R.success(res, 'In-progress courses retrieved.', result);
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][IN PROGRESS]', err);
        return R.error(res, 'Could not retrieve in-progress courses.', 500);
    }
};

// =============================================================================
// ── GET PROGRESS SUMMARY ──────────────────────────────────────────────────────
// =============================================================================

exports.getCourseProgressSummary = async (req, res) => {
    try {
        const { courseId } = req.params;
        const userId       = req.user.user_id;

        const course = await Course.findOne({
            where:      { course_id: courseId, ...notDeleted },
            attributes: ['course_id'],
        });
        if (!course) return R.error(res, 'Course not found.', 404);

        const [lessons_total, lessons_completed, courseRow] = await Promise.all([
            countCourseLessons(courseId),
            CourseReadingProgress.count({
                where: { user_id: userId, course_id: courseId, type: 'lesson', status: 'completed' },
            }),
            CourseReadingProgress.findOne({
                where:      { user_id: userId, course_id: courseId, type: 'course' },
                attributes: ['status'],
            }),
        ]);

        const percent = lessons_total > 0 ? Math.round((lessons_completed / lessons_total) * 100) : 0;

        return R.success(res, 'Progress summary retrieved.', {
            lessons_total,
            lessons_completed,
            percent,
            status: courseRow?.status ?? null,
        });
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][SUMMARY]', err);
        return R.error(res, 'Could not retrieve progress summary.', 500);
    }
};

// =============================================================================
// ── GET PROGRESS SNAPSHOT ─────────────────────────────────────────────────────
// =============================================================================

exports.getCourseProgress = async (req, res) => {
    try {
        const { courseId } = req.params;
        const userId       = req.user.user_id;

        const course = await Course.findOne({
            where:      { course_id: courseId, ...notDeleted },
            attributes: ['course_id'],
        });
        if (!course) return R.error(res, 'Course not found.', 404);

        const rows = await CourseReadingProgress.findAll({
            where: { user_id: userId, course_id: courseId },
            attributes: ['progress_id', 'reference_id', 'type', 'status', 'completed_at', 'last_accessed_at'],
        });

        return R.success(res, 'Course progress retrieved.', rows);
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][GET]', err);
        return R.error(res, 'Could not retrieve course progress.', 500);
    }
};

// =============================================================================
// ── TASK CONTEXT FOR A COURSE ─────────────────────────────────────────────────
// =============================================================================

// GET /client/courses/:courseId/task-context
// Returns all pending task requirements (read_course / read_unit / read_lesson)
// whose reference_id matches this course, any of its units, or any of its lessons,
// filtered to tasks the current user is actually assigned to (via group membership).
// UnitList calls this on mount when no task context is passed via navigation state.

exports.getCourseTaskContext = async (req, res) => {
    try {
        const { courseId } = req.params;
        const userId       = req.user.user_id;

        const course = await Course.findOne({
            where:      { course_id: courseId, ...notDeleted },
            attributes: ['course_id', 'uuid'],
            include: [{
                model:      Unit,
                as:         'units',
                where:      notDeleted,
                required:   false,
                attributes: ['unit_id', 'uuid'],
                through:    { attributes: [] },
                include: [{
                    model:      Lesson,
                    as:         'lessons',
                    where:      notDeleted,
                    required:   false,
                    attributes: ['lesson_id', 'uuid'],
                    through:    { attributes: [] },
                }],
            }],
        });
        if (!course) return R.error(res, 'Course not found.', 404);

        const units      = course.units ?? [];
        const allUuids   = [
            course.uuid,
            ...units.map((u) => u.uuid),
            ...units.flatMap((u) => (u.lessons ?? []).map((l) => l.uuid)),
        ];

        const { taskListIds, taskListToGroup } = await getAccessibleTaskListIds(userId);
        if (!taskListIds.length) {
            return R.success(res, 'Task context retrieved.', { has_task: false, contexts: [] });
        }

        const requirements = await TaskRequirement.findAll({
            where: {
                type:         { [Op.in]: ['read_course', 'read_unit', 'read_lesson'] },
                reference_id: { [Op.in]: allUuids },
                deletedAt:    null,
            },
            include: [{
                model:    Task,
                as:       'task',
                where:    { task_list_id: { [Op.in]: taskListIds }, deletedAt: null },
                required: true,
                attributes: ['task_id', 'name', 'task_list_id'],
            }],
            attributes: ['requirement_id', 'task_id', 'type', 'reference_id', 'reference_label'],
        });

        if (!requirements.length) {
            return R.success(res, 'Task context retrieved.', { has_task: false, contexts: [] });
        }

        // Mark which requirements are already completed
        const taskIds = [...new Set(requirements.map((r) => r.task_id))];
        const doneProgress = await TaskProgress.findAll({
            where:      { task_id: { [Op.in]: taskIds }, user_id: userId, completed: true },
            attributes: ['requirement_id', 'reference_id'],
        });
        const doneSet = new Set(doneProgress.map((p) => `${p.requirement_id}:${p.reference_id}`));

        const contexts = requirements.map((req) => ({
            task_id:           req.task_id,
            task_name:         req.task.name,
            task_list_id:      req.task.task_list_id,
            group_id:          taskListToGroup[req.task.task_list_id],
            requirement_id:    req.requirement_id,
            type:              req.type,
            reference_id:      req.reference_id,
            reference_label:   req.reference_label,
            already_completed: doneSet.has(`${req.requirement_id}:${req.reference_id}`),
        }));

        return R.success(res, 'Task context retrieved.', { has_task: true, contexts });
    } catch (err) {
        console.error('[CLIENT][COURSE TASK CONTEXT]', err);
        return R.error(res, 'Could not retrieve task context.', 500);
    }
};

// =============================================================================
// ── UPSERT LESSON PROGRESS ────────────────────────────────────────────────────
// =============================================================================

// POST /client/courses/:courseId/units/:unitId/lessons/:lessonId/progress
// Body: { status: 'in_progress' | 'completed' }
//
// Flow:
//   1. Resolve course / unit / lesson to get their UUIDs
//   2. Delegate to recomputeCascade (completion_requirements service) — lesson + unit + course
//      evaluated against any configured CompletionRequirement rows (or the default implicit rule),
//      all in one transaction
//   3. Side-effect: sync task_progress for matching task requirements
//   4. Return result + completed_tasks (tasks whose all read requirements are now satisfied)

exports.upsertLessonProgress = async (req, res) => {
    try {
        const { courseId, unitId, lessonId } = req.params;
        const userId = req.user.user_id;
        const status = req.body.status === 'completed' ? 'completed' : 'in_progress';

        const [course, unit, lesson, courseLink, lessonLink] = await Promise.all([
            Course.findOne({
                where:      { course_id: courseId, ...notDeleted },
                attributes: ['course_id', 'uuid'],
            }),
            Unit.findOne({
                where:      { unit_id: unitId, ...notDeleted },
                attributes: ['unit_id', 'uuid'],
            }),
            Lesson.findOne({
                where:      { lesson_id: lessonId, ...notDeleted },
                attributes: ['lesson_id', 'uuid'],
            }),
            CourseUnit.findOne({ where: { course_id: courseId, unit_id: unitId } }),
            UnitLesson.findOne({ where: { unit_id: unitId, lesson_id: lessonId } }),
        ]);

        if (!course)                return R.error(res, 'Course not found.', 404);
        if (!unit || !courseLink)   return R.error(res, 'Unit not found.', 404);
        if (!lesson || !lessonLink) return R.error(res, 'Lesson not found.', 404);

        // ── 1. Consolidated evaluation + persistence: lesson → unit → course ──
        const result = await recomputeCascade(userId, {
            courseId:     course.course_id,
            courseUuid:   course.uuid,
            unitId:       unit.unit_id,
            unitUuid:     unit.uuid,
            lessonId:     lesson.lesson_id,
            lessonUuid:   lesson.uuid,
            lessonStatus: status,
        });

        // Task-progress sync (read_lesson/read_unit/read_course auto-complete) already ran
        // inside recomputeCascade — result.completed_tasks reflects it directly.
        logActivity(userId, 'lesson_read', {
            entityType: 'lesson',
            entityId:   lesson.lesson_id,
            details:    { lesson_uuid: lesson.uuid, status },
        });

        return R.success(res, 'Progress updated.', result, 200);
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][UPSERT]', err);
        return R.error(res, 'Could not update progress.', 500);
    }
};

// =============================================================================
// ── WATCH PROGRESS (watch_percent completion requirement) ────────────────────
// =============================================================================

// POST /client/courses/:courseId/units/:unitId/lessons/:lessonId/watch-progress
// Body: { percent, block_id?, block_type? }  — running max % of video/audio watched, 0-100.
// block_id/block_type identify which block on the lesson's page sent this update — needed
// to drive watch_video/listen_audio (every block of that type must individually reach 100);
// omit them and only the aggregate watch_percent requirement (if configured) is touched.
// No-ops (still 200s) if the lesson has neither requirement type configured.
exports.upsertWatchProgress = async (req, res) => {
    try {
        const { courseId, unitId, lessonId } = req.params;
        const userId  = req.user.user_id;
        const percent = Number(req.body.percent);
        if (!Number.isFinite(percent)) return R.error(res, 'percent must be a number.', 400);
        const blockId   = req.body.block_id ?? null;
        const blockType = req.body.block_type ?? null;

        const [course, unit, lesson, courseLink, lessonLink] = await Promise.all([
            Course.findOne({ where: { course_id: courseId, ...notDeleted }, attributes: ['course_id', 'uuid'] }),
            Unit.findOne({ where: { unit_id: unitId, ...notDeleted }, attributes: ['unit_id', 'uuid'] }),
            Lesson.findOne({ where: { lesson_id: lessonId, ...notDeleted }, attributes: ['lesson_id', 'uuid'] }),
            CourseUnit.findOne({ where: { course_id: courseId, unit_id: unitId } }),
            UnitLesson.findOne({ where: { unit_id: unitId, lesson_id: lessonId } }),
        ]);
        if (!course)                return R.error(res, 'Course not found.', 404);
        if (!unit || !courseLink)   return R.error(res, 'Unit not found.', 404);
        if (!lesson || !lessonLink) return R.error(res, 'Lesson not found.', 404);

        const result = await recordWatchProgress(userId, {
            lessonId: lesson.lesson_id, lessonUuid: lesson.uuid,
            unitId: unit.unit_id, unitUuid: unit.uuid,
            courseId: course.course_id, courseUuid: course.uuid,
            percent, blockId, blockType,
        });

        return R.success(res, 'Watch progress updated.', result, 200);
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][WATCH PROGRESS]', err);
        return R.error(res, 'Could not update watch progress.', 500);
    }
};

// =============================================================================
// ── MARK COMPLETE (manual_complete completion requirement) ───────────────────
// =============================================================================

// POST /client/courses/:courseId/units/:unitId/lessons/:lessonId/mark-complete
// No-ops (still 200s) if the lesson has no configured manual_complete requirement.
exports.markLessonComplete = async (req, res) => {
    try {
        const { courseId, unitId, lessonId } = req.params;
        const userId = req.user.user_id;

        const [course, unit, lesson, courseLink, lessonLink] = await Promise.all([
            Course.findOne({ where: { course_id: courseId, ...notDeleted }, attributes: ['course_id', 'uuid'] }),
            Unit.findOne({ where: { unit_id: unitId, ...notDeleted }, attributes: ['unit_id', 'uuid'] }),
            Lesson.findOne({ where: { lesson_id: lessonId, ...notDeleted }, attributes: ['lesson_id', 'uuid'] }),
            CourseUnit.findOne({ where: { course_id: courseId, unit_id: unitId } }),
            UnitLesson.findOne({ where: { unit_id: unitId, lesson_id: lessonId } }),
        ]);
        if (!course)                return R.error(res, 'Course not found.', 404);
        if (!unit || !courseLink)   return R.error(res, 'Unit not found.', 404);
        if (!lesson || !lessonLink) return R.error(res, 'Lesson not found.', 404);

        const result = await recordManualComplete(userId, {
            entityType: 'lesson', entityId: lesson.lesson_id,
            lessonUuid: lesson.uuid,
            unitId: unit.unit_id, unitUuid: unit.uuid,
            courseId: course.course_id, courseUuid: course.uuid,
        });

        return R.success(res, 'Lesson marked complete.', result, 200);
    } catch (err) {
        console.error('[CLIENT][COURSE READING PROGRESS][MARK COMPLETE]', err);
        return R.error(res, 'Could not mark lesson complete.', 500);
    }
};