feat: align UI with T-Bank design system, redesign landing page with bento layout, migrate shared utilities from SparkGuardian, standardize status chips and date formatters, remove explicit date inputs, and add project README

2026-04-16 03:31:48 +03:00
parent c99df2d86e
commit 44b80cd4b5
87 changed files with 14046 additions and 455 deletions
--- a/docs/REST-API.md
+++ b/docs/REST-API.md
@@ -0,0 +1,236 @@
+# REST API
+
+Этот документ описывает внешний REST-контракт `SparkGuardBackend`.
+
+## Общие правила
+
+- авторизация: `Authorization: Bearer <jwt>`;
+- frontend работает только с backend, не с analyzer и не с MinIO;
+- `upload` и `check` — разные действия;
+- full report скачивается только через backend.
+
+Формат ошибки:
+
+```json
+{
+  "message": "Краткое описание",
+  "error": "Технические детали"
+}
+```
+
+## Основной сценарий
+
+1. `POST /auth/login`
+2. `GET /auth/me`
+3. `GET /readyz`
+4. `POST /students`
+5. `POST /groups`
+6. `POST /groups/:id/students/:student_id`
+7. `POST /events`
+8. `POST /works`
+9. `PUT /works/:id/archive`
+10. `POST /works/:id/check`
+11. `GET /analysis-runs/:id`
+12. дождаться `Queued -> Completed` или `Failed`
+13. `GET /works/:id/summary`
+14. `GET /events/:id/summary`
+15. `GET /analysis-runs/:id/report.json`
+16. `GET /analysis-runs/:id/report.html`
+17. `GET /analysis-runs/:id/report.pdf`
+18. `GET /audit-logs` — только для admin UI
+
+## Works
+
+- `GET /works`
+- `POST /works`
+- `GET /works/:id`
+- `PUT /works/:id`
+- `DELETE /works/:id`
+- `PUT /works/:id/archive`
+- `POST /works/:id/check`
+- `GET /works/:id/archive`
+- `GET /works/:id/analysis-runs`
+- `GET /works/:id/summary`
+- `GET /works/:id/adoptions`
+- `GET /works/:id/adoptions/related`
+- `GET /works/:id/adoptions/archive`
+
+### `PUT /works/:id/archive`
+
+Смысл:
+
+- repack архива;
+- сохранение текущего архива в MinIO;
+- обновление archive metadata у `work`;
+- без создания `analysis_run`.
+- принимает и raw `application/octet-stream`, и `multipart/form-data`.
+
+Пример ответа:
+
+```json
+{
+  "message": "archive uploaded",
+  "status": "Stored",
+  "archive_object_key": "submissions/12/101.zip",
+  "archive_checksum": "sha256...",
+  "archive_size": 20480
+}
+```
+
+### `POST /works/:id/check`
+
+Смысл:
+
+- создать новый `analysis_run` по текущему архиву;
+- записать outbox message;
+- отправить задачу в Kafka.
+
+Пример ответа:
+
+```json
+{
+  "message": "analysis queued for current archive",
+  "analysis_run_id": "uuid",
+  "status": "Queued"
+}
+```
+
+## Analysis runs
+
+- `GET /analysis-runs/:id`
+- `GET /analysis-runs/:id/chunks`
+- `GET /analysis-runs/:id/adoptions`
+- `GET /analysis-runs/:id/report.raw.json`
+- `GET /analysis-runs/:id/report.json`
+- `GET /analysis-runs/:id/report.html`
+- `GET /analysis-runs/:id/report.pdf`
+- `POST /analysis-runs/:id/retry`
+
+### Что важно понимать
+
+- `POST /works/:id/check` — единственная обычная команда запуска новой проверки;
+- `GET /works/:id/analysis-runs` — история попыток по работе;
+- `GET /analysis-runs/:id` — статус конкретной попытки;
+- `GET /analysis-runs/:id/adoptions` — материализованные suspicious findings конкретного run;
+- `GET /analysis-runs/:id/report.json/html/pdf` — teacher-facing отчёт для UI;
+- `GET /analysis-runs/:id/chunks` и `GET /analysis-runs/:id/report.raw.json` — debug/admin endpoints, не обязательны frontend dashboards;
+- `POST /analysis-runs/:id/retry` — человекочитаемая обычная ручка retry;
+
+### Dashboard summaries
+
+- `GET /works/:id/summary`
+- `GET /events/:id/summary`
+- `GET /students/:id/stats`
+- `GET /groups/:id/stats`
+
+Они отдают:
+
+- `presentation_summary` — агрегаты для frontend dashboards;
+- `trust_score` и `plagiarism_rate`;
+- список работ/контрагентов с highest risk;
+- `graph.nodes`/`graph.edges` для сценария "кто с кем совпадает".
+
+## System
+
+- `GET /healthz`
+- `GET /readyz`
+
+`healthz` — дешёвая liveness probe.
+
+`readyz` — readiness check backend API, который проверяет доступность базы данных.
+
+## Audit
+
+- `GET /audit-logs`
+
+Доступно только `Admin`.
+
+Фильтры:
+
+- `actor_user_id`
+- `action`
+- `resource_type`
+- `resource_id`
+- `source`
+- `limit`
+
+Аудит покрывает:
+
+- административные CRUD-операции;
+- group memberships;
+- upload/check/retry по работам;
+- reference set changes;
+- reference ingestion scheduling;
+- system completion events для reference ingestion.
+
+### Teacher report
+
+Teacher report содержит:
+
+- `context`:
+  - работа;
+  - студент;
+  - группа;
+  - событие;
+  - archive metadata;
+- `summary`:
+  - plagiarism probability;
+  - risk level;
+  - strongest counterpart;
+  - strongest match;
+- `counterparts`;
+- `evidence`;
+- `technical`.
+
+### Retry
+
+`POST /analysis-runs/:id/retry`:
+
+- не требует повторного upload;
+- использует snapshot archive metadata исходного run;
+- создаёт новый `analysis_run`.
+
+## Adoptions
+
+- `GET /adoptions/:id/segment`
+
+Этот endpoint сначала читает snapshot excerpt из БД. Если excerpt ещё не materialized, только тогда он обращается к архиву.
+
+## Reference sets
+
+- `GET /reference-sets`
+- `POST /reference-sets`
+- `GET /reference-sets/:id`
+- `PATCH /reference-sets/:id`
+- `DELETE /reference-sets/:id`
+- `GET /reference-sets/:id/ingestions`
+- `POST /reference-sets/:id/ingestions`
+
+Пример создания:
+
+```json
+{
+  "name": "course-template",
+  "description": "Шаблон лабораторной работы",
+  "kind": "template"
+}
+```
+
+Пример ingestion ответа:
+
+```json
+{
+  "message": "accepted",
+  "ingestion_id": "uuid",
+  "status": "Queued",
+  "object_key": "reference-sets/7/uuid-template.zip"
+}
+```
+
+## Что смотреть при отладке
+
+- `GET /analysis-runs/:id` — статусы и error message;
+- `GET /analysis-runs/:id/chunks` — Kafka compatibility flow;
+- `GET /analysis-runs/:id/report.raw.json` — исходный analyzer output;
+- `GET /works/:id/summary` — агрегированный work-level view поверх bilateral adoptions;
+- `GET /works/:id/adoptions/related` — новые двусторонние связи по уже проверенным работам.