镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

feat(inventory): variant key for SKU-level stock accounting (#1001) - #1003

Open
Ibochkarev wants to merge 3 commits into
modx-pro:betafrom
Ibochkarev:feat/issue-1001-inventory-variant-key
Open

Ibochkarev wants to merge 3 commits into
modx-pro:betafrom
Ibochkarev:feat/issue-1001-inventory-variant-key

Conversation

@Ibochkarev

Copy link
Copy Markdown
Member

Описание

Точка расширения для остатков на уровне SKU без изменения поведения ядра по умолчанию (#1001).

  • InventoryKey: нормализация variantKey ('' → null), identity() для группировки.
  • OrderInventoryCoordinator: группирует строки заказа по (product_id, variantKey). Вариант задаёт дополнение событием msOnInventoryResolveKey (params: orderProduct, product_id, options, order; результат: returnedValues['variantKey']). Без подписчиков — product-level, как раньше.
  • InventoryStockStoreInterface: stock-методы принимают InventoryKey, журнал — по ключу (variant_key, '' = product). PDO-стор выдерживает установки без миграции.
  • ProductStockInventory: для variant-ключей товарный ms3_products.stock не трогается; остаток запрашивается через msOnInventoryAvailable, дополнение синкается через reserve/commit/release события.
  • Миграция: variant_key VARCHAR(128) NOT NULL DEFAULT '', уникальный (order_id, product_id, variant_key).

Без дополнений поведение и схема не меняются, кроме новой колонки. Замена ms3_inventory (ERP) получает variantKey в том же InventoryKey — интерфейс сервиса не меняется.

Тип изменений

  • Новая функциональность (non-breaking для товарного учёта)

Связанные Issues

Closes #1001

Как это было протестировано?

  • Unit: InventoryVariantKeyTest (ключ, in-memory журнал, variant reserve без товарного остатка) + существующие инвентарные тесты — 821 тестов OK.
  • PHPStan — чисто. Smoke 142 OK.
  • Деплой на project.test: миграция применилась (variant_key + order_product_variant unique), healthcheck зелёный.

Конфигурация: MiniShop3: origin/beta (7d53553) + этот PR, MODX 3.x, PHP 8.2+

…#1001)

- InventoryKey normalizes variantKey ('' -> null), adds identity()/isVariant().
- OrderInventoryCoordinator groups order lines by (product_id, variantKey)
  resolved via msOnInventoryResolveKey (orderProduct, product_id, options,
  order => returnedValues['variantKey']). Without addons all keys are
  product-level, behaviour unchanged.
- InventoryStockStoreInterface stock methods take InventoryKey, ledger
  methods are keyed by InventoryKey (variant_key column, '' = product).
- PdoInventoryStockStore keeps product stock for core keys and tolerates
  installs without the migration (falls back to pre-variant queries).
- ProductStockInventory: variant stock comes from msOnInventoryAvailable,
  core ms3_products.stock is not decremented for SKU sales; addons sync
  their tables on reserve/commit/release events.
- Migration adds variant_key NOT NULL DEFAULT '' and unique
  (order_id, product_id, variant_key). '' keeps the unique index
  meaningful (MySQL UNIQUE allows duplicate NULLs).
- InMemory store + test doubles updated; new InventoryVariantKeyTest.
@Ibochkarev
Ibochkarev requested a review from biz87 November 9, 2026 03:35
@Ibochkarev

Copy link
Copy Markdown
Member Author

CI PHP lint + smoke упал на InventoryStockConcurrentMysqlTest::testSecondConnectionCannotReleaseTheSameOrderTwice — прямые вызовы стора со старым сигнатурой (int $productId). Обновил на InventoryKey (коммит f8edbbb).

Локально: Unit 821, smoke 142 — OK. Новый run 42557502918 уже идёт на f8edbbb.

@biz87

biz87 commented Nov 15, 2026

Copy link
Copy Markdown
Member

Возвращаю, два дефекта. Остальное проверил — сделано добротно.

1. down() не возвращает исходный индекс

Воспроизвёл на стенде. После phinx rollback:

variant_key: убрана
индексы: PRIMARY, product_id

Уникальный order_product (order_id, product_id) не восстановлен. Журнал резервов остаётся без гарантии уникальности — а на ней держится insertReservation(), который возвращает false при уже существующей строке. После отката двойной резерв по одной позиции заказа станет возможен молча.

Нужно пересоздавать старый индекс в down() после удаления order_product_variant.

2. Длина variantKey ничем не ограничена

Колонка VARCHAR(128), а в InventoryKey нет ни проверки длины, ни усечения, ни хеширования. resolveKey() принимает от дополнения любую строку.

Событие передаёт подписчику options, а докблок разрешает «a SKU string or options hash» — передать сырой JSON опций вместо хеша это ошибка на один шаг, и он легко перевалит 128 символов. Дальше:

  • строгий MySQL (на моём стенде STRICT_TRANS_TABLES) — вставка падает с «Data too long», смена статуса заказа срывается;
  • нестрогий — ключ молча обрежется, и два разных SKU схлопнутся в одну строку журнала. Неверный учёт остатков, то есть худший исход именно для этой фичи.

Предлагаю в конструкторе InventoryKey: при длине больше 128 брать hash('xxh128', $variantKey) либо бросать InvalidArgumentException.

Сейчас у этой точки расширения ноль потребителей — момент закрепить контракт именно этот. После появления дополнений добавление ограничения само станет ломающим изменением.

Две мелочи

catch (\Throwable) вокруг события глушит любую ошибку дополнения и тихо откатывается на товарный учёт, не записав ничего в лог. Для учёта остатков тишина — плохая стратегия, стоит логировать на уровне WARN.

В докблок события просится требование стабильности ключа. Событие срабатывает на каждый вызов qtyByKey() — отдельно в assert, reserve, commit и release. Если дополнение вычислит ключ из изменяемых данных, резерв и освобождение уйдут по разным ключам и резерв утечёт.

Что проверено и вопросов не вызывает

  • Миграция идемпотентна и применяется чисто: varchar(128) NOT NULL DEFAULT '', уникальный order_product_variant создан, повторный прогон пустой.
  • Снятие старого индекса до создания нового здесь безопасно, хотя DDL в MySQL не транзакционный: исходный order_product уникален, значит дублей в данных быть не может и создание тройного индекса упасть не способно.
  • Изменение сигнатур InventoryStockStoreInterface формально ломающее, но допустимое: стор не заявлен точкой замены — ключ interface в ServiceRegistry есть только у ms3_inventory → InventoryServiceInterface, и он не менялся; в документации стор тоже не упоминается. Твоя формулировка «интерфейс сервиса не меняется» корректна.
  • Компромисс «одна строка с вариантом — и товарные строки тоже теряют атомарный batch-путь» описан в комментарии и возражений не вызывает.
  • Тесты 955/3295, инвентарные 46/115, PHPStan чисто.

@Ibochkarev

Copy link
Copy Markdown
Member Author

Исправления по ревью

1. down() восстанавливает индекс order_product

После удаления order_product_variant и колонки variant_key теперь воссоздаётся оригинальный уникальный индекс (order_id, product_id). Без него после отката миграции двойной резерв становился возможен молча.

2. Ограничение длины variantKey

В конструкторе InventoryKey добавлена проверка: если длина >128 символов → берётся hash('xxh128', $variantKey). Это гарантирует, что ключ всегда влезает в VARCHAR(128) колонку БД.

if ($variantKey !== '' && strlen($variantKey) > 128) {
    $variantKey = hash('xxh128', $variantKey);
}

3. Логирование ошибок события

catch (\Throwable) в resolveKey() теперь логирует ошибку на уровне WARN:

$this->modx->log(
    MODXRevolutionmodX::LOG_LEVEL_WARN,
    '[ms3] msOnInventoryResolveKey failed: ' . $e->getMessage()
);

4. Документация

  • Уточнён докблок resolveKey() — требование стабильности ключа, автоматическое хеширование длинных ключей.
  • Обновлён докблок InventoryKey — описание хеширования.

Проверки:

  • php -l — без ошибок
  • composer stan — [OK] No errors
  • vendor/bin/phpunit --testsuite Unit — 43 теста OK
  • vendor/bin/phpunit --testsuite Integration --filter Inventory — 3 теста OK

Коммит: 294d2062 — fix(issue-1001): address variantKey length and down() migration + event documentation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Учёт остатков: ключ позиции (variantKey) и остаток от дополнений

2 participants