docs: add UML and architecture documentation (Mermaid)

- docs/README.md — index and short system overview - 01-architecture.md — context, per-service components, Gradle modules, authentication/authorization, web interceptors (flowcharts) - 02-deployment.md — deployment diagram, containers/env/volumes, build stages, nginx, update sequence - 03-domain-model.md — class diagrams for identity/academic/progress and web, ER model of all schemas (cross-schema references noted) - 04-sequences.md — 10 sequence diagrams (login, JWT check, forced password change, lab import, distribution, submission, defense, grades+publication, content publishing, group page aggregation) - 05-states.md — state diagrams for defense session, grade publication, lab status, content visibility, submission lifecycle, variant assignment, password MS git log --oneline -3
2026-09-16 18:44:14 +03:00
parent 30b8064718
commit 025c937f21
7 changed files with 1398 additions and 0 deletions
--- a/docs/05-states.md
+++ b/docs/05-states.md
@@ -0,0 +1,127 @@
+# Диаграммы состояний
+
+## 1. Сессия защиты (`defense_sessions.status`)
+
+```mermaid
+stateDiagram-v2
+    [*] --> waiting : преподаватель назначил задание
+    waiting --> waiting : выдан/обновлён код
+    waiting --> started : студент ввёл верный код
+    started --> ready : студент завершил работу
+    started --> ready : истекло время (syncTimeouts, readyReason=timeout)
+    ready --> waiting : «доп. задание: начать заново» (reset)
+    ready --> [*] : задание принято
+    note right of waiting
+        code = NULL — ждёт кода
+        code != NULL — код выдан
+    end note
+```
+
+## 2. Публикация оценок (пара «группа + лабораторная»)
+
+```mermaid
+stateDiagram-v2
+    [*] --> hidden : оценка выставлена (lab_grades)
+    hidden --> published : «опубликовать оценки» (grade_publications)
+    published --> hidden : «скрыть оценки»
+    note right of hidden
+        студент не видит ни балл,
+        ни комментарии
+    end note
+    note right of published
+        студенты группы видят балл и
+        комментарии, сгруппированные по тону
+    end note
+```
+
+## 3. Статус лабораторной (`labs.status`)
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft : импорт/создание
+    draft --> published : публикация
+    published --> draft : снятие с публикации
+    note right of draft
+        студентам не видна;
+        доступна для настройки
+    end note
+    note right of published
+        видна студентам: условие, вариант,
+        сдача; оценки — только после публикации
+    end note
+```
+
+## 4. Публикация материалов (главы, разделы, статьи)
+
+```mermaid
+stateDiagram-v2
+    state "опубликовано" as pub
+    state "скрыто" as hid
+    [*] --> pub : импорт/создание (published=true)
+    pub --> hid : «Скрыть» (published=false)
+    hid --> pub : «Опубликовать»
+    note right of hid
+        Не видно гостям и студентам:
+        глава целиком скрывает разделы и статьи,
+        раздел — свои статьи.
+        Администратор видит их с бейджем «скрыто»
+        и может открыть для предпросмотра.
+    end note
+```
+
+## 5. Жизненный цикл сдачи решения
+
+```mermaid
+stateDiagram-v2
+    [*] --> notSubmitted : лабораторная выдана
+    notSubmitted --> submitted : сдача (seq = 1, файлы на диске)
+    submitted --> submitted : переотправка (seq + 1, хранится вся история)
+    submitted --> closed : наступил дедлайн (deadlineAt)
+    submitted --> closed : выдано индивидуальное задание на защиту
+    closed --> [*]
+    note right of closed
+        Форма отправки скрыта,
+        доступно только скачивание
+        ранее отправленных решений
+    end note
+    note right of submitted
+        Скачать можно любую попытку;
+        преподаватель видит последнюю
+    end note
+```
+
+## 6. Вариант студента
+
+```mermaid
+stateDiagram-v2
+    [*] --> none : студент в группе, ЛР опубликована
+    none --> auto : распределение («Раздать»)
+    auto --> manual : «Закрепить» конкретный вариант
+    auto --> auto : повторное распределение без force (не трогает занятые)
+    manual --> manual : force не перезаписывает ручные закрепления
+    auto --> none : force (сброс авто-назначений)
+    note right of auto
+        подбирается наименее занятый вариант
+        своего уровня; пока есть невыданные —
+        повторов нет
+    end note
+```
+
+## 7. Пароль студента
+
+```mermaid
+stateDiagram-v2
+    [*] --> temporary : аккаунт создан / «Сбросить пароль»
+    temporary --> own : смена на /change-password
+    own --> temporary : «Сбросить пароль» преподавателем
+    note right of temporary
+        must_change_password = true,
+        temp_password хранится;
+        пока пароль не сменён, доступны только
+        /change-password, /logout и статика
+    end note
+    note right of own
+        must_change_password = false,
+        temp_password = NULL
+    end note
+```