Kirill
139 lines
11 KiB
Markdown
139 lines
11 KiB
Markdown
# Дизайн: аудит заказов, оплаты и админки заказов
|
||
|
||
**Дата:** 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.
|
||
- Все релевантные проверки из раздела тестирования пройдены или явно перечислены как не запущенные с причиной.
|