ms3Remains

ms3Remains — дополнение для MODX Revolution 3 и MiniShop3: остатки товаров по комбинациям опций. Одна строка отвечает на вопрос «сколько единиц с таким набором опций лежит на остатке».

Пример. У футболки есть опции color и size. Вы указываете их в ms3remains_option_keys, и компонент ведёт отдельный остаток для каждой пары: «красная / M», «красная / L», «синяя / M». Товар без опций работает с одной базовой строкой. Пустой ms3remains_option_keys не отключает опции в корзине: в расчёт остатка войдут все опции, которые покупатель передал с товаром.

С чего начать: Быстрый старт.

Минимальный путь

1. Установить MiniShop3, VueTools, pdoTools и ms3Remains.
2. Выключить встроенный inventory: ms3_inventory_enabled = 0.
3. Включить ms3remains_enabled, задать ms3remains_option_keys и статусы списания/возврата.
4. Заполнить остатки на вкладке товара или через CSV.
5. На витрине вывести сниппет ms3Remains (некэшируемый) или проекцию [[+stock]].

Быстрые ссылки

Нужно	Документ
Включить и проверить списание	Быстрый старт
Все ключи ms3remains_*	Системные настройки
Вкладка, список, рецепты витрины	Остатки
Списание и проверки корзины	Заказы
Параметры сниппета	ms3Remains
Варианты и двойное списание	ms3Variants
msProductData.stock и count	Проекция
Фильтр «в наличии» в каталоге	mFilter
CSV и PHP API	Обмен с внешними системами
Плагины на изменение остатка	События
Типовые ошибки	FAQ

Возможности

• Остаток на товар без опций, на комбинацию опций и на вариант ms3Variants
• Вкладка остатков на странице товара и раздел «Остатки» со списком, фильтрами и CSV
• Списание при смене статуса заказа и возврат при отмене или удалении
• Проверка доступности в корзине и перед оформлением заказа
• Проекция суммы в msProductData.stock и остатка варианта в ms3Variants.count
• Фильтр каталога «только в наличии» через mFilter по полю stock
• Сниппет ms3Remains: число, «В наличии / Нет в наличии», порог «Много», JSON и остатки по значениям опций

Чего в компоненте нет

Складов, резервов, перемещений, инвентаризаций и журнала движений. Если нужен полноценный WMS, этот компонент не подходит.

Модель

• Остаток — число DECIMAL(12,3) в таблице ms3remains_remains. Дробные значения подходят для весовых и мерных товаров.
• Комбинация опций кодируется полем options_hash. Одинаковые наборы дают один и тот же код независимо от порядка ключей и типа значения.
• Товар отслеживается, если у него есть хотя бы одна строка остатка. Без строк проверки корзины и заказа его пропускают.
• Истории изменений нет. Остаток меняется через manager UI, CSV-импорт или сервисный API. Кто и когда менял — по updatedon строки и по логу событий MODX, если пишете их в плагине на события компонента.

Что происходит с заказами

1. Покупатель добавляет товар в корзину. Компонент проверяет выбранные опции и достаточность остатка.
2. Заказ переходит в статус из ms3remains_deduct_statuses. Компонент списывает остаток по каждой строке. Повторный переход в тот же статус не списывает дважды.
3. Заказ переходит в статус из ms3remains_refund_statuses или удаляется. Компонент возвращает списанное.

Системные требования

Требование	Версия
MODX Revolution	3.x
PHP	8.2 или 8.3
MiniShop3	1.13.0-beta1 и совместимые сборки той же ветки
VueTools	1.2.0-pl и новее (vuetools/theme в Import Map)
pdoTools	3.x
MySQL	5.7+
MariaDB	10.3+

Зависимости

• MiniShop3 — товары, заказы, статусы
• VueTools — manager UI (тема vuetools.theme: aura или modx)
• pdoTools — рекомендуется для примеров Fenom

Опционально

Компонент	Роль
ms3Variants	варианты с отдельным count
CommerceBridge1C	каталог и цены. Запись остатков без Sync-адаптера не поддерживается

Inventory MiniShop3

Пока работает ms3Remains, держите ms3_inventory_enabled = 0. Встроенный inventory резервирует суммарный ms3_products.stock и конфликтует с остатками по комбинациям опций.

Права файловой системы

Transport package пишет:

• core/components/ms3remains/
• assets/components/ms3remains/
• core/config/ms3.services.d/50-ms3remains.php
• core/config/ms3.routes.d/manager/50-ms3remains.php

Каталог core/config/ должен быть доступен на запись при установке.

ms3Remains не меняет файлы MiniShop3, ms3Variants и CommerceBridge1C. Интеграция идёт через DI-фрагменты, события и таблицы с префиксом ms3remains_.

Установка

1. Подключите репозиторий ModStore. Для зашифрованного transport нужен провайдер modstore.pro, иначе установка падает с Package provider not found.
2. Установите MiniShop3, VueTools и pdoTools.
3. Extras → Installer — установите ms3Remains.
4. Настройки → Очистить кэш.

Установка создаёт namespace ms3remains, меню и controller manager, plugin и события, system settings, policy template и policy, таблицы ms3remains_remains и ms3remains_order_deductions, фрагменты MiniShop3 для сервиса статуса заказа и manager API.

Компонент ставится выключенным: ms3remains_enabled = false. Таблицы пустые.

Проверка после установки

1. В manager откройте меню ms3Remains: доступны разделы «Остатки» и «Настройки».
2. В core/config/ms3.services.d/ есть файл 50-ms3remains.php.
3. В core/config/ms3.routes.d/manager/ есть файл 50-ms3remains.php.
4. В БД есть две таблицы с префиксом сайта и именем ms3remains_*.

Типичные ошибки установки

Симптом	Причина	Действие
Меню есть, страницы пустые	нет VueTools или пустой vue-dist	проверьте VueTools
Вкладка товара без стилей	нет CSS из vue-dist	плагин подключает первый существующий файл: ms3remains-manager.css, затем ms3remains-product-tab.css
Таблиц нет	resolver миграций упал	смотрите error log MODX, переустановите пакет
API 404	нет route fragment	проверьте core/config/ms3.routes.d/manager/50-ms3remains.php и кэш
Статус заказа не списывает	нет service fragment или компонент выключен	проверьте 50-ms3remains.php и ms3remains_enabled

Термины

Термин	Значение
Комбинация / строка остатка	товар плюс набор опций или вариант, по которому хранится количество
Отслеживаемый товар	товар с хотя бы одной сохранённой строкой в ms3remains_remains
Проекция	запись суммы остатков в поле stock товара и/или count варианта
Проверки корзины	блокировка добавления и оформления, если опций не хватает или остаток меньше нужного