HUB Blocks Settings Architecture

Каноничный документ по архитектуре блоков HUB: где хранятся настройки блока, как они читаются/перезаписываются и как блок добавляется в шаблоны без смешивания контуров.

Цель

1. Зафиксировать один источник правил для blocks library и template-level settings.
2. Исключить путаницу между глобальными значениями блока и значениями блока внутри шаблона.
3. Дать инженерно-полный workflow для добавления новых блоков.

Термины

• Секция: крупная секция страницы (value, program, faq и т.д.).
• Блок: переиспользуемый компонент библиотеки блоков (feature-enrollment-system-v1).
• Карточка: внутренний элемент блока (01, 02, 03, 04).
• Глобальные настройки блока: значения блока в библиотеке блоков.
• Шаблонные настройки блока: значения того же блока, но в конкретном шаблоне.

Где это в интерфейсе

• Библиотека блоков: /{locale}/offers/templates/blocks
• Админ шаблонов: /{locale}/admin/templates
  • для value настройки блока редактируются прямо внутри карточки секции value.

Модель данных Enrollment System

Источник схемы: src/lib/offers/enrollment-block-schema.ts.

Поля блока:

1. sectionBg
2. cardBg
3. titleColor
4. textColor
5. indexColor
6. heroTextColor
7. heroIndexColor
8. heroOverlayColor
9. heroOverlayTopOpacity (0..100)
10. heroOverlayBottomOpacity (0..100)
11. heroImageSrc (public path /images/...)
12. card03Bg
13. card03BgOpacity (0..100)
14. card03TextColor

Upload-поле: enrollHeroImageFile (транспортное поле формы; сохраняется как heroImageSrc после загрузки файла).

Хранилища значений

Глобальный storage блока (библиотека)

• Основной ключ:
  • hub.blocks.feature-enrollment-system-v1.defaults
• Legacy-ключи (обратная совместимость):
  • hub.blocks.enrollment_system.section_bg
  • hub.blocks.enrollment_system.card_bg
  • hub.blocks.enrollment_system.title_color
  • hub.blocks.enrollment_system.text_color
  • hub.blocks.enrollment_system.index_color

Template storage блока (внутри шаблона)

• Ключ:
  • hub.templates.<templateKey>.blocks.feature-enrollment-system-v1
• Пример:
  • hub.templates.beauty-courses.blocks.feature-enrollment-system-v1

Storage секций шаблона (отдельно от блока)

• Ключ:
  • hub.templates.<templateKey>.sections
• Используется для enabled/order и style-полей секций.
• Для секции value style-поля в админке отключены, чтобы не дублировать источник настроек блока.

Приоритет чтения значений (resolve chain)

Для библиотеки блоков

1. Читать hub.blocks.feature-enrollment-system-v1.defaults.
2. Если нет/битый JSON: читать legacy-ключи.
3. Если и там нет валидных значений: DEFAULT_ENROLLMENT_BLOCK_SETTINGS.

Для шаблона

1. Читать hub.templates.<templateKey>.blocks.feature-enrollment-system-v1.
2. Если нет: fallback к текущим глобальным настройкам блока.
3. Если глобальные недоступны: DEFAULT_ENROLLMENT_BLOCK_SETTINGS.

Контуры записи (кто куда пишет)

Глобальные настройки блока

• Action: saveEnrollmentBlockSettingsAction
• Пишет:
  • hub.blocks.feature-enrollment-system-v1.defaults
  • legacy-ключи (для совместимости)

Шаблонные настройки блока

• Action: saveTemplateEnrollmentBlockSettingsAction
• Пишет:
  • hub.templates.<templateKey>.blocks.feature-enrollment-system-v1

Каноничное правило разделения

1. Значения в библиотеке блока живут в глобальном storage блока.
2. Значения блока внутри шаблона живут в template storage.
3. Контуры независимы: запись в одном контуре не должна перезаписывать другой.
4. Набор полей один и тот же (схема блока одна), storage-ключи разные.

Таблица: поля -> форма -> storage

Поле	Input name	Тип	Global key	Template key
sectionBg	enrollSectionBg	color	hub.blocks.feature-enrollment-system-v1.defaults	hub.templates.<templateKey>.blocks.feature-enrollment-system-v1
cardBg	enrollCardBg	color	same JSON key	same JSON key
titleColor	enrollTitleColor	color	same JSON key	same JSON key
textColor	enrollTextColor	color	same JSON key	same JSON key
indexColor	enrollIndexColor	color	same JSON key	same JSON key
heroTextColor	enrollHeroTextColor	color	same JSON key	same JSON key
heroIndexColor	enrollHeroIndexColor	color	same JSON key	same JSON key
heroOverlayColor	enrollHeroOverlayColor	color	same JSON key	same JSON key
heroOverlayTopOpacity	enrollHeroOverlayTopOpacity	number	same JSON key	same JSON key
heroOverlayBottomOpacity	enrollHeroOverlayBottomOpacity	number	same JSON key	same JSON key
heroImageSrc	enrollHeroImageSrc	text	same JSON key	same JSON key
card03Bg	enrollCard03Bg	color	same JSON key	same JSON key
card03BgOpacity	enrollCard03BgOpacity	number	same JSON key	same JSON key
card03TextColor	enrollCard03TextColor	color	same JSON key	same JSON key
hero image upload	enrollHeroImageFile	file	сохраняется как heroImageSrc после upload	сохраняется как heroImageSrc после upload

Примечание: legacy-ключи существуют только для части старых color-полей и только в global контуре.

Автосохранение

• EnrollmentBlockSettingsEditor:
  • autosave по onInputCapture/onChangeCapture;
  • debounce submit (~450ms);
  • file change отправляется сразу.
• TemplateSectionsEditor:
  • autosave секций по цветам/enable/reorder;
  • для value секции style controls отключены.

Как добавить новый блок в шаблон (стандарт)

1. Создать блок в src/components/blocks/**.
2. Зарегистрировать в src/components/blocks/registry.ts.
3. Вывести в библиотеке блоков (/{locale}/offers/templates/blocks).
4. Добавить схему настроек блока (типы, поля, defaults, normalize).
5. Реализовать чтение/запись:
   • global read/write;
   • template read/write.
6. Подключить блок в шаблонной странице (например, PremiumTemplatePage).
7. Зафиксировать storage keys, resolve chain и write flow в этом документе.

Smoke-check после изменений

1. Изменить поле в библиотеке блоков -> проверить, что changed только global контур.
2. Изменить то же поле в админке шаблона -> проверить, что changed только template контур.
3. Проверить upload изображения в обоих контурах.
4. Проверить, что секция value не имеет конкурирующих style-полей секции.