Техническая документация

Раздел для разработчиков: архитектура, модель данных, интеграции, контракты API, разбор legacy, архитектурные решения и план работ. Бизнес-основа — в верхнеуровневой документации, описание функций — в функциональной.

Новая система продажи товаров: монолит на Kotlin + Spring Boot, админка на React + Ant Design, источник номенклатуры и приёмник заказов — iiko Transport (api-ru.iiko.services).

Заменяет связку legacy-сервисов: PHP/Laravel site (сайт, админка Orchid, заказы, импорт iiko), Go menu (второй импорт iiko + API меню), Go payment, Go user, Node notification.

Состав документации

Архитектура

Документ	Содержание
01-architecture.md	Границы системы, модульный монолит, стек, нефункциональные требования
06-decisions.md	Принятые решения (ADR), открытые вопросы, план работ
franchise-model.md	Модель франчайзинга: франчайзи, юрлицо, подключение iiko, ресторан; секреты юрлица и денежный контур
admin-access-model.md	Админка ГК, Личный кабинет ФЧ и доступ сотрудников: учётные записи, роли, сессии, изоляция
customer-access-model.md	Покупатели сети и доступ к витрине
administrative-frontends.md	Frontend-приложения Админки ГК и Личного кабинета ФЧ
bootstrap-process.md	Первоначальная настройка установки

Модули

Документация реализованных модулей монолита: franchise, iiko, restaurant, iam, customer, dadata, admin, franchiseoffice, storefront.

Каталог

Документ	Содержание
02-catalog-domain.md	Доменная модель каталога и полная схема БД (DDL)
03-iiko-sync.md	Синхронизация с iiko: организации, меню, стоп-листы, ревизии, отказоустойчивость
04-admin-catalog.md	ТЗ на админку каталога: экраны, сценарии, поведение
05-catalog-api.md	Контракты API: публичная витрина + админский API
07-media.md	Изображения: инвентаризация размеров, пресеты, загрузка, нарезка, отдача
13-catalog-db.md	Целевая схема БД каталога: ресторан, импорт iiko, виртуальные товары и опции
14-catalog-grid.md	Контентная сетка категорий: товарные карточки разных размеров, видео и баннеры

Проектирование каталога по мере реализации переходит в документацию модулей.

Разбор legacy

Документ	Содержание
08-frontend-logic.md	Разбор логики legacy-витрины и legacy-бэкендов: что переезжает на бэкенд (доставка, зоны, режим работы, слоты, гейт оформления)
09-order-flow.md	Жизненный цикл заказа в legacy: статусы, отправка в iiko, оплата, отмена, уведомления — и постановка для модуля order
10-notifications.md	Уведомления: клиентский контур (TG/MAX/SMS), служебный контур (MAX-чаты), почта и ошибки — и постановка для модуля notifications
11-gift-dish.md	Блюдо в подарок: модель компенсации, выдача оператором через категорию или комментарий iiko, погашение на сайте и в операторском заказе
12-user-auth.md	Вход покупателей: одноразовый код, JWT access/refresh, сессии, logout и миграция случайных legacy-токенов
16-franchise-legacy.md	Что в legacy мешает франшизе и как это снимается в новой платформе

Границы первого этапа

В скоупе: каталог — импорт номенклатуры из iiko, доменная модель товара, админка каталога, публичное API витрины, медиа-хранилище, стоп-листы (чтение), справочники организаций и терминалов.

Вне скоупа первого этапа (проектируется позже): корзина и заказы, отправка заказов в iiko и статусы, оплата, клиенты и авторизация покупателей, скидки/промокоды/акции, доставка и зоны, уведомления, статистика.

Уточнение по итогам разбора витрины (08-frontend-logic.md): справочник организаций с расписанием и статусом точки и перенос SEO-контента категорий входят в первый этап — без них новая витрина не покажет режим работы и потеряет SEO. Зоны доставки, слоты «ко времени» и гейт оформления остаются на этапе заказа.

Каталог спроектирован так, чтобы заказ мог сослаться на catalog.product_variant → iiko.item без переделки модели.

Ключевые решения (кратко)

1. Два жёстко разделённых слоя данных. Схема iiko — зеркало источника, пишется только импортом, для человека read-only. Схема catalog — витрина, владелец — админка. Связь только через явные ссылки. Ни одно поле не «редактируется поверх» импорта.
2. iiko — источник истины по ценам, составу и наличию. Админка владеет мерчандайзингом: структура каталога, картинки, сортировка, SEO, бейджи, видимость, тексты-переопределения.
3. Витринное дерево категорий — собственное. itemCategories и productCategories из iiko используются только как сырьё для импорта и подсказок, а не как структура сайта.
4. Товар — это карточка с вариантами. «Панам 25/30/35/40 см» — 4 отдельных блюда в iiko (itemSizes у всех длины 1, sizeId: null) и один товар на витрине. Сборка карточки — ручная, с автоподсказкой кандидатов при импорте.
5. Один generic-товар вместо типизации таблицами. В legacy было dish_pizza, dish_snacks, dish_drinks, dish_non_food — каждый новый тип товара требовал миграции, модели, экрана. В новой модели тип товара — это данные (категория + ось вариативности + набор атрибутов), а не таблица.
6. Состав модификаторов контекстный, цена глобальная. В актуальной выгрузке v3 241 блюдо порождает 21 031 ссылку на 236 глобальных модификаторов. Состав и ограничения группы могут отличаться между блюдами, но цена одного modifier ID едина для всех блюд и размеров — это отдельно подтверждено бизнесом.
7. Модульный монолит на Spring Modulith. Границы модулей проверяются тестом, а транзакционный outbox (Event Publication Registry) идёт из коробки — событие «меню импортировано» не теряется.
8. Каталог собирается с нуля. Данные legacy не мигрируются: там товары разбиты по таблицам dish_pizza / dish_snacks / dish_drinks / dish_non_food, и перенос потянул бы за собой эту структуру. Мигрируются только пользователи, и это следующий этап.
9. Привязка к iiko хранит снимок. Блюда в iiko случайно удаляют и пересоздают с новым itemId. Вариант товара помнит, чем была позиция, замена подбирается по SKU, перепривязка — одно действие; карточка, фото и SEO не теряются.
10. Франшиза — единая платформа, деньги вне её. Продавец — юрлицо ФЧ, которому принадлежит ресторан; у юрлица свои аккаунты iiko, ЮKassa и ОФД. Платформа не принимает и не переводит деньги, роялти считается вне её по данным iiko (Франшиза).

Данные, на которых основано проектирование

Разобраны два актуальных ответа одного меню: от POST /api/2/menu/by_id (формат v2) и от POST /api/menu/v3/by_id (формат v3). Снимки в репозитории не хранятся — при необходимости они заново получаются теми же запросами к iiko.

формат                 v3: itemsGroups + глобальные products/modifiers
itemsGroups            15 категорий внешнего меню (витринная группировка iiko)
productCategories      34 учётные группы (бухгалтерская классификация iiko)
блюд                   241 ссылок в itemsGroups / 241 глобальная запись product
модификаторов          236 глобальных записей, по одной цене в sizePrices
групп модификаторов    700 вхождений / 11 вхождений без ID
ссылок на модификаторы 21 031; все ссылаются на существующий глобальный modifier ID
Халапеньо доп 30 г     один ID, цена 60 ₽, 111 блюд; все размеры пиццы 25/30/35/40 см

В v2 глобальные данные модификатора повторяются внутри каждого блюда, а v3 выносит их в отдельный массив modifiers[]. Набор ID и цены между ответами совпадают полностью; расхождений цен одного modifier ID между блюдами в актуальном v2 также нет.