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 c379be7fba
commit 6ffc6304e3
7 changed files with 1398 additions and 0 deletions
--- a/docs/02-deployment.md
+++ b/docs/02-deployment.md
@@ -0,0 +1,108 @@
+# Развёртывание
+
+## 1. Диаграмма развёртывания
+
+```mermaid
+flowchart TB
+    internet["Интернет"]
+    subgraph host["Сервер lms.our-place.ru (Ubuntu, Docker)"]
+        nginx["nginx (host)<br/>80/443, TLS (certbot)<br/>proxy → 127.0.0.1:8090"]
+        subgraph net["docker network: lms"]
+            web["container: web<br/>lms-web:latest<br/>:8090"]
+            gw["container: gateway<br/>lms-gateway:latest<br/>:8080"]
+            id["container: identity<br/>lms-identity:latest<br/>:8081"]
+            ac["container: academic<br/>lms-academic:latest<br/>:8082"]
+            pr["container: progress<br/>lms-progress:latest<br/>:8083"]
+            pg["container: postgres<br/>postgres:18<br/>:5432"]
+            vol1[("volume lms_pgdata")]
+            vol2[("volume lms_assets<br/>/data/content-assets")]
+            vol3[("volume lms_submissions<br/>/data/submissions")]
+        end
+    end
+
+    internet -->|HTTPS| nginx
+    nginx -->|HTTP| web
+    web --> gw
+    gw --> id
+    gw --> ac
+    gw --> pr
+    id --> pg
+    ac --> pg
+    pr --> pg
+    ac --> vol2
+    pr --> vol3
+    pg --> vol1
+```
+
+Наружу публикуется только web на `127.0.0.1:8090`; доступ снаружи — через nginx и TLS.
+
+## 2. Контейнеры и переменные окружения
+
+| Сервис | Образ / стадия Dockerfile | Порт | Ключевые переменные | Тома |
+|---|---|---|---|---|
+| postgres | `postgres:18` | 5432 (внутр.) | `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` | `lms_pgdata` |
+| identity | `target: identity` | 8081 | `LMS_DB_URL` (схема `identity`), `LMS_DB_USER`, `LMS_DB_PASSWORD` | — |
+| academic | `target: academic` | 8082 | `LMS_DB_URL` (`academic`), `LMS_CONTENT_ASSETS_DIR`, `LMS_JWT_JWK_SET_URI` | `lms_assets` |
+| progress | `target: progress` | 8083 | `LMS_DB_URL` (`progress`), `LMS_SUBMISSIONS_DIR`, `LMS_IDENTITY_URI`, `LMS_ACADEMIC_URI`, `LMS_JWT_JWK_SET_URI` | `lms_submissions` |
+| gateway | `target: gateway` | 8080 | `LMS_IDENTITY_URI`, `LMS_ACADEMIC_URI`, `LMS_PROGRESS_URI`, `LMS_JWT_JWK_SET_URI` | — |
+| web | `target: web` | 8090 | `LMS_GATEWAY_URL`, `SERVER_PORT` | — |
+
+`LMS_JWT_JWK_SET_URI` обязателен для gateway, academic и progress —
+в контейнерах это `http://identity:8081/api/v1/auth/jwks.json` (иначе 401).
+
+## 3. Сборка
+
+```mermaid
+flowchart LR
+    src["Исходники<br/>services/, libs/, web/, buildSrc/"]
+    subgraph build["Dockerfile, стадия build (eclipse-temurin:21-jdk)"]
+        g["./gradlew bootJar -x test<br/>(Gradle-кэш в cache-mount)"]
+    end
+    jar["bootJar-артефакты"]
+    subgraph run["Runtime-стадии (eclipse-temurin:21-jre)"]
+        r["java -jar app.jar<br/>TZ=Europe/Moscow"]
+    end
+    src --> g --> jar --> r
+```
+
+Java на сервере не нужна: сборка и запуск — внутри контейнеров.
+`deploy/deploy.sh up` собирает образы и запускает стек из `docker-compose.prod.yml`.
+
+## 4. Nginx
+
+`deploy/nginx/lms.our-place.ru.conf`:
+
+- `listen 80` (TLS добавляет `certbot --nginx`), `server_name lms.our-place.ru`;
+- ACME-челлендж через `/.well-known/acme-challenge/`;
+- `client_max_body_size 120m` — загрузка ZIP-архивов лабораторных и решений;
+- `proxy_pass http://127.0.0.1:8090` c заголовками
+  `Host`, `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`;
+- таймауты 300 с на чтение/отправку.
+
+Web-сервис запускается с `server.forward-headers-strategy: framework`,
+поэтому корректно формирует https-редиректы за прокси.
+
+## 5. Обновление и данные
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Dev as Разработчик
+    participant Git as Gitea
+    participant Srv as Сервер /opt/LMS
+    participant DC as docker compose
+    participant PG as postgres
+
+    Dev->>Git: git push origin master
+    Srv->>Git: git pull
+    Srv->>DC: ./deploy/deploy.sh up
+    DC->>DC: docker build (5 стадий)
+    DC->>PG: старт postgres (volume lms_pgdata)
+    DC->>DC: старт identity → academic → progress → gateway → web
+    Note over DC: Flyway применяет миграции<br/>V1..V5 автоматически при старте сервисов
+```
+
+- Резервные копии: `pg_dump` (том `lms_pgdata`) и `tar` томов `lms_assets`,
+  `lms_submissions` — команды в [deploy/DEPLOY.md](../deploy/DEPLOY.md).
+- Порядок наполнения данными (админ → группы → лабораторная → варианты →
+  оценки/защита → материалы) описан в [deploy/IMPORT.md](../deploy/IMPORT.md).