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/02-bootstrap-json-spec.md
+++ b/docs/platform/02-bootstrap-json-spec.md
@@ -0,0 +1,124 @@
+# 02. Спецификация bootstrap.json
+
+## Назначение
+Bootstrap JSON является главным конфигурационным документом витрины. Он определяет структуру страниц, секций, виджетов, тему и подключение источников данных.
+
+## Поведение системы
+- Frontend загружает bootstrap.json на старте runtime.
+- Конфигурация валидируется по обязательным полям.
+- После валидации строится UI без хардкода tenant-логики.
+
+## Обязательные свойства
+- schemaVersion: string
+- tenant: object
+- theme: object
+- layout: object
+- pages: array
+- apiEndpoints: object
+
+### Обязательные свойства tenant
+- id: string
+- slug: string
+- host: string
+- defaultLocale: string
+- supportedLocales: string[]
+
+### Обязательные свойства страницы
+- id: string
+- key: string
+- route.path: string
+- sections: array
+
+### Обязательные свойства секции
+- id: string
+- type: string
+- order: number
+- widgets: array
+
+### Обязательные свойства виджета
+- id: string
+- type: string
+- version: string
+
+### Поддерживаемые layout.type
+- default
+- sidebar-left
+- carousel-home
+- minimal
+
+## Опциональные свойства
+- featureFlags
+- localization
+- seo
+- permissions
+- branding
+- navigation
+- footer
+- staticPages
+- widgetRegistry
+- visibility
+- layout
+- dataSource
+
+## Строгие правила
+- Поля обязательной схемы не могут быть null.
+- route.path должен быть уникальным в рамках tenant.
+- id страниц, секций и виджетов должен быть уникальным в своей области.
+- В одной секции порядок order не может дублироваться.
+- Виджеты не содержат backend URL в props; URL управляются только apiEndpoints.
+- Для виджетов допустимы metadata поля: order, padding, visibility.desktop/tablet/mobile.
+- Для footer links/legal/payout icons источник истины — bootstrap JSON.
+- Для staticPages контент поддерживается в формате multilingual HTML и рендерится только через safe sanitizer.
+
+## Пример полного минимального bootstrap
+```json
+{
+  "schemaVersion": "1.0.0",
+  "tenant": {
+    "id": "tenant-default",
+    "slug": "default",
+    "host": "default.marketplace.com",
+    "defaultLocale": "ru",
+    "supportedLocales": ["ru", "en"]
+  },
+  "theme": {
+    "themeId": "default-light",
+    "palette": {
+      "primary": "#497671",
+      "textPrimary": "#1e3c38",
+      "backgroundPrimary": "#ffffff"
+    }
+  },
+  "apiEndpoints": {
+    "catalog": { "baseUrl": "https://api.marketplace.com" },
+    "bootstrap": { "path": "/bootstrap" }
+  },
+  "pages": [
+    {
+      "id": "page-home",
+      "key": "home",
+      "route": { "path": "/", "exact": true },
+      "sections": [
+        {
+          "id": "section-hero",
+          "type": "hero",
+          "order": 1,
+          "widgets": [
+            { "id": "widget-hero", "type": "hero", "version": "1.0.0" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Ответственность Frontend
+- Валидировать обязательные поля до рендера.
+- Применять значения опциональных полей только при наличии.
+- Прекращать инициализацию при критической невалидности схемы.
+
+## Ответственность Backend
+- Отдавать tenant-specific bootstrap.json.
+- Поддерживать schemaVersion и changelog контракта.
+- Не включать frontend-специфические runtime-хуки в JSON.