feat(web-api): галерея изображений товара (images[])

[Ibochkarev]

Описание

GET /api/v1/product/get/{id}?include_images=1 добавляет в карточку товара images[]: упорядоченные active originals (parent_id=0, type=image), url/thumb, thumbs (map размеров), name/description, derived alt (name, иначе pagetitle), is_preview через ProductImageService::resolvePreviewFileId.

Без флага ключа images нет. С флагом и без файлов — images: []. Корневые image/thumb не трогаются.

product/list?include_images=1 подмешивает тот же массив (cap 10 файлов на товар, один batch на страницу). GET /api/v1/product/{id}/images отдаёт только { images } с той же сериализацией. Невидимый товар — 404.

thumb берёт child с папкой ms3_product_thumbnail_size (как mgr GetList path LIKE %/{size}/). Если такого размера нет — первый active child по id, иначе url оригинала. thumbs — все active children, ключ размера из path/url. Media source на hot path не открывается.

Allowlist после modifyFields отсекает hash/path/createdby. Отдельного DB-поля alt нет.

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

• Новая функциональность (non-breaking change)

Связанные Issues

Closes #566

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

cd core/components/minishop3
php tests/ProductCatalogImagesRoutesTest.php
php tests/ProductCatalogServiceTest.php
php tests/TokenMiddlewarePublicRoutesTest.php
vendor/bin/phpunit tests/Unit/Services/Product/ProductGalleryPublicSerializerTest.php
composer ci:php
composer stan

Команда	Результат
smoke-тесты галереи / whitelist / publicRoutes	exit 0
PHPUnit serializer	6 tests, exit 0
composer ci:php	PHPUnit 245, exit 0
composer stan	OK, exit 0

• Автоматические тесты
• Ручное тестирование на живом MODX/MySQL

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

• MiniShop3: branch feat/issue-566-product-gallery-images
• MODX: n/a (smoke/ci без полной установки)
• PHP: 8.4.17

Чеклист

• Код соответствует стилю проекта
• Изменения не ломают существующую функциональность
• Лексиконы не нужны (новых error keys нет)
• PHPStan локально зелёный
• CHANGELOG не трогал (release-time)

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

Follow-up: integration-тест unpublished 404 + SQL active filter на живой БД. Выбор thumb по первому ключу media source (mgr GetList, если setting не совпал) по-прежнему не на hot path.

[biz87]

Влил #597 (facets) — этот PR теперь конфликтует с beta, нужен ребейз. Сам резолвить не стал: в ProductController конфликт разрезал посередине два разных метода (getImages отсюда и filters из #597), плюс есть один вопрос по security, который лучше решить тебе.

Конфликтуют 6 файлов — почти везде обычный union (обе стороны добавляют своё):

• config/routes/web.php — /{id}/images vs /filters, нужны оба
• ProductController.php — методы getImages() и filters()
• ServiceRegistry.php / ServiceRegistryFactories.php — ms3_product_gallery_public vs ms3_product_facets
• TokenMiddleware.php + TokenMiddlewarePublicRoutesTest.php — см. ниже

Вопрос по публичным роутам. В этом PR ты меняешь точечные записи на широкий префикс:

'/api/v1/product/',   // вместо '/api/v1/product/filters' и т.п.

Матчинг идёт через str_starts_with, так что это делает публичной всю группу /api/v1/product/*. Сегодня это безвредно — в группе только каталожные GET (get/{id}, list, filters, {id}/images), все и так публичные. Но это меняет контракт с «явный allow-list» на «вся ветка открыта»: любой будущий роут в этой группе станет публичным молча, без отдельного решения. После #584, где мы наоборот сужали поверхность, это шаг в другую сторону.

Понимаю, откуда взялось: /{id}/images с динамическим сегментом через префиксы точечно не выразить. Варианты — либо осознанно оставить широкий префикс (тогда стоит закрепить тестом, что в группе /product только публичные GET), либо завести отдельный матчер по шаблону (/api/v1/product/*/images). Выбор за тобой, я бы не оставлял widening молча.

Остальное по P1 идёт хорошо: #595 (journey suite) и #597 (facets) влиты, beta зелёная. Как ребейзнёшь — сразу возьму #598, дальше #599 и #600.