admin/shop-server

Fork 0

Files

T

Kirill f34c05095a ываыв

2026-05-28 21:46:17 +05:00

11 KiB

Raw Blame History

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

Дата: 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.

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

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 фиксируются в отчете и не смешиваются с исправлениями.

Артефакты

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

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

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

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.
Все релевантные проверки из раздела тестирования пройдены или явно перечислены как не запущенные с причиной.

11 KiB Raw Blame History Unescape Escape