Аукционы для маркетплейса

Полноценная аукционная система, превращающая обычные объявления в торги. Продавец задаёт правила лота, покупатели соревнуются ставками, платформа автоматически определяет победителя, замораживает гарантийный депозит и проводит расчёты — от прямого контакта сторон до полного эскроу через платёжный шлюз.

Модуль рассчитан на марктеплейсы автомобилей, недвижимости, искусства, коллекционных предметов и любых ниш, где целесообразна динамическая цена вместо фиксированной.

---

Типы аукционов

English (классический) — открытые возрастающие ставки. Покупатели видят текущую цену и сумму каждой ставки, перебивают друг друга шагом не меньше минимального. По таймеру побеждает наибольшая ставка.

Sealed-bid (закрытый) — каждый участник может сделать только одну ставку, суммы скрыты от других до окончания торгов. По таймеру платформа открывает все ставки и определяет победителя — тот, кто предложил больше всех.

Dutch (голландский) — цена начинает с верхней и автоматически падает по расписанию (например, минус 5 000 ₽ каждые 30 секунд) до нижней границы. Первый, кто согласится с текущей ценой, забирает лот.

---

Режимы ставок

Ручная ставка — покупатель вводит сумму ≥ текущая цена + минимальный шаг.

Авто-ставка (proxy bid) — покупатель указывает свой потолок, платформа автоматически перебивает чужие ставки минимально допустимым шагом, пока ставки не превысят потолок. Несколько proxy-ставок соревнуются между собой в одной транзакции — побеждает тот, у кого выше потолок, по цене на один шаг выше второго потолка.

---

Защита от снайпинга

Если ставка приходит в последние N минут перед окончанием (по умолчанию 5), таймер автоматически продлевается на M минут (по умолчанию 5). Жёсткий потолок продления ограничивает суммарное удлинение торгов (по умолчанию 24 часа от изначального ends_at).

Все три параметра настраиваются индивидуально для каждой категории.

---

Резервная цена и купить-сейчас

Резерв — скрытый минимум, ниже которого лот не продаётся. Покупатели не видят его значение, но видят бейдж «Резерв достигнут / не достигнут». Если торги заканчиваются ниже резерва, лот переходит в статус ended_below_reserve без победителя.

Купить сейчас — фиксированная цена, по которой покупатель может закрыть торги мгновенно, пока никто ещё не сделал ставку. После первой ставки опция блокируется автоматически.

---

Гарантийный депозит (wallet holds)

При каждой ставке платформа замораживает определённый процент от суммы (deposit_percent, настраивается на категорию) на кошельке покупателя. Деньги не списываются — они блокируются как «hold», и пользователь не может потратить их на других аукционах или вывести.

Когда ставку перебивают — hold автоматически освобождается. По завершении торгов hold победителя либо захватывается (если settlement_mode=deposit или escrow), либо освобождается (settlement по контактам).

Это защищает от фейковых ставок: пользователь не сможет участвовать без реальных средств на балансе.

---

Расчёт между сторонами (settlement)

По контактам — платформа отправляет покупателю и продавцу системное сообщение в чат с просьбой связаться. Оплата и передача товара — между собой, вне платформы. Платформа списывает комиссию с продавца автоматически после завершения торгов.

Через депозит — если у покупателя на балансе заморожена полная сумма лота, она переводится продавцу в одну транзакцию. Покупатель получает уведомление о списании, продавец — о зачислении. Подходит для категорий с обязательной предоплатой.

Через эскроу — платформа создаёт payment intent, покупатель оплачивает через любой подключённый платёжный шлюз (YooKassa, CloudPayments, Stripe, Tinkoff и др.). Деньги хранятся на платформе до подтверждения сделки, потом выплачиваются продавцу за вычетом комиссии. Используется при крупных сделках, где нужна гарантия третьей стороны.

---

Споры

Каждая из сторон (покупатель или продавец) может открыть спор в течение 14 дней после завершения торгов. К спору прикладываются текстовое описание причины и до 10 фото-доказательств (загружаются через стандартный uploader платформы).

Администратор видит все споры в /admin/auctions/disputes, может взять в работу (reviewing) и принять решение:

• В пользу покупателя — hold освобождается, settlement помечается как refunded.
• В пользу продавца — деньги остаются у продавца, лот закрывается.
• Отменить спор — без финансовых последствий.

При решении в пользу покупателя автоматически разблокируется hold; при отказе — статус закрывается с обоснованием.

---

Realtime через SSE

Каждая страница лота открывает Server-Sent Events соединение на GET /{id}/events. Сервер пушит события bid_placed, price_changed (для голландских), sealed_revealed, dutch_step без необходимости опроса. Polling в 15 секунд оставлен как fallback на случай прокси, режущих SSE.

Для multi-replica деплоя SSE-события транслируются через Redis pub/sub канал auctions:events — клиент, подключённый к одной реплике, получит ставку, опубликованную на любой другой.

---

Платёжные вебхуки

Каждый платёжный шлюз дёргает endpoint POST /escrow/webhook/{gateway} после успешной/неуспешной оплаты. Поддерживаются основные форматы подписи:

• Stripe — заголовок Stripe-Signature: t=...,v1=... с 5-минутным окном защиты от replay
• CloudPayments — заголовок Content-HMAC (base64 HMAC-SHA256)
• Все остальные — общий формат X-Auctions-Signature: HMAC-SHA256(body) в hex

Секрет хранится в env-переменных AUCTIONS_WEBHOOK_SECRET_<gateway_slug> (отдельный на каждый шлюз) или общий AUCTIONS_WEBHOOK_SECRET для всех.

Вебхук идемпотентен — повторный вызов на уже подтверждённый платёж возвращает already_confirmed без побочных эффектов.

---

Уведомления

Платформа автоматически отправляет in-app уведомления на ключевые события:

• bid_placed — продавцу, когда на его лот пришла новая ставка
• outbid — покупателю, когда его ставку перебили
• ending_soon_5min / ending_soon_1h — всем участникам перед окончанием
• won / lost / no_winner — после завершения торгов
• dutch_price_drop — участникам, когда цена голландского аукциона упала на 5% и больше
• escrow_expired — покупателю, когда срок оплаты эскроу истёк (24 часа)

---

Аналитика для админа

Страница /admin/auctions/analytics показывает за выбранный период (7/30/90/365 дней):

• Всего лотов, активных, сумма выручки и комиссии
• Открытых споров, dispute rate (% от общего числа торгов)
• Success rate (% завершённых с победителем)
• Разбивка по категориям: количество лотов в каждом state, выручка, средняя финальная цена, споры

Данные обновляются по запросу — никаких background-aggregations, всё по факту.

---

Управление авто-ставками

Участник видит свои активные proxy-ставки в /dashboard/auctions/proxies: лот, потолок, текущая цена, бейдж «Лидируете / Перебили», таймер. Можно отменить любую — если пользователь сейчас не лидирует, hold освобождается; если лидирует, hold остаётся (защита текущей ставки).

---

Анонимность участников

Каждый участник в публичной истории ставок отображается как «Участник 1», «Участник 2» и т.д. — нумерация сквозная per-аукцион, реальный user_id не раскрывается. Один и тот же пользователь сохраняет свой номер на всём протяжении торгов.

Админ в /admin/auctions/{id} видит реальные user_id всех участников.

---

Политика создания лотов

Для каждой категории настраивается одна из политик:

• Свободно (free) — любой пользователь может создать аукцион сразу
• С модерацией (moderation) — лот попадает в статус pending_moderation, админ approve/reject
• Только админ (admin_only) — обычные пользователи не могут создавать, только админы

---

Настройки на категорию

В редакторе категории (/admin/categories → выбрать категорию) появляется блок «Аукционы» с полями:

• Типы разрешённых аукционов (English / Sealed / Dutch — можно несколько)
• Режимы ставок (manual / proxy)
• Режим расчёта (contacts / deposit / escrow)
• Депозит, %
• Комиссия платформы, %
• Политика создания
• Окно анти-снайпа (мин)
• Продление по анти-снайпу (мин)
• Жёсткий потолок продления (часы)
• Минимальный шаг ставки, %
• Длительность лота по умолчанию (часы)
• Разрешить продавцу отменять активный аукцион
• Разрешить отзыв ставки

---

Глобальные настройки модуля

В карточке модуля доступны общие дефолты, которые наследуются категориями при первом включении:

• Депозит / комиссия / шаг по умолчанию
• Анти-снайп параметры
• Длительность лота по умолчанию
• Срок оплаты эскроу (часы)
• Максимум активных лотов на пользователя
• Окно открытия спора (дней)

---

Интеграция с UI платформы

При включении модуля автоматически появляется:

• Каталог /auctions со списком активных торгов и сортировкой
• Блок «Аукционы» на главной странице (включается отдельно в /admin/design)
• AuctionBlock в правой sticky-панели на странице лота — текущая цена, таймер, форма ставки, история
• Карточка аукциона в каталоге выглядит как обычное объявление + footer с countdown и CTA «Сделать ставку»
• Кнопка «Открыть спор» появляется на завершённых лотах
• Панель «Оплатить эскроу» с выбором шлюза — для победителей в режиме эскроу

Когда модуль выключен или удалён — все эти элементы автоматически скрываются (страница /auctions отдаёт 404, блок на главной не рендерится, опция «Аукцион» исчезает из формы создания объявления).

---

API endpoints (краткая справка)

Публичные:

• GET /api/v1/ext/auctions/active — каталог
• GET /api/v1/ext/auctions/{id} — детали аукциона
• GET /api/v1/ext/auctions/{id}/bids — история ставок
• GET /api/v1/ext/auctions/{id}/events — SSE-стрим
• GET /api/v1/ext/auctions/listing/{listingId} — аукцион по объявлению

Покупатель:

• POST /api/v1/ext/auctions/{id}/bids — сделать ставку (manual или proxy)
• POST /api/v1/ext/auctions/{id}/buy-now — купить сейчас
• POST /api/v1/ext/auctions/{id}/dispute — открыть спор
• GET /api/v1/ext/auctions/my/bids — мои ставки
• GET /api/v1/ext/auctions/my/proxies — мои авто-ставки
• POST /api/v1/ext/auctions/{id}/proxy/cancel — отменить авто-ставку
• GET /api/v1/ext/auctions/my/escrow — мои эскроу-платежи
• GET /api/v1/ext/auctions/escrow/gateways — список шлюзов
• POST /api/v1/ext/auctions/escrow/{intentId}/start — начать оплату

Продавец:

• POST /api/v1/ext/auctions/ — создать аукцион
• PATCH /api/v1/ext/auctions/{id} — изменить параметры (до старта)
• POST /api/v1/ext/auctions/{id}/cancel — отменить
• GET /api/v1/ext/auctions/my/owned — мои аукционы

Админ:

• GET /api/v1/ext/auctions/admin/list — все аукционы с фильтрами
• GET /api/v1/ext/auctions/admin/{id} — детали
• POST /api/v1/ext/auctions/admin/{id}/force-end — принудительно закрыть
• POST /api/v1/ext/auctions/admin/{id}/approve|reject — модерация
• GET /api/v1/ext/auctions/admin/disputes — список споров
• POST /api/v1/ext/auctions/admin/disputes/{id}/resolve — закрыть спор
• GET /api/v1/ext/auctions/admin/analytics?days=N — аналитика
• POST /api/v1/ext/auctions/admin/escrow/{id}/confirm — ручное подтверждение оплаты

Webhooks:

• POST /api/v1/ext/auctions/escrow/webhook/{gateway} — приём вебхуков от платёжных шлюзов

---

Совместимость и ограничения

• Минимальная версия CMS: 0.1.0
• Требует включенный модуль кошелька (wallet) для работы holds и settlement
• Для эскроу нужен хотя бы один установленный платёжный шлюз
• SSE через Redis работает только если REDIS_HOST сконфигурирован (на тех же env-переменных, что и host CMS)
• Анонимные псевдонимы участников (Участник N) сохраняются после публикации в БД — переименование требует SQL UPDATE