[Feature] Web API: интеграционный test suite для headless Nuxt journey #574

Описание функции

Интеграционный test suite для Web API (api.php → /api/v1), который гоняет headless Nuxt customer journey на уровне HTTP-контракта: Router + middleware + controllers + envelope. Не domain facades и не source-scan.

Сейчас в репозитории много unit/smoke и несколько Level-2 сервисов. Почти нет тестов, которые проходят storefront flow так же, как Nuxt.

Проблема, которую решает

Регрессии в TokenMiddleware, Response::normalizeResponse/getData(), CORS, cart→order bind и submit ломают Nuxt, а CI остаётся зелёным: тесты проверяют SQLite-facade или static helpers, не wire-контракт.

Нужен один suite «headless journey», который падает, если изменился JSON/HTTP публичного API.

Текущее покрытие (проверено по journey)

Легенда: HTTP = Router::dispatch / Web API envelope. Domain = facade/service без Web boundary. Static = helpers / source-scan / DTO.

* CustomerAuthEndpointsTest делает Router::loadRoutes(web.php) + dispatch, но runProcessor заглушен. Это mapping auth routes/status codes, не полный login+DB+cart transfer.

Что ещё есть (не journey)

• Token public routes / refresh removed / session revoke — source + policy ([Bug] REST API: cart/get недоступен анонимно, рассинхрон publicRoutes и хардкод строк вместо лексикона #408/[Bug] Web API: /token/refresh возвращает success, хотя не реализован #334/fix(auth): session bypass после revoke API-токенов + Web logout #462).
• CorsConfigNormalizeTest — pure config ([Bug] CORS: дефолт allowed_origins=* вместе с allow_credentials=true #335), не HTTP preflight.
• ResponseFromProcessorTest, RateLimitMiddlewareTest — изолированные куски.
• Manager ACL Router dispatch — mgr, не storefront.
• Smoke: composer test:smoke → standalone tests/*Test.php; PHPUnit → tests/Unit + tests/Integration.

Сквозного headless HTTP journey нет. Domain coverage cart/order/auth кусками есть. Для Nuxt gate этого мало.

Предлагаемое решение

Архитектура suite

tests/Integration/WebApi/
  HeadlessStorefrontJourneyTest.php   # happy path 1→15 (где endpoints существуют)
  WebApiTestCase.php                  # bootstrap Router + fixtures + token helpers
  support/…                           # fixtures / HTTP client wrapper

Фазы:

1. Phase A: паттерн CustomerAuthEndpointsTest — Router + web.php + stubbed services/DI для cart/order/product, assert HTTP status + envelope keys. Быстро в CI.
2. Phase B: MySQL/SQLite fixtures как AuthManagerMysqlLifecycleTest / cart SQLite — draft rows, published product, delivery/payment members.
3. Phase C (optional): HTTP к api.php через built-in server — nightly, не блокер merge.

Минимум для закрытия issue: Phase A+B на PHPUnit (composer test или composer test:web-api).

Auth handling

1. GET /customer/token/get или TokenMiddleware auto-mint → сохранить token.
2. Authorization: Bearer и отдельно cookie ms3_token.
3. Guest token → register/login → новый token + cart transfer (см. [Bug] Login/Register: rebind guest API-токена без ротации (token fixation) #412 / [Feature] Web API: контракт customer auth для Nuxt SSR (me / TTL / cookie+Bearer) #571).
4. Cabinet addresses/orders: customer_id > 0.

Database fixtures (Phase B)

• 1 published product (+ option keys для change-option).
• Active delivery + payment + msDeliveryMember.
• Customer credentials для login/register.
• Cleanup per test / transaction.

Полный MODX manager bootstrap не обязателен, если xPDO/SQLite harness уже принят в Integration/.

CORS

• Unit уже есть (CorsConfigNormalizeTest).
• В suite: один preflight OPTIONS через Router/middleware → 200 + headers при allowlisted origin. Кейс empty origins / *+credentials ([Bug] CORS: дефолт allowed_origins=* вместе с allow_credentials=true #335).
• Не дублировать весь CORS matrix в journey.

Happy path (assert envelope)

Где endpoint существует:

• HTTP status (не только success в body — см. [Feature] Web API: единый контракт ошибок и HTTP-статусов для TypeScript/Nuxt #572 getData()).
• success / data shape.
• Cart: status.total_* после add/change ([Feature] Web API: нормализовать контракт ответа корзины (cart/get) для headless #570).
• Cost: cart_cost / delivery_cost / payment_cost / cost после set delivery/payment.
• Submit: data.redirect или payment redirect key.
• Customer orders: list/get после submit (если status позволяет).

Error cases (минимум)

Чего suite не должен ждать

В web.php пока нет public delivery/list, payment/list, category API (#563–#569). Journey ставит delivery_id/payment_id из fixture IDs (как Fenom form), с пометкой «discovery later».

Затронутые места

• tests/Integration/WebApi/* (новые)
• composer.json scripts / scripts/ci-php.sh / CI workflow
• Переиспользовать stubs: WebApiModxStub, CustomerAuthPdoStore, OrderProductSqliteStore где возможно
• Не дублировать mgr ACL tests

Альтернативные варианты

1. Только расширять facade tests. Не ловит Web controller / getData() / middleware.
2. Browser e2e (Playwright). Дорого. Не заменяет API contract suite.
3. Полагаться на docs ([Feature] Docs: полный справочник Web API для Nuxt/TypeScript (сверка с web.php) #573). Docs не gate.

Примеры использования

cd core/components/minishop3
composer test:web-api
# или: vendor/bin/phpunit --testsuite WebApi

Nuxt-команда перед релизом витрины: зелёный journey = контракт /api/v1 не сломан.

Обратная совместимость

• Новые тесты не меняют runtime API.
• Flaky MySQL: @group mysql / skip без DSN (как существующие Mysql integration).

Критерии приёмки

• PHPUnit (или эквивалент в CI) suite бьёт Web routes через Router/api boundary.
• Happy path: product list+get → cart add/change/(change-option) → get cart → token/login → set address + delivery_id + payment_id → order/cost → submit → customer order get (или явный skip с reason).
• Assertы на HTTP status + success/data (не только domain arrays).
• Bearer и хотя бы один cookie auth path.
• Error cases: 401 token, 404 product, validation/business на submit или set.
• CORS preflight или config+middleware smoke в том же suite/adjacent test.
• CI: suite в composer ci:php или отдельный required job; skip policy для MySQL задокументирован.
• README/tests: как запустить локально.
• Не требует несуществующих endpoints [Feature] Web API: публичный Category API для headless (list / get / tree) #563–[Feature] Web API: публичный список методов оплаты (payment/list) #569.

Дополнительный контекст

• Ближайший образец HTTP Web: CustomerAuthEndpointsTest.php.
• Domain cart: Integration/Cart/CartFacadeDraftStoreTest.php (нет change-option).
• Domain submit: OrderFinalizeServiceTest ≠ POST /order/submit.
• Related: [Feature] Web API: нормализовать контракт ответа корзины (cart/get) для headless #570 cart contract, [Feature] Web API: контракт customer auth для Nuxt SSR (me / TTL / cookie+Bearer) #571 auth, [Feature] Web API: единый контракт ошибок и HTTP-статусов для TypeScript/Nuxt #572 errors/HTTP, [Feature] Docs: полный справочник Web API для Nuxt/TypeScript (сверка с web.php) #573 docs, [Feature] Публичный sessionless API для программного создания заказов #507 programmatic orders (другой вход).