contracts

contracts — это общий слой договорённостей между сервисами. Он нужен, чтобы frontend, backend и pipeline не расходились по форме данных.

Что здесь хранится

Путь	Назначение
`graphql/schema.graphql`	GraphQL-контракт для backend и frontend
`events/source-raw.v1.json`	схема сырого события
`events/source-normalized.v1.json`	схема нормализованного события
`queue-messages/`	тестовые и примерные сообщения

Зачем это выделено в отдельный репозиторий

Потому что контракт нельзя надёжно держать “в голове” или только в одном сервисе.

Такой подход даёт:

единый source of truth;
более безопасные cross-repo изменения;
предсказуемый review изменений API и событий;
меньше скрытого дрейфа между frontend, backend и pipeline.

Кто использует `contracts`

npp-backend реализует GraphQL API;
npp-web ориентируется на GraphQL-схему;
scrape-helper валидирует raw-события;
processing-worker валидирует normalized-события.

Когда нужно менять этот репозиторий

появляется новое поле в GraphQL;
меняется shape raw-события;
меняется shape normalized-события;
нужно синхронно расширить несколько сервисов;
хочется зафиксировать формальный контракт до реализации.

Хороший порядок изменений

Если меняется GraphQL:

обновить contracts;
обновить backend;
обновить frontend.

Если меняется normalized payload:

обновить contracts;
обновить processing-worker;
обновить ingest в backend;
при необходимости обновить аналитические или UI-срезы.

Проверка

bash

npm install
npm run validate

Типичная ошибка

Самая частая проблема — поменять контракт только в одном месте:

только в backend;
только во frontend;
только в worker.

Именно для этого contracts и вынесен отдельно.