Web API: resolve category/product по alias|uri

[Ibochkarev]

Описание

Публичный lookup категории и товара по alias или uri (+ context) для headless SSR без numeric MODX id. Ответ тот же, что у GET …/get/{id}.

Контракт: ровно один из alias/uri. Ошибки lookup → 400 с lexicon. Невидимый / чужой context / неоднозначный alias → 404.

Кэш каталога (#579 cache-часть) — out of scope, follow-up. Docs #573 — вне репозитория, follow-up.

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

• Новая функциональность (non-breaking change)
• Исправление бага (non-breaking change)
• Breaking change (изменение, ломающее обратную совместимость)
• Рефакторинг (без изменения функциональности)
• Документация
• Другое (опишите):

Связанные Issues

Closes #579 (resolve-only; cache и docs.modx.pro/#573 — follow-up)

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

cd core/components/minishop3
php -l src/Services/Catalog/CatalogResolve.php
# … и остальные затронутые PHP — exit 0

vendor/bin/phpunit tests/Unit/Services/Catalog/CatalogResolveTest.php
# OK — 24 tests, exit 0

php tests/CategoryCatalogRoutesTest.php
php tests/ProductCatalogRoutesTest.php
php tests/TokenMiddlewarePublicRoutesTest.php
# OK, exit 0

vendor/bin/phpunit tests/Integration/WebApi/HeadlessStorefrontErrorsTest.php \
  --filter testProductGetWithoutLookupParamsReturns400
# OK — 1 test, exit 0

• Ручное тестирование
• Автоматические тесты (unit CatalogResolve, smoke routes/TokenMiddleware, integration 400)
• Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

• MiniShop3: feat/issue-579-catalog-resolve-alias-uri
• MODX: n/a (unit/smoke)
• PHP: 8.4.23

Скриншоты (если применимо)

До	После
n/a	n/a

Чеклист

• Код соответствует стилю проекта
• Добавлены/обновлены комментарии в сложных местах
• Изменения не ломают существующую функциональность
• Лексиконы добавлены на двух языках (ru/en)
• PHPStan проходит без новых ошибок (composer stan / CI job PHPStan)
• ESLint проходит без ошибок (npm run lint:ci для Vue) — Vue не трогали
• Обновлён CHANGELOG.md — на релиз

Дополнительные заметки

Endpoints

GET /api/v1/category/get?uri=catalog/shoes/&context=web
GET /api/v1/category/get?alias=shoes&context=web
GET /api/v1/product/get?alias=red-sneakers&context=web

Реализация

• CatalogResolve — parse/normalize + findUniqueId (LIMIT 2)
• CategoryCatalogService / ProductCatalogService — resolveByLookup → getById
• Маршруты GET /get зарегистрированы перед GET /get/{id}
• TokenMiddleware: exact path или prefix/ (без ложного match на getting)

Вне scope

• Catalog HTTP/MODX cache + TTL/invalidation
• Документация docs.modx.pro ([Feature] Docs: полный справочник Web API для Nuxt/TypeScript (сверка с web.php) #573)
• Manager API, SEO ([Feature] Web API: seo-блок для product/category (headless SSR) #567)