sparkantiplagiat-frontend/docs/INTEGRATION.md

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

Ответ:

{
  "user": {
    "id": 1,
    "name": "Admin",
    "email": "admin@example.com",
    "access_level": "Admin"
  },
  "token": "jwt"
}

Текущий пользователь

• GET /auth/me

Передавать:

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

Ответ:

{
  "message": "archive uploaded",
  "status": "Stored",
  "archive_object_key": "submissions/12/101.zip",
  "archive_checksum": "sha256...",
  "archive_size": 20480
}

3. Запустить проверку

• POST /works/:id/check

Ответ:

{
  "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.

Ошибки

Формат ошибок стабилен:

{
  "message": "Краткое описание",
  "error": "Технические детали"
}

Для UI обычно показывать:

• message пользователю;
• error — только в debug/admin mode.