# 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.