Mermutef/LMS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a2daf2fecc0c0c132195db5a6e9101a1b37bba8
LMS/docs/12-stage2-report.md

12 KiB
Raw Blame History

12. Отчёт этапа 2: academic (курсы и лабораторные)

Дата: 2026-10-27. Статус: этап 2 выполнен; этап 3 (доступ и профиль студента курса) — следующий.

1. Что сделано

Курсы

  • Добавлены таблицы courses, course_teachers, course_groups (миграция V6).
  • courses.course_no — BIGINT GENERATED ALWAYS AS IDENTITY, уникальный номер для человекочитаемых URL; UUID остаётся первичным ключом.
  • CRUD курсов: создание, просмотр, переименование, перевод в архив и возврат в работу. Название нормализуется (trim), пустое заменяется на «Новый курс».
  • Название курса уникально без учёта регистра (миграция V10, индекс по lower(title)); повторное создание возвращает 409.
  • Назначение и снятие преподавателей, привязка и отвязка групп хранятся с историей: снятие/отвязка проставляют removed_at, запись не удаляется. Повторное назначение после снятия создаёт новую активную запись.
  • Для архивированного курса запрещены новые назначения преподавателей и привязка групп.

Bootstrap курса C

  • CourseBootstrapService идемпотентно создаёт (или находит) курс «Промышленное программирование на языке C», назначает владельцем текущего админа и переносит в него существующие данные.
  • Конкурентные запуски сериализуются advisory-локом pg_advisory_xact_lock(hashtext('academic.course.bootstrap')).
  • Перед переносом проверяются дубли номеров лабораторных без курса. При дублях bootstrap завершается 409, транзакция откатывается, курс не создаётся.
  • Все активные группы, переданные из web, привязываются к курсу (повторный запуск не создаёт дублей).
  • Всем лабораторным и главам без курса проставляется course_id = C; у курсовых глав audience сбрасывается в NULL.
  • После переноса, если лабораторных без курса не осталось, сервис в рантайме выполняет ALTER TABLE academic.labs ALTER COLUMN course_id SET NOT NULL. Это post-bootstrap шаг, а не Flyway-файл: обычный старт Flyway не может дождаться создания курса и назначения владельца.

Лабораторные

  • labs.course_id добавлен nullable-миграцией V7; уникальность номера — в рамках курса: (number, course_id).
  • Создание и импорт лабораторной требуют курс; архивированный курс отклоняется с 400.
  • Список лабораторных фильтруется по courseId; API и UI показывают номер и название курса у каждой лабораторной.
  • Копирование лабораторной в другой курс (LabCopyService): копируются описание, уровни и варианты с новыми id, копия создаётся черновиком. Оценки, сдачи, защиты и назначения вариантов не копируются.
  • Копирование запрещено в тот же курс и в архивированный курс; занятый номер в целевом курсе даёт 409.

Админ-UI

  • /admin/courses — список курсов с номером, названием, статусом и счётчиками преподавателей, групп и лабораторных; создание курса; блок первичного bootstrap, пока курсов нет.
  • /admin/courses/{id} — карточка курса: архивирование/возврат, привязка и отвязка групп, назначение и снятие преподавателей по UUID аккаунта, список лабораторных курса.
  • /admin/labs — фильтр по курсу, колонка курса, выбор курса (обязательный) в формах импорта и создания.
  • /admin/labs/{id} — карточка лабораторной показывает курс; кнопка «Копировать в курс» открывает форму выбора целевого курса, номера и названия.
  • В навигацию админа добавлен пункт «Курсы».

Миграции

  • V6__courses.sql — курсы, преподаватели, группы курса.
  • V7__labs_course.sql — labs.course_id, уникальность (number, course_id).
  • V8__chapters_course.sql — chapters.course_id/audience, частичные индексы slug.
  • V9__article_assets_indexes.sql — индекс article_assets(article_id).
  • V10__course_title_unique.sql — уникальный индекс lower(title) по курсам.

2. API

Все эндпоинты курсов доступны только роли ADMIN.

Метод Путь Назначение
GET /api/v1/courses список курсов со счётчиками
POST /api/v1/courses создать курс, владелец — текущий админ
GET /api/v1/courses/{id} карточка курса с историей преподавателей и групп
PUT /api/v1/courses/{id} изменить название и/или статус
POST /api/v1/courses/{id}/teachers назначить преподавателя
DELETE /api/v1/courses/{id}/teachers/{accountId} снять преподавателя
POST /api/v1/courses/{id}/groups привязать группу
DELETE /api/v1/courses/{id}/groups/{groupId} отвязать группу
POST /api/v1/courses/bootstrap создать курс C и перенести данные
GET /api/v1/labs?courseId=… список лабораторных, опционально по курсу
POST /api/v1/labs создать лабораторную с обязательным courseId
POST /api/v1/labs/import?courseId=… импорт ZIP в указанный курс
POST /api/v1/labs/{id}/copy копировать лабораторную в другой курс

LabSummary и LabDetail дополнены полями courseId, courseNo, courseTitle. В браузерных URL курса используется course_no; API работает с UUID.

3. Порядок bootstrap

  1. Админ открывает /admin/courses. Пока курсов нет, показывается блок первичной настройки.
  2. Web передаёт в POST /api/v1/courses/bootstrap название (необязательно) и id всех активных групп.
  3. Сервис берёт advisory-лок, проверяет UUID групп, находит или создаёт курс по названию без учёта регистра (владелец — текущий админ).
  4. Привязывает активные группы, проверяет дубли номеров лабораторных без курса.
  5. Проставляет course_id лабораторным и главам.
  6. Если лабораторных без курса не осталось, выполняет SET NOT NULL для labs.course_id.
  7. Возвращает courseId, courseNo, название и счётчики: сколько групп привязано, лабораторных и глав перенесено, сколько осталось без курса.
  8. Повторный запуск безопасен: существующий курс переиспользуется, уже привязанные группы и перенесённые данные не дублируются.

4. Тесты

Добавлены интеграционные тесты на PostgreSQL (Testcontainers):

  • CourseServiceIntegrationTest (6 тестов): отказ bootstrap при дублях номеров без создания курса, создание курса и перенос групп/лабораторных/глав, идемпотентность bootstrap, генерация уникальных course_no, запрет дубликата названия без учёта регистра, история назначений преподавателей и групп, отказ при некорректном UUID группы.
  • LabCopyIntegrationTest (5 тестов): копирование с уровнями и вариантами, обязательный курс при создании, запрет копирования в тот же курс, в архивированный курс и создание лабораторной в архивированном курсе.

Прогон 2026-10-27: ./gradlew :services:academic-service:test :web:test — успешно, в новых наборах 0 failures / 0 errors. git diff --check — успешно.

5. Известные пробелы (этап 3)

  • Материалы курса и аудитории. Схема chapters.course_id/audience готова (V8), но URL /learn/course/{course_no}/... и проверка аудитории ещё не реализованы: читалка материалов пока работает по прежним глобальным правилам.
  • Активы. V9 добавляет только индекс; наследуемая видимость активов от статьи → раздела → главы и проверка доступа при выдаче файлов — этап 3.
  • Проверка аккаунтов преподавателей. Academic принимает UUID без обращения к identity: не проверяются существование аккаунта, роль TEACHER и статус ACTIVE. Нужна внутренняя проверка identity при назначении.
  • Кабинет преподавателя и скоупинг. API курсов пока admin-only; кабинет /teacher/..., доступ преподавателя только к своим курсам и студентам, профиль студента курса и negative-тесты «чужой курс/студент/сдача» — этап 3.
  • Повторный bootstrap из UI. Кнопка bootstrap показывается только когда курсов нет; повторный запуск возможен через API. Группы, появившиеся позже, привязываются вручную на странице курса.