docs

docs/platform/06-api-contracts.md

@@ -0,0 +1,74 @@
+# 06. API-контракты
+
+## Назначение
+Документ определяет стабильные контракты API для данных маркетплейса. Backend предоставляет только данные, frontend отвечает за представление.
+
+## Поведение системы
+- API base URL определяется tenant-конфигурацией.
+- Frontend отправляет запросы через единый API слой и интерсепторы.
+- Ответы маппятся в доменные модели frontend.
+
+## Обязательные свойства JSON (ответы API)
+- status или корректный HTTP status code
+- data (основная полезная нагрузка)
+- id для доменных сущностей
+
+## Опциональные свойства JSON
+- meta (pagination, total, filters)
+- errors (детализация ошибок)
+- warnings
+
+## Строгие правила
+- Backend не должен отдавать HTML для витрины.
+- Контракты должны быть обратно совместимы в пределах одной major-версии.
+- В ответах на списки должна поддерживаться пагинация.
+- Ошибки API должны быть машиночитаемыми и локализуемыми на frontend.
+
+## Пример API ответа: категории
+```json
+{
+  "data": [
+    {
+      "id": 101,
+      "title": "Смартфоны",
+      "parentId": null,
+      "priority": 1,
+      "visible": true
+    }
+  ],
+  "meta": {
+    "total": 1
+  }
+}
+```
+
+## Пример API ответа: товары
+```json
+{
+  "data": {
+    "items": [
+      {
+        "itemID": 5001,
+        "name": "Phone X",
+        "price": 49990,
+        "currency": "RUB",
+        "categoryID": 101,
+        "visible": true
+      }
+    ],
+    "total": 1,
+    "skip": 0,
+    "count": 20
+  }
+}
+```
+
+## Ответственность Frontend
+- Маппинг API DTO в доменные модели.
+- Центральная обработка ошибок и retry-стратегий.
+- Кеширование и переиспользование данных без нарушения актуальности.
+
+## Ответственность Backend
+- Гарантировать SLA и стабильность контрактов.
+- Возвращать tenant-correct данные.
+- Поддерживать фильтрацию, пагинацию и сортировку для каталога.