# Дизайн: аудит заказов, оплаты и админки заказов

**Дата:** 2026-05-28  
**Статус:** Ready for implementation planning

## Контекст

Проект — магазин изделий ручной работы с витриной, личным кабинетом и админкой. Самый рискованный бизнес-поток сейчас проходит через создание заказа, доставку, подтверждение цены, оплату, смену статусов, чат заказа и синхронизацию UI через React Query/SSE.

Предыдущий документ `docs/superpowers/specs/2026-05-28-admin-orders-improvements-design.md` описывает UX-доработку админки заказов. Этот документ шире: он задает дизайн аудита логики и исправлений вокруг заказов и оплаты.

## Цели

- Найти логические ошибки и рассинхроны в потоке заказа от checkout до финального статуса.
- Приоритизировать проблемы по риску для данных, оплаты, остатков и пользовательского опыта.
- Исправить только подтвержденные проблемы высокой ценности, не превращая аудит в большой несвязанный рефакторинг.
- Подготовить отдельный список безопасных рефакторингов, которые стоит делать после стабилизации тестами.

## Не в рамках этой итерации

- Редизайн витрины, карточек товара или всей админки.
- Полный аудит всех CRUD-разделов админки.
- Миграция с SQLite или изменение инфраструктуры деплоя.
- Новая ролевая модель вместо текущего `verifyAdmin`.
- Переработка публичных контрактов `/api/categories` и `/api/products`.

## Рекомендованный подход

Первая итерация должна быть сфокусирована на сквозном потоке `orders/payments/admin-orders`, а не на всем проекте сразу. Этот поток объединяет серверные инварианты, платежи, остатки, админские действия, React Query cache и realtime-обновления, поэтому дает максимальную отдачу от аудита.

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

- Timebox-аудит всего проекта даст широкую карту проблем, но исправления окажутся менее связными.
- Отдельный frontend-only или backend-only аудит проще выполнить локально, но он хуже ловит ошибки на стыке API, статусов, кеша и UI.

## Область анализа

### Backend

- `server/src/routes/user-orders.js` — создание заказа, checkout, списание остатков, доставка.
- `server/src/routes/user-payments.js` — создание и проверка платежа.
- `server/src/routes/webhook-yookassa.js` — обработка платежных вебхуков.
- `server/src/routes/api/admin-orders.js` — список, деталка, summary, смена статуса, доставка, сообщения.
- `server/src/routes/user-messages.js` — пользовательские сообщения заказа.
- `server/src/routes/user-cart.js` — корзина как источник checkout.
- `server/src/plugins/auth.js` — админская проверка только в части влияния на order API.
- `shared/constants/order-status.js` и `server/src/lib/order-status.js` — допустимые переходы статусов.

### Frontend

- `client/src/pages/admin-orders/` — список заказов, диалог деталки, summary.
- `client/src/features/order-detail/` — деталка заказа, статусы, доставка, чат, оплата.
- `client/src/pages/me/ui/sections/` — пользовательская деталка заказа, сообщения, действия по заказу.
- `client/src/entities/order/api/` — контракты клиентского API.
- `client/src/app/providers/SseProvider.tsx` — realtime-инвалидации.
- Order-related query keys и мутации React Query.

## Проверяемые инварианты

### Заказ и остатки

- Checkout не создает заказ при нехватке товара.
- Остатки списываются атомарно и не уходят в отрицательные значения.
- Если отмена заказа не возвращает остатки, это фиксируется в audit report как явное продуктовое решение или дефект.
- Корзина после успешного checkout очищается согласованно с созданным заказом.

### Доставка и цена

- Для доставки состояние `deliveryFeeLocked` соответствует возможности оплаты.
- Заказы, требующие подтверждения цены доставки, видны администратору в списке заказов и учитываются в summary, если summary заявлен как список задач к вниманию.
- Админ не переводит заказ в состояние, которое противоречит неподтвержденной доставке.

### Оплата

- Платеж нельзя создать для заказа, который еще не готов к оплате.
- Webhook и polling не создают дублирующих побочных эффектов.
- Переход в `PAID` идемпотентен и не ломает уведомления.
- Ручной перевод админом в `PAID` либо запрещен, либо явно обоснован и протестирован.

### Статусы

- Все переходы статусов проходят через единый источник правил.
- Frontend не дублирует серверную бизнес-логику переходов.
- Для delivery и pickup сценариев допустимые переходы не расходятся.
- Финальные статусы нельзя случайно изменить через admin API.

### UI и синхронизация

- Query keys деталки, списка, summary и SSE-инвалидаций согласованы.
- После мутаций админка и личный кабинет не показывают устаревший статус.
- Сообщения чата корректно отображают автора в пользовательской и админской деталке.
- Ошибки API отображаются понятным текстом и не скрываются за silent fail.

## Приоритизация находок

- **P0:** риск потери денег, некорректной оплаты, отрицательных остатков, доступа к чужим данным.
- **P1:** неверный статус заказа, сломанная админская операция, рассинхрон UI после успешного действия.
- **P2:** плохая диагностика ошибок, слабое покрытие тестами вокруг важного сценария.
- **P3:** локальный техдолг и рефакторинг без текущего пользовательского эффекта.

В первой реализации исправляются P0/P1 и небольшие P2, если они нужны для тестового закрепления. P3 фиксируются в отчете и не смешиваются с исправлениями.

## Артефакты

1. Audit report в формате списка находок с приоритетом, сценарием воспроизведения или кодовой причиной.
2. Набор точечных исправлений для подтвержденных P0/P1.
3. Тесты, которые фиксируют исправленное поведение.
4. Отдельный список рефакторингов и доработок на следующую итерацию.

## Тестирование и проверки

Минимальный набор проверок после исправлений:

- `server` → `npm test`
- `server` → `npm run lint`
- `server` → `npm run format:check`
- `client` → `npm run lint`
- `client` → `npm run format:check`

Дополнительно по затронутым изменениям:

- `client` → `npm test`
- `client` → `npm run build`
- ручной smoke-сценарий: checkout delivery, подтверждение доставки админом, оплата, смена статусов, обновление открытой деталки.

## Риски

- Аудит может найти больше проблем, чем стоит исправлять в одной итерации. Мера: исправлять только P0/P1, остальное переносить в отчет.
- Статусная модель может оказаться связана с UX-решениями, которые не очевидны из кода. Мера: спорные изменения фиксировать как предложение, а не вносить без подтвержденного инварианта.
- Сквозные тесты могут потребовать подготовки данных. Мера: начинать с route/unit/component тестов рядом с найденным дефектом.

## Критерии готовности

- Каждая исправленная проблема имеет тест или четкую проверку.
- Публичные роуты `/api/categories` и `/api/products` не меняются.
- FSD-границы фронтенда не нарушены.
- API ошибки для админских операций остаются понятными: 400/401/404/409.
- Все релевантные проверки из раздела тестирования пройдены или явно перечислены как не запущенные с причиной.