docs

docs/platform/05-widget-system.md

@@ -0,0 +1,57 @@
+# 05. Widget System
+
+## Назначение
+Widget System предоставляет переиспользуемые UI-блоки для сборки страниц из конфигурации без дублирования логики и без tenant-specific кода.
+
+## Поведение системы
+- Widget Engine выбирает компонент по widget.type и version.
+- Виджет получает входные props и resolved data.
+- В случае отсутствия регистрации используется fallback unknown-widget.
+
+## Обязательные свойства JSON
+- widget.id
+- widget.type
+- widget.version
+
+## Опциональные свойства JSON
+- widget.props
+- widget.dataSource
+- widget.featureFlag
+- widget.visible
+- widget.events
+
+## Строгие правила
+- Виджеты не вызывают API напрямую.
+- Виджеты не управляют page-level margin/padding/layout.
+- Виджет может управлять только внутренней разметкой и презентацией.
+- Любой новый widget.type должен быть зарегистрирован в реестре.
+
+## Пример JSON виджета
+```json
+{
+  "id": "widget-categories-main",
+  "type": "categories",
+  "version": "1.0.0",
+  "props": {
+    "title": "Категории",
+    "emptyMessage": "Категории скоро появятся"
+  },
+  "dataSource": {
+    "name": "categories",
+    "params": {
+      "rootOnly": true,
+      "limit": 12
+    }
+  }
+}
+```
+
+## Ответственность Frontend
+- Разрешать тип виджета через registry/manifest.
+- Передавать только подготовленные данные в компонент виджета.
+- Блокировать прямые API-вызовы из слоя UI-виджета.
+
+## Ответственность Backend
+- Поставлять данные в форматах, ожидаемых data resolvers.
+- Обеспечивать консистентность ID и ссылок между сущностями.
+- Не внедрять frontend-специфичные инструкции в props виджетов.