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/INTEGRATION.md
+++ b/docs/INTEGRATION.md
@@ -0,0 +1,253 @@
+# Frontend Integration Guide
+
+Этот документ нужен фронтенду как краткая рабочая инструкция по интеграции с `SparkGuardBackend`.
+
+## Что использовать как основной контракт
+
+Frontend-команде нужно отдать три файла:
+
+1. `cmd/rest/controllers/docs/swagger.json` — машинно-читаемый OpenAPI/Swagger контракт.
+2. `docs/api/README.md` — краткий REST-обзор по сценариям и смыслу ручек.
+3. `docs/frontend/README.md` — этот документ с прикладными рекомендациями для экранов и polling flow.
+
+## Базовые принципы
+
+- frontend общается только с backend;
+- frontend не ходит в `SparkGuardAntiplagiarism`, Kafka или MinIO;
+- upload и check — это два разных шага;
+- dashboards должны использовать `summary/stats` endpoints, а не `chunks`;
+- `chunks` и `report.raw.json` — только debug/admin слой.
+
+## Авторизация
+
+### Вход
+
+- `POST /auth/login`
+
+Ответ:
+
+```json
+{
+  "user": {
+    "id": 1,
+    "name": "Admin",
+    "email": "admin@example.com",
+    "access_level": "Admin"
+  },
+  "token": "jwt"
+}
+```
+
+### Текущий пользователь
+
+- `GET /auth/me`
+
+Передавать:
+
+```http
+Authorization: Bearer <jwt>
+```
+
+## Справочники и CRUD
+
+Основные сущности:
+
+- `users`
+- `students`
+- `groups`
+- `events`
+- `works`
+- `reference-sets`
+
+Для большинства таблиц frontend может опираться на стандартный CRUD:
+
+- list: `GET`
+- create: `POST`
+- get one: `GET /:id`
+- update: `PATCH` или `PUT`
+- delete: `DELETE`
+
+## Основной flow проверки работы
+
+### 1. Создать work
+
+- `POST /works`
+
+### 2. Загрузить архив
+
+- `PUT /works/:id/archive`
+
+Поддерживаются:
+
+- 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
+}
+```
+
+### 3. Запустить проверку
+
+- `POST /works/:id/check`
+
+Ответ:
+
+```json
+{
+  "message": "analysis queued for current archive",
+  "analysis_run_id": "uuid",
+  "status": "Queued"
+}
+```
+
+### 4. Poll статуса
+
+- `GET /analysis-runs/:id`
+
+Frontend должен ждать состояния:
+
+- `Queued`
+- `Processing`
+- `Completed`
+- `Failed`
+
+Рекомендуемый polling:
+
+- каждые `2-3` секунды первые `30` секунд;
+- затем каждые `5` секунд;
+- останавливать polling на `Completed` или `Failed`.
+
+### 5. После завершения читать результат
+
+- `GET /analysis-runs/:id/adoptions`
+- `GET /analysis-runs/:id/report.json`
+- `GET /analysis-runs/:id/report.html`
+- `GET /analysis-runs/:id/report.pdf`
+- `GET /works/:id/summary`
+
+## Какие endpoints использовать для экранов
+
+### Экран списка/карточки работы
+
+- `GET /works`
+- `GET /works/:id`
+- `GET /works/:id/analysis-runs`
+- `GET /works/:id/summary`
+
+`GET /works/:id/summary` — основной endpoint для детального экрана работы.
+
+Он уже отдаёт:
+
+- `presentation_summary`
+- `trust_score`
+- `plagiarism_rate`
+- strongest counterpart
+- `counterparts`
+- `graph`
+- latest run metadata
+
+### Экран события
+
+- `GET /events`
+- `GET /events/:id`
+- `GET /events/:id/works`
+- `GET /events/:id/summary`
+
+### Экран группы
+
+- `GET /groups`
+- `GET /groups/:id`
+- `GET /groups/:id/stats`
+
+### Экран студента
+
+- `GET /students`
+- `GET /students/:id`
+- `GET /students/:id/stats`
+
+### Экран отчёта преподавателя
+
+- основа: `GET /analysis-runs/:id/report.json`
+- экспорт:
+  - `GET /analysis-runs/:id/report.html`
+  - `GET /analysis-runs/:id/report.pdf`
+
+### Экран аудита
+
+- `GET /audit-logs`
+
+Фильтры:
+
+- `actor_user_id`
+- `action`
+- `resource_type`
+- `resource_id`
+- `source`
+- `limit`
+
+Этот endpoint нужен только для admin UI.
+
+## Что означает summary/statistics payload
+
+Во всех `summary/stats` ручках frontend получает одинаковые строительные блоки:
+
+- `presentation_summary`
+- `works`
+- `graph`
+
+### `presentation_summary`
+
+Основные поля:
+
+- `works_total`
+- `works_checked`
+- `works_completed`
+- `works_failed`
+- `works_flagged`
+- `counterparts_count`
+- `connections_count`
+- `plagiarism_rate`
+- `trust_score`
+- `risk_level`
+- `headline`
+
+### `graph`
+
+- `nodes` — вершины графа работ;
+- `edges` — связи между работами;
+- использовать для экрана "`кто с кем совпадает`".
+
+## Что не нужно использовать для продуктового UI
+
+- `GET /analysis-runs/:id/chunks`
+- `GET /analysis-runs/:id/report.raw.json`
+
+Они нужны для:
+
+- отладки пайплайна;
+- технической диагностики;
+- проверки Kafka/analyzer boundary.
+
+## Ошибки
+
+Формат ошибок стабилен:
+
+```json
+{
+  "message": "Краткое описание",
+  "error": "Технические детали"
+}
+```
+
+Для UI обычно показывать:
+
+- `message` пользователю;
+- `error` — только в debug/admin mode.