LMS/docs/16-stage6-report.md

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

Дата: 2026-10-27, обновлено 2026-10-28 после закрытия продуктовых рисков. Ветка: feature/groups-courses. Статус: этап 6 закрыт. Продуктовые риски (legacy-активы, срок жизни JWT, сессии, пагинация аудита и N+1 имён групп) закрыты; оставшиеся ограничения перечислены в разделе 4 и не блокируют передачу.

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

Этап	Что реализовано	Отчёт
0	Схема и контракты: identity V4–V11 (V10 — аудит, V11 — refresh-токены), 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
6	Права преподавателя на запись (лабораторные, ведомость, группы, материалы), центральный аудит identity.audit_events, CI merge gate, hardening и deploy-runbook	этот отчёт

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

• все лабораторные принадлежат курсу; существующие лабораторные, главы и активные группы перенесены в курс C;
• API работает с UUID курса, браузерные URL — с course_no;
• преподаватель видит только активные назначенные курсы; студент — только курсы активной группы; админ — все курсы;
• студент видит только опубликованные оценки и комментарии;
• активы наследуют видимость статьи → раздела → главы: курсовые требуют доступа к курсу, глобальные — аудитории, а файлы без связи со статьёй по умолчанию недоступны (404) всем, кроме админа; админ перечисляет их через GET /api/v1/content/legacy-assets;
• access-токен живёт 15 минут, refresh — 7 дней с ротацией и отзывом; web-сессия скользящая на 7 дней и сама обновляет access-токен;
• преподаватель своего курса может писать: лабораторные/уровни/варианты, ведомость, привязка групп и авторские материалы курса; чужие курс, лаба, студент и группа отклоняются на сервисах;
• вход закрыт для отчисленных, выпущенных и архивных студентов, а также для архивных аккаунтов; web дополнительно перепроверяет статус;
• повышение и жизненный цикл пишут историю; применение повышения идемпотентно;
• чувствительные действия пишутся в центральный identity.audit_events, админ смотрит журнал на /admin/audit;
• CI на каждый push/MR прогоняет test ktlintCheck detekt.

2. Проверка

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

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

./gradlew --no-daemon test ktlintCheck detekt

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

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

./gradlew test --rerun-tasks

Модуль	Тестов	Failures	Errors	Skipped
identity-service	72	0	0	0
academic-service	88	0	0	0
progress-service	33	0	0	0
web	69	0	0	0
markdown	5	0	0	0
Итого на момент этапа 6	267	0	0	0

После закрытия рисков актуальный LDD-baseline — 319 тестов, 0 failures (см. раздел 7). ktlintCheck и detekt прошли без замечаний. У gateway теперь есть unit-тесты публичных auth-путей и 401; маршрутизация gateway дополнительно проверена конфигурацией и security-матрицей ниже. Тот же набор команд выполняет .gitlab-ci.yml; на каждый push/MR добавлен smoke-job, полный release-evidence обязателен для тегов.

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–V11;
   • 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; V10 создаёт identity.audit_events без внешних ключей и индексы по occurred_at/action; V11 создаёт identity.refresh_tokens (SHA-256-хеш, expires_at, revoked_at, replaced_by, индексы по аккаунту и сроку).
• 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-проверки

Проверено автоматическими тестами (актуальный прогон — 319 тестов, 0 failures) и разбором конфигурации gateway. Запись преподавателя дополнительно покрыта negative-тестами «свой/чужой курс».

Сценарий	Ожидание	Факт
Аноним → курс/материалы курса	нет доступа	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-актив без связи со статьёй	404 для анонима/студента/преподавателя, файл доступен только админу	404 всем, кроме ADMIN; GET /api/v1/content/legacy-assets под ROLE_ADMIN перечисляет несвязанные файлы
Access/refresh	короткий access + ротация refresh	access JWT 15 минут (LMS_ACCESS_TOKEN_TTL), refresh 7 дней (LMS_REFRESH_TOKEN_TTL); POST /api/v1/auth/refresh ротирует пару, повторное использование старого токена отзывает все сессии аккаунта
Logout / смена пароля	сессии отзываются	POST /api/v1/auth/logout отзывает refresh; смена пароля — revokeAll
Архив/отчисление/закрытая группа → refresh	обновление запрещено	ensureSessionAllowed при ротации: EXPELLED, GRADUATED, ARCHIVED, архивный аккаунт и GRADUATED/ARCHIVED группа дают 401
Web-сессия	7 дней sliding, без повторного входа, быстрый отзыв	cookie LMS_SESSION, Max-Age 7 дней (LMS_SESSION_TIMEOUT), HttpOnly/SameSite=Lax; access обновляется за 2 минуты до истечения, cookie перевыпускается на каждом ответе; статус перепроверяется не реже чем раз в 45 секунд, active=false или 401/403 инвалидируют сессию, недоступность identity не разлогинивает всех; выход отзывает refresh
Админ → курс, профиль, скачивание	полный доступ	доступ к любому курсу и студенту, скачивание любой попытки курса
Преподаватель своего курса → чтение	курс, группы, профиль, материалы	видит опубликованные и скрытые материалы, всех студентов активной группы курса, неопубликованные оценки и все попытки; GET /api/v1/courses/{id}/groups отдаёт привязанные группы с именами одним вызовом (без N+1)
Преподаватель своего курса → запись	лабы/уровни/варианты, ведомость, группы, материалы	оценки/комментарии, публикация, уровни/варианты и раздача, защиты (код/reset), привязка групп, авторство материалов; проверки в progress CourseScopeService и academic course/content authoring
Преподаватель чужого курса	403	403 на чтение и запись: материалы, курс по course_no, состав группы, профиль, лабы, оценки, группы
Аудит → админ	чтение журнала	GET /api/v1/audit?page=&limit=&action= и /admin/audit доступны только ADMIN; в UI — постраничный переход «Показать ещё»
Аудит → запись из сервисов	только по токену	POST /api/v1/internal/audit с X-Internal-Token; без/неверный токен — 403
Студент → свой профиль	только своё и опубликованное	скрытые оценки/комментарии отсутствуют; чужой 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/refresh/logout и публичного /api/v1/content/**
Gateway → заголовки личности	клиент не подменяет	X-Account-Id/Login/Role удаляются и проставляются только после проверки JWT

Остаточные ограничения перечислены в разделе 4: offset-пагинация аудита, N+1 в отдельных лабораторных списках и отсутствие абсолютного лимита web-сессии. Продуктовые риски legacy-активов, 30-дневного JWT и ведущих нулей номера группы закрыты или сняты как не относящиеся к требованиям.

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 нужной ветки/тега.
• CI зелёный. .gitlab-ci.yml на каждом push/MR выполняет test ktlintCheck detekt evidenceCheck и job smoke (scripts/ldd-smoke.sh: полный стек, health, вход админа, один курс). Полный release-evidence обязателен для тегов и запускается вручную для веток. check использует privileged-сервисы docker:dind для Testcontainers; smoke/release-evidence — shell-runner с Java 21, Docker Compose v2, Python 3, Node и Chromium Playwright.
• Заданы сроки сессии: LMS_ACCESS_TOKEN_TTL=15m, LMS_REFRESH_TOKEN_TTL=7d, LMS_SESSION_TIMEOUT=7d (значения по умолчанию подходят; менять только осознанно).

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

1. Flyway. ./deploy/deploy.sh up собирает образы и запускает postgres → identity → academic → progress → gateway → web. Миграции применяются автоматически при старте сервисов: identity V4–V11 (V10 — identity.audit_events, V11 — identity.refresh_tokens), 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 соответствует старым комментариям;
   • группы без полного разбора отсутствуют;
   • таблица identity.audit_events существует (V10);
   • таблица identity.refresh_tokens существует (V11).
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, карточка своего курса (имена групп, привязка/отвязка группы по available-groups), ведомость /admin/groups/{groupId}?courseId=... без админских контролов, оценка и публикация, уровень/вариант и раздача, защита (код/reset), профиль студента, скачивание попытки и ZIP группы, авторство материалов /teacher/courses/{id}/content.
• Студент: вход, дашборд, лабораторная, сдача/история, курсовые материалы; видны только опубликованные оценки и комментарии.
• Материалы курса: админ и преподаватель видят скрытые статьи, студент — только опубликованные; чужой курс даёт 403, аноним уходит на /login.
• Активы: картинки курсовой статьи открываются у студента своего курса и преподавателя; чужой курс — 403, скрытая картинка у студента — 404, публичная ALL — без входа; файл без привязки к статье — 404 для всех, кроме админа. Админ проверяет инвентаризацию через GET /api/v1/content/legacy-assets (или админский UI/curl) и при необходимости привязывает или удаляет файлы.
• Копирование лабораторной: админ копирует лабораторную в другой курс; создаётся черновик с уровнями и вариантами; оценки, сдачи, защиты и назначения не копируются; занятый номер даёт 409.
• Профиль: преподаватель своего курса видит сводку, комментарии, все попытки и скачивает ZIP; чужой студент/курс — 403.
• Повышение: /admin/promotion строит dry-run за год, данные не меняются; применение — только после проверки плана; откат доступен для завершённого запуска. На production не применять план «на всякий случай».
• Аудит: /admin/audit открывается у админа, показывает события (например, PROFILE_VIEW, SUBMISSION_DOWNLOAD, GRADE_SET, CONTENT_*, TEACHER_*) с фильтром по действию и временем МСК; «Показать ещё» переходит на следующую страницу (page/limit); преподаватель/студент получают 403.
• Сессия: после входа cookie LMS_SESSION живёт 7 дней; при работе дольше 15 минут страница продолжает работать без повторного входа (access обновляется автоматически). Выход и смена пароля требуют повторного входа; вход отчисленного/архивного студента и refresh закрытой группы отклоняются.
• Проверить логи web, gateway, identity, academic, progress на ERROR/WARN после smoke.

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

1. Старый формат импорта не поддерживается. Импорт принимает только шаблон v2 (поток/курс/номер/степень/год/ФИО/№/база). Ограничение зафиксировано в 11. Номер группы — числовой, поэтому отдельного требования к ведущим нулям нет.
2. Пагинация аудита — offset. GET /api/v1/audit поддерживает page и limit (максимум 500), UI — «Показать ещё». Для очень больших журналов keyset-пагинация была бы устойчивее к вставкам между страницами.
3. N+1 в отдельных списках. Имена групп курса отдаются одним вызовом (GET /api/v1/courses/{id}/groups), но часть лабораторных списков и ведомости на больших объёмах всё ещё собирается по частям. Полный нагрузочный профиль 100 групп / 1000 студентов проходит, однако пакетные выборки для оставшихся экранов — лабораторная деталь, а не блокер передачи.
4. Нет абсолютного лимита web-сессии. Сессия скользящая (7 дней) и отзывается при выходе, смене пароля, отчислении/архиве и закрытии группы, но при непрерывной активности может жить бессрочно. Если политика требует принудительного повторного входа раз в N дней, нужен абсолютный max-age поверх sliding-сессии.

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

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

1. Инвентаризация legacy-активов. Несвязанные файлы уже не публичны; админ получает их список через GET /api/v1/content/legacy-assets, после чего привязывает к статьям или удаляет. Это гигиена хранилища, а не открытый риск доступа.
2. Keyset-пагинация и оставшиеся N+1. Устойчивый курсор для аудита, пакетные выборки для лабораторных списков и ведомости на больших курсах.
3. Абсолютный лимит сессии. Опционально: принудительный повторный вход раз в N дней поверх 7-дневной sliding-сессии.
4. Внешняя интеграция «Контингент»/next.uniyar.ac.ru. Отдельный anti-corruption слой, идемпотентная синхронизация, журнал и отчёт дрифта; внешние идентификаторы добавляются миграцией.

6. Итог

Этап 6 закрыт: права преподавателя на запись, аудит, CI, security-матрица, upgrade-тест миграций, видимость активов и deploy-runbook проверены. Продуктовые риски закрыты: legacy-активы secure-by-default, access/refresh и web-сессия с отзывом, пагинация аудита и bulk-выдача групп. Оставшиеся ограничения (offset-пагинация, отдельные N+1, отсутствие абсолютного лимита сессии) задокументированы в разделе 4 и не блокируют передачу.

7. LDD baseline

После этапа 6 и закрытия рисков текущая функциональность проверена через LDD-контур: реестр docs/evidence/claims.json (46 claims, 25 P0 / 21 P1), gate ./gradlew evidenceCheck, upgrade-скрипт, runtime-smoke, smoke-job, mutation testing и браузерный Playwright E2E. Результат: 46/46 claims proven, P0 gaps = 0, 319 тестов, 0 failures; mutation strength CourseAccessService 75%, PromotionPlanner 69%; browser E2E 4/4; конкурентные apply/rollback и масштабный нагрузочный smoke (100 групп / 1000 студентов, 125 параллельных чтений, 0 ошибок, p95 < 1 с) зелёные. Smoke-job выполняется на каждом push/MR, полный release-evidence обязателен для тегов и доступен вручную для веток. E2E нашёл и закрыл реальный дефект Jackson 3/Kotlin defaults. Подробности и остаточные ограничения — docs/evidence/baseline-2026-10-27.md.