ms3Remains

Остатки товаров по комбинациям опций для MiniShop3
Документация
Документация
товары остатки экспорт импорт свойства товаров cvs miniShop3
Иван Бочкарев
Автор дополнения
Иван Бочкарев
Пакетов
44
Закачек
329
Обычно отвечает в течение суток
Автор дополнения
Иван Бочкарев Иван Бочкарев
Пакетов
44
Закачек
329
Обычно отвечает в течение суток

mspTBank

Интеграция с платежной системой T-Bank

mxQuickView

Компонент для быстрого просмотра ресурсов и товаров в MODX

msp3BePaid

Оплата через bePaid для MiniShop3
Версия 1.0.0-beta3
Дата выпуска 27.09.2026
Загрузки 3
Просмотры 157
Внимание, этот компонент требует PHP 8.2 или выше!
Внимание, этот компонент требует MODX 3 или выше.
Управляйте остатками не только товара целиком, но и каждой конкретной комбинации его опций.

Цвет × размер, объём × фасовка, материал × комплектация — ms3Remains хранит отдельный остаток для каждой комбинации, проверяет наличие при добавлении в корзину и оформлении заказа, а также автоматически списывает и возвращает остатки в зависимости от статуса заказа.

Компонент создан для MODX Revolution 3 + MiniShop3.

Когда обычного остатка недостаточно?

Представим товар — футболку с двумя опциями: цветом и размером.

  • Чёрный / S — 5 шт.
  • Чёрный / M — 2 шт.
  • Чёрный / L — 0 шт.
  • Белый / S — 8 шт.
  • Белый / M — 4 шт.
  • Белый / L — 3 шт.

Общий остаток товара ничего не говорит о наличии конкретного варианта.

ms3Remains позволяет хранить остаток отдельно для каждой комбинации и использовать его при работе с корзиной, заказами и каталогом.

Как это работает

  1. У товара есть опции — например, цвет и размер.
  2. ms3Remains формирует комбинации выбранных значений.
  3. Для каждой комбинации хранится собственный остаток.
  4. При добавлении товара в корзину проверяется доступное количество.
  5. Перед оформлением заказа остаток проверяется повторно.
  6. При переходе заказа в настроенный статус товар списывается.
  7. При отмене или возврате заказа списанное количество возвращается.

В результате покупатель всегда работает с актуальным наличием конкретного варианта товара.

Остатки прямо в карточке товара

Для товара доступна отдельная работа с остатками его комбинаций.

Можно увидеть и изменить количество для конкретного набора опций: цвет, размер, объём, комплектация и любые другие опции MiniShop3.





Общий список остатков

Для управления остатками большого каталога предусмотрен отдельный раздел.

В одном месте можно работать с остатками различных товаров и их комбинаций, использовать поиск и фильтрацию, а также импортировать и экспортировать данные через CSV.





Любые комбинации опций

ms3Remains не ограничивается стандартными вариантами «цвет + размер».

В комбинацию могут входить любые опции MiniShop3:

  • цвет;
  • размер;
  • объём;
  • вес;
  • материал;
  • комплектация;
  • фасовка;
  • любые пользовательские опции.

Количество может быть дробным, поэтому компонент подходит не только для штучных товаров, но и для товаров, которые продаются по весу, длине, объёму или другим единицам измерения.

Проверка наличия при покупке

ms3Remains участвует непосредственно в процессе покупки.

Если покупатель пытается добавить больше товара, чем доступно для выбранной комбинации, количество не будет превышать доступный остаток.

Проверка выполняется не только при добавлении в корзину, но и перед оформлением заказа.

Это позволяет избежать ситуации, когда покупатель оформляет заказ на комбинацию, которой фактически уже нет.

Автоматическое списание и возврат

Не нужно вручную изменять остатки после каждого заказа.

ms3Remains интегрируется с жизненным циклом заказа MiniShop3:

  • заказ переходит в настроенный статус → остаток списывается;
  • заказ отменён или удалён → списанное количество возвращается;
  • заказ повторно попадает в тот же статус → повторного списания не происходит.

Статусы, при которых выполняются эти действия, настраиваются в компоненте.





Работа с ms3Variants

ms3Remains может использоваться совместно с ms3Variants.

Это позволяет учитывать отдельное наличие для вариантов товара и использовать остатки при работе с каталогом и карточкой товара.

Отображение остатков на сайте

С помощью сниппета ms3Remains можно получить информацию о наличии товара и его комбинаций.

Доступны различные варианты отображения:

  • точное количество;
  • «В наличии» / «Нет в наличии»;
  • состояние «Много» при достижении заданного порога;
  • остаток выбранной комбинации;
  • данные в JSON;
  • остатки по значениям опций.

Это позволяет самостоятельно реализовать любой интерфейс отображения наличия на фронтенде.

Совместимость с каталогом

Остаток может быть представлен через стандартное поле stock, благодаря чему его можно использовать в существующих шаблонах, фильтрах и других компонентах MiniShop3.

Например, можно построить каталог с фильтром:

Только товары в наличии

Также ms3Remains можно использовать вместе с mFilter и другими механизмами фильтрации каталога.

Импорт и экспорт

Для работы с большим количеством товаров предусмотрен CSV.

Это позволяет массово обновлять остатки и интегрировать их с внешними системами учёта.

  • экспорт остатков;
  • подготовка данных во внешней системе;
  • массовое изменение;
  • импорт обратно в MODX.



Для разработчиков

ms3Remains можно использовать не только через интерфейс менеджера.

Компонент предоставляет программный API и события, позволяющие интегрировать остатки с собственными решениями и внешними системами.

Возможности интеграции включают:
  • получение и изменение остатков через API;
  • работу с комбинациями опций;
  • события изменения остатков;
  • работу с CSV;
  • использование остатка через stock;
  • интеграцию с каталогом и фильтрацией.

Не складская система

ms3Remains решает конкретную задачу — учёт доступного количества товара и его комбинаций в MiniShop3.

Компонент не пытается заменить полноценную WMS/ERP-систему.

В нём нет:
  • нескольких складов;
  • перемещения между складами;
  • резервирования;
  • инвентаризации;
  • полноценного журнала складских движений.

Если вам нужен именно учёт остатков товаров и их вариантов внутри интернет-магазина на MiniShop3 — ms3Remains закрывает эту задачу без необходимости внедрять полноценную складскую систему.

Преимущества ms3Remains

  • MODX 3 + MiniShop3 — современный стек.
  • Остатки по комбинациям — отдельное наличие для каждого варианта.
  • Любые опции — цвет, размер, объём, материал и собственные опции.
  • Проверка корзины — нельзя купить больше доступного количества.
  • Проверка перед оформлением — дополнительная защита от продажи отсутствующего товара.
  • Автоматическое списание — остатки меняются вместе со статусом заказа.
  • Автоматический возврат — отменённые заказы возвращают списанное количество.
  • Общий список остатков — удобное управление большим каталогом.
  • CSV — массовый импорт и экспорт.
  • ms3Variants — поддержка вариантов товаров.
  • API и события — интеграция с собственными решениями.
  • stock — использование остатков в существующей логике каталога.
  • Дробные значения — поддержка товаров, продаваемых не только поштучно.

Пример

Интернет-магазин одежды

Товар: «Футболка Basic»

Опции:
  • Цвет: Чёрный / Белый
  • Размер: S / M / L / XL

Для каждой комбинации можно задать собственное наличие.

Покупатель выбирает: Чёрный + M

ms3Remains проверяет остаток именно этой комбинации.

Если доступно 2 шт. — покупатель может приобрести максимум 2.

Если остаток равен 0 — комбинация недоступна.

При оформлении заказа остаток будет списан в соответствии с настроенным статусом заказа.

Требования

  • MODX Revolution 3.x
  • PHP 8.2+
  • MiniShop3
  • VueTools 1.2.0+
  • pdoTools 3.x
  • MySQL 5.7+ или MariaDB 10.3+

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0-beta3] - 2026-09-27

Fixed

  • msOnBeforeChangeInCart не разрешал product_id/options из контроллера корзины: MiniShop3 передаёт в событие только product_key+count. Из-за этого повторное добавление товара (add→change с суммой) и ручная смена количества в корзине обходили проверку остатка — можно было положить в корзину больше, чем есть в наличии. Guard теперь читает controller->cart[product_key] как fallback.

[1.0.0-beta2] - 2026-09-26

Added

  • Install and upgrade seed remain rows from ms3_products.stock and variant count when ms3remains_seed_on_install is on.
  • CSV import accepts product_id,quantity and creates the missing base remain row.

Changed

  • CSV import preview, paste field, and error list scroll so Close and Apply stay on screen.
  • Stocks filters apply as you change availability or search. The Apply button is gone.
  • Availability select stays 11rem wide. CSV actions sit next to the filters.
  • --msw-text-muted is #5c656b so the stocks total meets WCAG AA on the manager canvas.

Fixed

  • Fresh install left remains empty, so CSV export downloaded a header-only file.
  • Two-column CSV failed with remain_id not found.

[1.0.0-beta] - 2026-09-22

Added

  • Install and upgrade create ms3remainsOnBeforeRemainChange and ms3remainsOnAfterRemainChange in system_eventnames.
  • msOnBeforeChangeOrderStatus blocks the save when stock is short or the line identity is invalid.
  • Boot lexicon (MgrLexicon) for the manager CMP and the product tab.
  • Settings screen warns about empty deduct statuses, deduct/refund overlap, ms3Variants double-deduct, CommerceBridge1C, and MiniShop3's own inventory.
  • Russian and English lexicon for the manager Vue UI.

Changed

  • Manager Vue reads strings through VueTools @vuetools/useLexicon. Boot lexicon is merged into MODx.lang.
  • Saving settings drops a status id that sits in both deduct and refund lists. Deduct keeps it.
  • TrackedOptions and the option_keys setting skip reserved keys that start with _.
  • Rebuild from Settings writes the form first, so the sync toggles you see are the ones that run.
  • remains_default and moreless_count round to three decimal places on save.
  • The product tab option whitelist uses the same TrackedOptions rules as settings.

Notes

  • check_options runs only when the component is on and cart or order checks are on. A line with _variant_id skips the tracked-keys check. The variant is the identity.
  • Install leaves ms3remains_enabled off.
  • CI pins MiniShop3 1.13.0-beta1 and VueTools 1.2.0-pl+.
  • The manager UI build (assets/.../vue-dist/) is not in git. make gate and make build run npm run build.
  • Uninstall keeps ms3remains_* tables and settings.

[0.1.0-beta1] - 2026-09-11

Added

  • Remain row per option combination in ms3remains_remains: one row per (product_id, options_hash), quantity DECIMAL(12,3).
  • RemainService events: ms3remainsOnBeforeRemainChange and ms3remainsOnAfterRemainChange.
  • Order-status deduction with per-line idempotency (ms3remains_order_deductions). Refund on cancel or delete.
  • Cart and checkout availability checks.
  • One-way projection to msProductData.stock and ms3Variants.count, plus batch rebuild.
  • Product tab "Remains": option combinations and variants.
  • Manager "Stocks" section: list, filters, CSV export, preview, and commit.
  • Snippet ms3Remains: number, "In stock / Out of stock", "Many" threshold, JSON, and return=options.
  • Manager API at /api/mgr/ms3remains, permission ms3remains_manage.
  • Vue 3 and PrimeVue manager UI: Stocks and Settings.
  • Product tab shows an untracked hint until you save a remain row.
  • mFilter recipe: stock >= 1, then ms3.refresh() after AJAX.
  • Transactional MiniShop3 order-status wrapper through ms3.services.d/50-ms3remains.php.
  • Optional ms3Variants bridge and CommerceBridge1C detector.
  • Phinx migration, transport package, and CI (PHPStan, PHPUnit, Vue).

Notes

  • Install leaves ms3remains_enabled off.
  • CommerceBridge1C writes stock past this component. Import through CSV or the service API.
  • MiniShop3 CI pin: 1.13.0-beta1.
  • VueTools 1.2.0-pl+ (vuetools.theme / getActiveTheme).
  • Manager UI build (assets/.../vue-dist/) is not in git. make gate and make build run npm run build.
  • Uninstall keeps ms3remains_* tables and settings.

Последние обсуждения в сообществе MODX.pro