feat(web-api): единый контракт ошибок и HTTP-статусов

[Ibochkarev]

Описание

Единый success/error envelope Web API /api/v1 для TypeScript/Nuxt: HTTP status больше не теряется через ->getData(), field errors живут в top-level errors, additive error_code (snake_case).

Envelope #341 сохранён. Nested { error: {…} } не вводим.

Ключевые изменения

• ApiErrorCode + Response::error / errorWithCode / fromProcessor с error_code
• Web-контроллеры возвращают Response (create address → HTTP 201)
• Profile validation → top-level errors + HTTP 422 + зеркало data.errors (BC)
• Address conflict: existing_id в data; list → {items, total}
• Orders list: additive items (= orders)
• Cart/Order: DomainMs2Response поднимает field map в errors/422, _nf → 404, иначе business_rule
• Token/RateLimit middleware: token_expired / token_invalid / rate_limited; mint fail → 500/internal_error

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

• Новая функциональность (non-breaking change)
• Breaking change (частично: addresses list shape, conflict payload path, HTTP 201/404/422 точнее)

Связанные Issues

Closes #572

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

cd core/components/minishop3
composer ci:php   # exit 0
composer stan     # exit 0
php tests/WebApiErrorContractTest.php
php tests/ResponseFromProcessorTest.php

• Автоматические тесты (composer ci:php, composer stan)
• Ручное тестирование против live MODX

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

• MiniShop3: branch feat/issue-572-web-api-error-contract
• PHP: 8.4

Чеклист

• Код соответствует стилю проекта
• PHPStan проходит без новых ошибок
• Лексиконы не требовались (machine codes + существующие ключи)
• CHANGELOG.md — на релизе (по политике репо)

Wire contract (кратко)

Ситуация	HTTP	error_code
validation fields	422	validation_failed
auth / token	401	unauthorized / token_*
not found	404	not_found
conflict	409	conflict
rate limit	429	rate_limited
cart/order domain	400	business_rule
mint token fail	500	internal_error

Success: { success, message, data } — без изменений ключей.

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

• Addresses: data был голым массивом → {items,total} (breaking для клиентов с Array.isArray(data)).
• Conflict: errors.existing_id → data.existing_id.
• Email verify success при сбое session bind (token:null) оставлен как pre-existing UX ([Bug] Не работает подтверждение email в демо ЛК: мёртвая кнопка и неверная ссылка в письме #226); machine codes для verification token не пересекаются с API token_*.
• Docs на docs.modx.pro можно синхронизировать отдельно.