LMS/docs/16-stage6-report.md

16. Отчёт этапа 6: проверка, hardening и передача

Дата: 2026-10-27. Ветка: feature/groups-courses. Статус: проверка этапа 6 выполнена; этап 6 закрыт не полностью. Миграции, security-матрица, upgrade-тест, видимость активов и deploy-runbook проверены. Открытыми остаются права преподавателя на запись, аудит и CI — см. раздел 4.

1. Итоговый объём этапов 0–5

Этап	Что реализовано	Отчёт
0	Схема и контракты: identity V4–V9, academic V6–V12, progress V13; preflight-скрипты; ADR; контракт профиля студента курса	10
1	Роли ADMIN/TEACHER/STUDENT, группы-когорты и парсер имени, статусы студентов и аккаунтов, membership_history, импорт v2	11
2	Курсы, course_no для браузерных URL, история преподавателей и групп, bootstrap курса C, привязка лабораторных к курсу, копирование лабораторных, админ-UI	12
3	Аккаунты преподавателей, курсовая область видимости, внутренние API identity с LMS_INTERNAL_TOKEN, кабинет преподавателя, профиль студента курса и скачивание всех попыток	13
4	Повышение (dry-run/apply/rollback, планировщик 31 августа МСК), академотпуск, отчисление, выпуск, архив/восстановление, усиленное удаление, блокировка входа	14
5	Курсовые материалы /learn/course/{course_no}/..., публичные глобальные материалы ALL, скрытые материалы для преподавателя, перепроверка статуса web-сессии	15

Ключевые инварианты, действующие после этапов 0–5:

• все лабораторные принадлежат курсу; существующие лабораторные, главы и активные группы перенесены в курс C;
• API работает с UUID курса, браузерные URL — с course_no;
• преподаватель видит только активные назначенные курсы; студент — только курсы активной группы; админ — все курсы;
• студент видит только опубликованные оценки и комментарии;
• активы наследуют видимость статьи → раздела → главы: курсовые требуют доступа к курсу, глобальные — аудитории, а старые файлы без привязки остаются публичными (см. раздел 4);
• вход закрыт для отчисленных, выпущенных и архивных студентов, а также для архивных аккаунтов; web дополнительно перепроверяет статус;
• повышение и жизненный цикл пишут историю; применение повышения идемпотентно.

2. Проверка

2.1. Сборка, тесты и линтеры

Выполнено 2026-10-27:

./gradlew test ktlintCheck detekt

Результат: BUILD SUCCESSFUL, код возврата 0, все модули зелёные.

Счётчики включают новые тесты видимости активов: academic-service +9 (ContentAssetAccessIntegrationTest, импорт активов), web +2 (ApiClientContentAssetTest). Итог — 183 теста, 0 падений.

Для получения актуальных счётчиков тесты запущены принудительно:

./gradlew test --rerun-tasks

Модуль	Тестов	Failures	Errors	Skipped
identity-service	62	0	0	0
academic-service	62	0	0	0
web	42	0	0	0
progress-service	12	0	0	0
markdown	5	0	0	0
Итого	183	0	0	0

ktlintCheck и detekt прошли без замечаний. Отдельных unit-тестов у gateway и common-http в текущем дереве нет; маршрутизация gateway проверена конфигурацией и security-матрицей ниже.

2.2. Upgrade-тест миграций

Проверка выполнена на одноразовом PostgreSQL 18 (Testcontainers/контейнер, не production-БД):

1. Развёрнута схема master: identity V1–V3, academic V1–V5, progress V1–V9, V11, V12.
2. Загружены синтетические данные: администратор и два студента, две группы (ПИ-11БО, ПИ-21БО), зачисления, семестр, лабораторная, глава/раздел/ статья/актив, оценка, комментарий и попытка сдачи.
3. Поверх master применены миграции ветки:
   • identity V4–V9;
   • academic V6–V12;
   • progress V13.
4. Выполнены postflight-запросы и повторное применение V13.

Результат: успешно, без ошибок.

• identity: группы разобраны в stream/course/number/degree/enrollment_year (ПИ-11БО → поток ПИ, курс 1, номер 1, БО, год набора 2026; ПИ-21БО → курс 2, год 2025); статус ACTIVE; созданы promotion_runs, promotion_run_items; зачисления перенесены в membership_history действием ENROLL; добавлен accounts.status.
• academic: добавлены labs.course_id, chapters.course_id/audience, индексы labs_number_course_uidx, chapters_slug_global_uidx, chapters_slug_course_uidx, article_assets_article_idx, courses_title_lower_uidx. V12__asset_links_backfill.sql восстанавливает связи article_assets из markdown-ссылок /api/v1/content/assets/{name}; файлы без ссылок остаются несвязанными. Курс C миграциями не создаётся — его создаёт bootstrap после входа админа, поэтому labs_without_course до bootstrap ожидаемо больше нуля.
• progress: grade_comments.author_account_id и lab_grades.updated_by_account_id созданы как nullable uuid; индекс lab_grades_lab_idx существует и валиден; старый комментарий остался без автора, как и задумано.
• V13 идемпотентна: повторное применение V13 (дважды) завершилось сообщениями already exists, skipping и не изменило схему. Это же проверяет ProfileAuthorsMigrationTest на Testcontainers.
• progress V10 отсутствует: в ветке нет progress-service/.../V10__profile_authors.sql; в истории прогресса применяются V11, V12, затем V13. У academic V10 — это другой файл, V10__course_title_unique.sql (уникальный индекс названия курса).
• Переход forward-only: после V13 откат на сборку без неё не пройдёт валидацию Flyway; out-of-order включать нельзя.

2.3. Security-проверки

Проверено автоматическими тестами (полный прогон 183 теста) и разбором конфигурации gateway.

Сценарий	Ожидание	Факт
Аноним → курс/материалы курса	нет доступа	401 на /api/v1/courses/{id}/content/tree; /api/v1/courses/by-no/{no} — 401
Аноним → публичные материалы	только глобальные ALL	публичное дерево содержит только глобальные главы с audience = ALL; курсовая глава через /api/v1/content/... — 404
Аноним → актив глобальной ALL-статьи	публично	200
Аноним → курсовой/STUDENTS/TEACHERS актив	404	404, существование файла не раскрывается
Студент своего курса → актив опубликованной статьи	доступ	200; скрытый курсовой актив — 404
Студент/преподаватель чужого курса → курсовой актив	403	403
Преподаватель своего курса → скрытый курсовой актив	доступ	200; админ видит любой актив
Глобальный STUDENTS-актив → преподаватель	403	403; студент получает 200
Legacy-актив без связи со статьёй	публично	200; остаточный риск, раздел 4
Админ → курс, профиль, скачивание	полный доступ	доступ к любому курсу и студенту, скачивание любой попытки курса
Преподаватель своего курса	курс, группы, профиль, материалы	видит опубликованные и скрытые материалы, всех студентов активной группы курса, неопубликованные оценки и все попытки
Преподаватель чужого курса	403	403 на материалы, курс по course_no, состав группы и профиль
Студент → свой профиль	только своё и опубликованное	скрытые оценки/комментарии отсутствуют; чужой studentId — 403
Студент → чужой курс/группа	403	доступ только к курсам активной группы; архивный курс — 403
Чужая сдача / лаба другого курса	403	скачивание отклоняется; своя попытка курса скачивается ZIP
Внутренние API identity	только по токену	неверный/пустой X-Internal-Token — 403, сравнение constant-time; неизвестный id — 404
Gateway	внутренние пути не публикуются	маршрутов на /api/v1/internal/** нет; gateway требует JWT для всего, кроме /actuator, входа/setup/JWKS и публичного /api/v1/content/**
Gateway → заголовки личности	клиент не подменяет	X-Account-Id/Login/Role удаляются и проставляются только после проверки JWT
Web-сессия	быстрый отзыв доступа	статус перепроверяется не реже чем раз в 45 секунд; active=false или 401/403 инвалидируют сессию; недоступность identity не разлогинивает всех

Остаточные риски перечислены в разделе 4: legacy-активы без привязки, права преподавателя на запись и 30-дневный JWT для прямого API.

3. Чек-лист деплоя

3.1. Перед деплоем

• Backup обязателен. Выполнить ./deploy/backup.sh backup и ./deploy/backup.sh verify <dir>. ./deploy/deploy.sh up сам вызывает backup.sh backup --if-running; при ошибке backup деплой прерывается. Backup на том же сервере не считается единственной защитой.
• В .env.prod задан LMS_INTERNAL_TOKEN — длинная случайная строка (openssl rand -hex 32), одинаковая для identity, academic и progress. Значение по умолчанию dev-internal-token в production не использовать. Там же задан LMS_DB_PASSWORD; .env.prod не коммитится.
• Проверить, что на сервере нет незакоммиченных изменений и выполнен git pull нужной ветки/тега.

3.2. Порядок выкладки

1. Flyway. ./deploy/deploy.sh up собирает образы и запускает postgres → identity → academic → progress → gateway → web. Миграции применяются автоматически при старте сервисов: identity V4–V9, academic V6–V12, progress V13. Отдельный ручной запуск Flyway не нужен.
2. Bootstrap курса C. После входа админа открыть /admin/courses. Пока курсов нет, показан блок первичной настройки. Bootstrap идемпотентно создаёт/находит курс «Промышленное программирование на языке C», привязывает активные группы, переносит лабораторные и главы и, если лабораторных без курса не осталось, выполняет ALTER TABLE academic.labs ALTER COLUMN course_id SET NOT NULL. Это post-bootstrap шаг в рантайме, а не Flyway-миграция. Повторный запуск безопасен. Если в БД уже есть курс C, bootstrap не требуется.
3. Postflight. Выполнить psql -h localhost -U lms -d lms -f deploy/preflight/groups-courses-post.sql и проверить:
   • labs_without_course = 0;
   • chapters_without_course = 0 (если все текущие материалы курсовые);
   • ровно один курс C;
   • comments_without_author соответствует старым комментариям;
   • группы без полного разбора отсутствуют.
4. V10 → V13 — только dev/staging. На production/master записи progress V10__profile_authors.sql нет, ничего удалять не нужно. Не путать с academic V10__course_title_unique.sql — он относится к другой схеме и должен применяться как обычно. Если БД когда-либо применяла старую feature-миграцию V10:
   • сделать backup;
   • проверить deploy/preflight/progress-v10-v13.sql (columns_ok и index_ok должны быть true);
   • удалить только строку истории V10 (success=true) через flyway repair или точечный DELETE из примера в скрипте; объекты схемы не удалять;
   • при success=false сначала убедиться, что частичные объекты откатились;
   • не переставлять V11/V12 и не включать out-of-order. После V13 переход forward-only.

3.3. Smoke после деплоя

• docker compose -f docker-compose.prod.yml --env-file .env.prod ps — все контейнеры running; curl -fsS http://127.0.0.1:8090/actuator/health отдаёт UP.
• Админ: вход, /admin/courses (курс C и счётчики), /admin/groups, /admin/labs, /admin/teachers, /admin/promotion.
• Преподаватель: вход, /teacher, карточка своего курса, состав группы, профиль студента, скачивание попытки, курсовые материалы.
• Студент: вход, дашборд, лабораторная, сдача/история, курсовые материалы; видны только опубликованные оценки и комментарии.
• Материалы курса: админ и преподаватель видят скрытые статьи, студент — только опубликованные; чужой курс даёт 403, аноним уходит на /login.
• Активы: картинки курсовой статьи открываются у студента своего курса и преподавателя; чужой курс — 403, скрытая картинка у студента — 404, публичная ALL — без входа; старый файл без привязки — публичен.
• Копирование лабораторной: админ копирует лабораторную в другой курс; создаётся черновик с уровнями и вариантами; оценки, сдачи, защиты и назначения не копируются; занятый номер даёт 409.
• Профиль: преподаватель своего курса видит сводку, комментарии, все попытки и скачивает ZIP; чужой студент/курс — 403.
• Повышение: /admin/promotion строит dry-run за год, данные не меняются; применение — только после проверки плана; откат доступен для завершённого запуска. На production не применять план «на всякий случай».
• Проверить логи web, gateway, identity, academic, progress на ERROR/WARN после smoke.

4. Известные пробелы и follow-up

1. Legacy-активы без привязки. Видимость связанных активов реализована: V12 восстанавливает article_assets по markdown-ссылкам, а маршрут /api/v1/content/assets/{name} проверяет курс/аудиторию и публикацию. Остаточный случай — файлы, на которые нет ссылок ни в одной статье: они остаются публичными. Нужна инвентаризация и привязка либо удаление таких файлов; до этого fallback сохраняется, чтобы не ломать старые ссылки. Детали — в 15.
2. Права преподавателя в основном read-only. Кабинет преподавателя даёт обзор курса, групп, лабораторных и профилей. Авторство лабораторных и материалов, распределение вариантов, выставление оценок, комментарии, коды защиты и действия защиты остаются admin-only в UI/API. ТЗ (07, раздел ролей) ожидает преподавательский self-service; это главный функциональный разрыв.
3. Названия групп в кабинете преподавателя. На странице курса группа показывается UUID: academic отдаёт groupId, а имя группы не входит в контракт карточки курса. Нужен batch-запрос имён в identity или расширение DTO. Тест TeacherGroupTemplateTest фиксирует fallback на id.
4. Аудит чувствительных действий. Есть membership_history (переводы, академ, отчисление, архив, повышение) и журнал promotion_runs/items. Отдельного audit-log для скачиваний файлов, просмотра профилей, назначений преподавателей и публикаций нет. Нужна таблица audit_events и запись из сервисов/BFF.
5. Старый формат импорта не поддерживается. Импорт принимает только шаблон v2 (поток/курс/номер/степень/год/ФИО/№/база). Ведущие нули номера группы нормализуются к числу (01 → 1), поэтому ПИ-01БО и ПИ-1БО неразличимы; для разных когорт нужен строковый номер. Ограничение зафиксировано в 11.
6. JWT живёт до 30 дней. Web-сессия перепроверяет статус каждые 45 секунд и закрывает UI при отчислении/архиве, но уже выданный JWT для прямого вызова API действует до истечения. Нужны короткий TTL + refresh, denylist/revocation или проверка статуса на каждом API-вызове.
7. Нет CI. В репозитории нет pipeline (.github и аналогов); гейтом служит локальный ./gradlew test ktlintCheck detekt. Это не защищает ветку от merge без прогона и не проверяет upgrade-тест автоматически.

5. Рекомендуемые следующие шаги

Приоритет — сверху вниз:

1. Права преподавателя на запись. Дать преподавателю своего курса authoring лабораторных/материалов, распределение вариантов, выставление оценок и комментариев, коды и действия защиты; закрыть negative-тестами «свой/чужой курс». Это закрывает основной разрыв с ТЗ.
2. Инвентаризация legacy-активов. Найти файлы без строк в article_assets, привязать их к статьям или удалить; после этого можно убрать публичный fallback для несвязанных файлов.
3. UI авторства контента. Выбор курса и аудитории при создании глав/ статей, чтобы преподаватель и админ не работали только через импорт; сейчас глобальные главы создаются с ALL, курсовые — без аудитории.
4. Аудит. Ввести audit_events для скачиваний, профилей, назначений, публикаций, повышения и жизненного цикла; экран просмотра для админа.
5. CI. Пайплайн на каждый push/MR: test ktlintCheck detekt, отдельный шаг upgrade-теста миграций на PostgreSQL 18, сборка bootJar; запрет merge при красном статусе.

6. Итог

Этапы 0–5 реализованы и проверены. Security-матрица, upgrade-тест миграций, видимость активов и deploy-runbook этапа 6 зелёные; отчёт и чек-лист передачи готовы. Этап 6 нельзя считать полностью завершённым до закрытия прав преподавателя и CI. Видимость связанных активов реализована; публичными остаются только старые файлы без привязки к статье (см. раздел 4), а преподаватели пока работают в режиме просмотра.