docs

2026-07-05 04:23:47 +04:00
parent c901ec1e49
commit 10251f2fc6
24 changed files with 2424 additions and 0 deletions
--- a/docs/platform/13-backend-requirements.md
+++ b/docs/platform/13-backend-requirements.md
@@ -0,0 +1,61 @@
+# 13. Требования к backend
+
+## Назначение
+Документ фиксирует минимальный набор backend-возможностей для стабильной работы конфигурационно-управляемой multi-tenant платформы.
+
+## Функциональные требования
+- Tenant resolution по домену.
+- Выдача bootstrap.json для tenant.
+- API категорий, товаров, карточек, поисковых выборок.
+- Выдача навигации, статических страниц и feature flags.
+
+### Контракт статических страниц
+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.
+- Унифицированный формат ошибок API.
+
+## Опциональные 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 и контроль доступа.