courses.md

Courses

Назначение

Курсы отвечают за обучение пользователей внутри Procollab: список курсов, доступность, структуру курса, прохождение уроков, ответы на задания, прогресс и экспорт результатов.

Статус модуля

Модуль находится в хорошем состоянии и может использоваться как ориентир для рефакторинга других частей backend.

Основные возможности

• просмотр списка доступных курсов;
• просмотр карточки курса;
• просмотр структуры курса: модули, уроки, задания;
• контроль доступности курса, модуля, урока и задания;
• отправка ответов на задания;
• поддержка заданий с ручной проверкой;
• пересчет прогресса пользователя;
• экспорт результатов курса из Django admin.

Архитектура

• courses/models/ - модели курса, контента, ответов и прогресса.
• courses/api/views/ - HTTP endpoints.
• courses/api/serializers/ - request и response contracts.
• courses/queries/ - сборка read payload для API.
• courses/services/ - бизнес-логика: доступы, ответы, прогресс, экспорт.
• courses/admin_config/ - настройка Django admin.
• courses/tests/ - тесты модуля.

Основные сущности

• Course - курс.
• CourseModule - модуль курса.
• CourseLesson - урок.
• CourseTask - задание.
• CourseTaskOption - вариант ответа.
• UserTaskAnswer - ответ пользователя.
• UserCourseProgress - прогресс по курсу.
• UserModuleProgress - прогресс по модулю.
• UserLessonProgress - прогресс по уроку.

API

• GET /courses/ - список курсов.
• GET /courses/<id>/ - детали курса.
• GET /courses/<id>/structure/ - структура курса.
• POST /courses/<id>/visit/ - отметка посещения курса.
• GET /courses/lessons/<id>/ - детали урока.
• POST /courses/tasks/<id>/answer/ - отправка ответа на задание.

Основные сценарии

1. Выбор курса

Пользователь открывает список курсов и видит доступные ему карточки. Для каждой карточки отображаются статус, период доступности, состояние действия (start, continue, lock) и текущий прогресс.

Доступность курса зависит от:

• статуса курса;
• типа доступа;
• участия пользователя в партнерской программе;
• дат начала и окончания курса;
• факта завершения курса.

2. Выбор модуля

После открытия курса пользователь видит структуру из модулей. Модуль доступен, если доступен сам курс, модуль опубликован, наступила дата старта модуля и предыдущий модуль завершен.

Для каждого модуля отображаются уроки, прогресс и состояние доступности.

3. Выбор урока

Пользователь может открыть только доступный опубликованный урок. Урок доступен, если доступен его модуль и предыдущий урок завершен.

Урок состоит из заданий. Поддерживаются два основных типа заданий:

• информационные задания - пользователь должен ознакомиться с материалом;
• задания с ответом - пользователь должен отправить текст, выбрать вариант или прикрепить файл.

Для заданий с ответом поддерживаются разные типы ответа:

• текст;
• один вариант;
• несколько вариантов;
• файл;
• текст и файл.

4. Прохождение урока

Пользователь проходит задания урока по порядку. Следующее задание открывается после завершения текущего.

После отправки ответа система обновляет:

• прогресс урока;
• прогресс модуля;
• прогресс курса;
• текущее задание пользователя.

Если урок, модуль или курс завершены полностью, их прогресс становится 100%.

5. Проверка ответов

Задания могут проверяться автоматически или вручную.

При автоматической проверке результат определяется сразу после отправки ответа. Если ответ принят, пользователь может продолжить прохождение.

При ручной проверке ответ получает статус pending_review. Администратор проверяет ответ в Django admin и выставляет итоговый статус. После изменения review-полей прогресс пользователя пересчитывается автоматически.

Ограничения и правила

• file_ids в ответах могут ссылаться только на файлы текущего пользователя.
• Доступ к урокам и заданиям зависит от порядка прохождения.
• Для опубликованных choice-заданий должен быть корректный набор правильных вариантов.
• Upload flow в Django admin использует временные флаги _has_pending_*; это зафиксированный технический долг.

Тесты

Тесты модуля лежат в courses/tests/ и разделены по уровням.

API и пользовательские сценарии

• test_api.py - базовый flow прохождения курса через HTTP API.
• test_api_extended.py - расширенные сценарии: частичный прогресс, блокировка следующих уроков, choice-задания, файлы и text_and_files.

Эти тесты проверяют поведение, видимое фронтенду: status code, response payload, доступность элементов и изменение прогресса после действий пользователя.

Бизнес-логика

• test_access.py - доступность курса, модуля и урока, action state и date labels.
• test_progress.py - расчет процентов, статусов, обновление progress-записей, посещение курса и сложный regression-сценарий с несколькими модулями, уроками и ручной проверкой.
• test_learning_flow.py - порядок прохождения заданий и доступность текущего задания.
• test_answers.py - отправка ответов, with_review flow и пересчет прогресса после проверки через Django admin.

Model validation

• test_answers.py - validation для UserTaskAnswer, UserTaskAnswerOption, UserTaskAnswerFile.
• test_content_models.py - validation для CourseModule, CourseTask и CourseTaskOption.

Эти тесты фиксируют доменные ограничения модели: обязательные поля для разных типов заданий, допустимые типы ответов, правила choice-вариантов, лимиты файлов и review-поля.

Admin и экспорт

• test_export.py - экспорт результатов курса из Django admin.
• test_answers.py - ручная проверка ответа через admin и автоматический пересчет прогресса.

Что считается критичным

Критичные regression-сценарии:

• пользователь не может открыть недоступный урок;
• пользователь проходит задания строго по порядку;
• file_ids не могут ссылаться на файлы другого пользователя;
• with_review ответ блокирует продолжение до проверки;
• после ручной проверки пересчитывается прогресс урока, модуля и курса;
• сложный курс с несколькими модулями и уроками считает частичный прогресс корректно;
• опубликованные choice-задания не могут быть некорректно сконфигурированы.