sparkantiplagiat-frontend/docs/REST-API.md

REST API

Этот документ описывает внешний REST-контракт SparkGuardBackend.

Общие правила

• авторизация: Authorization: Bearer <jwt>;
• frontend работает только с backend, не с analyzer и не с MinIO;
• upload и check — разные действия;
• full report скачивается только через backend.

Формат ошибки:

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

Пример ответа:

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

Пример ответа:

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

Пример создания:

{
  "name": "course-template",
  "description": "Шаблон лабораторной работы",
  "kind": "template"
}

Пример ingestion ответа:

{
  "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 — новые двусторонние связи по уже проверенным работам.