# 13. Требования к backend

## Назначение
Документ фиксирует минимальный набор backend-возможностей для стабильной работы конфигурационно-управляемой multi-tenant платформы.

## Функциональные требования
- Tenant resolution по домену.
- Выдача bootstrap.json для tenant.
- API категорий, товаров, карточек, поисковых выборок.
- Выдача навигации, статических страниц и feature flags.
- Product Engagement API для рейтинга, отзывов и вопросов.
- Advanced Search API для keyword/suggestions/filter metadata/sorting.
- User Experience API (future-ready): wishlist/compare/saved-searches/recently-viewed sync for authenticated users.

### Контракт статических страниц
Backend должен поддерживать формат:
```json
{
  "slug": "about-us",
  "content": {
    "en": "<html>",
    "ru": "<html>",
    "hy": "<html>"
  }
}
```

## Обязательные JSON-контракты
- Bootstrap контракт со schemaVersion.
- Категории: id/title/parentId/visible/priority.
- Товары: itemID/name/price/currency/categoryID/visible.
- Product Engagement:
  - RatingSummary (average, totalReviews, distribution)
  - Review (id, rating, text, createdAt, author)
  - Question (id, text, createdAt, answers)
- Унифицированный формат ошибок API.

## Обязательные Product Engagement endpoints
- GET /products/{id}/rating
- GET /products/{id}/reviews?page={n}&pageSize={n}
- GET /products/{id}/questions?page={n}&pageSize={n}
- POST /products/{id}/reviews
- POST /products/{id}/questions

## Обязательные Catalog/Search endpoints (current + future-ready)
- GET /searchitems
- GET /category/{id}
- GET /items/randomitems
- GET /search/suggestions?q={term} (future-ready)
- GET /catalog/filters?category={id}&q={term} (future-ready)

## User Experience endpoints (future-ready)
- GET /me/wishlist
- POST /me/wishlist
- DELETE /me/wishlist/{itemId}
- GET /me/compare
- POST /me/compare
- DELETE /me/compare/{itemId}
- GET /me/saved-searches
- POST /me/saved-searches
- DELETE /me/saved-searches/{id}
- GET /me/recently-viewed
- POST /me/recently-viewed

## Catalog bootstrap contract expectations
- Backend should populate `catalog.availableSorts` and `catalog.enabledFilters`.
- Backend should not include product list or filter results inside bootstrap.
- Bootstrap remains feature-configuration only.

## Опциональные JSON-контракты
- Персонализированные рекомендации.
- Расширенные facets/filters.
- SEO-объекты и контентные блоки.

## Строгие правила
- Backend не должен возвращать frontend-specific разметку приложения (кроме контента статических страниц по согласованному контракту).
- Любое breaking change требует новой версии контракта.
- Данные tenants должны быть полностью изолированы.
- SLA bootstrap и catalog API должны обеспечивать запуск витрины без деградации UX.
- Bootstrap не должен содержать секреты: private keys, admin credentials, signing tokens.

## Пример JSON ошибки API
```json
{
  "error": {
    "code": "CATEGORY_NOT_FOUND",
    "message": "Category does not exist",
    "details": { "categoryId": 999 }
  }
}
```

## Ответственность Frontend
- Корректно интерпретировать ошибки и показывать пользовательские сценарии восстановления.
- Не обходить публичные backend-контракты прямыми вызовами внутренних сервисов.

## Ответственность Backend
- Обеспечить мониторинг, логирование и трассировку критических endpoint.
- Поддерживать тестируемые и документированные контракты.
- Обеспечить безопасность, rate limiting и контроль доступа.
