# Магазин — обзор

Плагин превращает Celena CMS в полноценный интернет-магазин: каталог с вариациями и атрибутами, корзина, оформление заказов, клиентская база, аналитика, промокоды, отзывы, импорт/экспорт каталога. Платёжные шлюзы (Stripe, Kaspi, ЮKassa) подключаются отдельными суб-плагинами через хук — само ядро магазина к ним не привязано.

## Что добавляет плагин в админку

В сайдбаре появляется раздел **Магазин** с подменю:

| Раздел | URL | О чём |
|---|---|---|
| **Товары** | `/admin/shop/products` | Каталог: фильтры по табам (все / активные / черновики / архив), поиск по id/SKU/title, бренд, категория, остаток, цена, рейтинг, просмотры. |
| **Производители** | `/admin/shop/manufacturers` | Бренды товаров с логотипом, страной, сайтом и сортировкой. |
| **Атрибуты** | `/admin/shop/attributes` | Типизированные характеристики: text, number, select, multiselect, boolean, color. Используются как фасетные фильтры в каталоге. |
| **Заказы** | `/admin/shop/orders` | Полная карточка: позиции, итоги, доставка/оплата, история событий, sidebar статусов, ручное создание заказа. |
| **Клиенты** | `/admin/shop/customers` | Авто-база: каждый заказ создаёт/обновляет карточку. VIP-флаг, marketing opt-in, агрегаты (orders_count, total_spent, last_order_at). |
| **Доставка** | `/admin/shop/shipping` | Способы доставки: flat / by_weight / free / pickup, бесплатно от суммы. |
| **Города** | `/admin/cities` | Справочник городов (используется в чекауте). |
| **Оплата** | `/admin/shop/payments` | Методы оплаты: cash / card_offline / online_gateway / invoice. JSON-конфиг для платёжных плагинов. |
| **Промокоды** | `/admin/shop/promocodes` | Скидки: percent / fixed / free_shipping. Лимит использований, период действия. |
| **Отзывы** | `/admin/shop/reviews` | Модерация отзывов о товарах с авто-пересчётом рейтинга. |
| **Аналитика** | `/admin/shop/analytics` | KPI за 7/30/90 дней: выручка, заказы, средний чек, клиенты. График по дням, топ-5 товаров, разбивка по статусам. |
| **Импорт CSV** | `/admin/shop/products/import` | Массовая загрузка каталога. UTF-8 с BOM, совместимо с Excel/LibreOffice. |
| **Настройки** | `/admin/shop/settings` | 6 табов: общее / валюта / каталог / заказы / чекаут / налоги. |

На колокольчике уведомлений автоматически показывается бейдж с количеством заказов в статусе `new`.

На главном дашборде админа появляется виджет «Витрина магазина» с KPI и быстрыми ссылками — это часть стандартного `admin.dashboard.sections` хука.

## Что добавляет на сайте

| URL | Что |
|---|---|
| `/shop` | Витрина: карточки товаров, поиск, фильтр по категориям. |
| `/shop/product/{slug}` | Карточка товара: галерея, вариации, атрибуты, кнопка «В корзину». Счётчик просмотров. |
| `/cart` | Корзина — клиентская, на `localStorage`. JS-виджет в шапке темы синхронизируется. |
| `/checkout` | Оформление: имя, email, телефон, адрес. Авто-создание клиента в `shop_customers`. |
| `/checkout/thanks/{number}` | «Спасибо» после оформления. Префикс номера настраивается. |
| `/shop/reviews/add` | POST: добавить отзыв о товаре (модерация в админке). |

## Базовые настройки

После установки CMS дефолтная валюта — **USD ($)**. Сменить на любую (UAH, EUR, GBP, PLN…) можно в `Магазин → Настройки → Валюта`. Подробнее: [«Настройки магазина»](#).

## Локализация

Плагин полностью переведён на **ru / en / uk** — все админские страницы, статусы заказа/оплаты, sidebar, флэш-сообщения. Переключение через `?lang=en` (запоминается в cookie). Файлы локалей: `plugins/shop/languages/{ru,en,uk}.json`. Добавить свой язык — просто положить новый файл с теми же ключами.

## Архитектура

- **Каноны в БД на латинице** — статусы, оплата, источник: `new/paid/shipped/delivered/cancelled`, `pending/paid/refunded/cancelled`, `web/admin/phone/api`. Отображение через Translator при рендере.
- **Изоляция от ядра** — без активного плагина CMS работает; пункт меню, виджеты дашборда, хуки — всё подвешено через `admin.sidebar`, `admin.notifications`, `admin.dashboard.sections`.
- **Авто-миграции** — при загрузке плагин сам догоняет пропущенные миграции (раннер идемпотентен).
- **Single-file экспорт XLSX** — без зависимостей: `XlsxWriter` пишет валидный `.xlsx` через `ZipArchive` + минимальный OOXML.
- **Customer-репо** — `CustomerRepo::upsertFromOrder()` + `recalcAggregates()` поддерживают `shop_customers` в актуальном состоянии при каждом изменении заказа.

## Что плагин делает с базой

Активация применяет миграции из `plugins/shop/migrations/`:

- `0001_create_products` — каталог.
- `0002_create_orders` — заказы и позиции.
- `0003_product_variations` — JSON-вариации товара.
- `0004_create_reviews` — отзывы.
- `0005_extend_catalog` — производители, атрибуты, промокоды, методы доставки/оплаты, поля `status/is_featured/manufacturer_id/barcode/rating_*` у товара.
- `0006_product_views` — счётчик просмотров.
- `0007_customers_and_order_extras` — таблица `shop_customers`, `shop_order_history`, расширение `shop_orders` (subtotal/discount/tax/shipping/payment_status/source/timestamps).
- `0008_backfill_kzt_currency` — мигрирует валюту старых заказов на актуальную из настроек.

При деактивации данные **не удаляются**.

## Совместимость

- PHP 8.3+
- Celena Core 1.0+
- Не зависит от других плагинов.

При активации регистрирует:
- Сущность `shop_product` для модуля «Доп. поля» (можно добавить кастомное поле «Срок гарантии», «Возрастной рейтинг» и т.п.).
- Сущность `shop_product` для модуля «Категории» (категории товаров живут в общей таблице `celena_categories`).
- Источник для общего поиска `/search` — товары попадают в общую выдачу.
- Виджет «Витрина магазина» на главный дашборд через `admin.dashboard.sections`.
- Inline-теги `{price amount="…"}` и `{currency}` для тем.
- Блок-тег `[products …]` для тем (по аналогии с `[news]`).
- Уведомления о новых заказах в колокольчике.
