Detailed Component Design

Вставь ниже в Detailed Component Design. Это закрывает три наиболее важных и рискованных части: атомарное выделение места, бронирование с оплатой и обработку въезда/выезда.[codemia]

1. Slot Allocation Service

Цель: гарантированно выбрать и занять подходящее место без double-booking при конкурентных запросах.

Data structures

Для каждого lot_id хранить состояние в одном Redis shard:

text

slot:{lot_id}:{slot_id} -> {
  status: AVAILABLE | HELD | RESERVED | OCCUPIED,
  type: COMPACT | REGULAR | LARGE | HANDICAP,
  zone_id,
  priority_score,
  reservation_id?,
  ticket_id?,
  expires_at?
}

available:{lot_id}:{vehicle_type} -> Redis Sorted Set
score = priority_score
member = slot_id

Sorted Set позволяет получить ближайший/приоритетный свободный слот через ZRANGE ... 0 0. Например, для обычного автомобиля сначала выбираем REGULAR, затем LARGE; для disabled-user — только HANDICAP.

Atomic allocation algorithm

Все действия выполняются одним Lua script на Redis primary для shard-а данного lot_id:

Находит первый кандидат в available:{lot_id}:{vehicle_type}.
Проверяет, что слот всё ещё AVAILABLE.
Удаляет слот из Sorted Set.
Меняет статус на HELD или OCCUPIED.
Сохраняет reservation_id/ticket_id.
Для HELD устанавливает TTL, например 10 минут.
Возвращает slot_id.

Поскольку Lua script исполняется атомарно и Redis обрабатывает команды последовательно, два клиента не смогут получить один слот. Redis lock здесь не нужен: он добавил бы время ожидания и риск stale lock.

Scaling and trade-offs

Шардирование по lot_id: все слоты одной парковки находятся в одном shard, поэтому атомарное выделение не требует distributed transaction.
API/Allocation Service stateless и масштабируется горизонтально; Redis shard масштабируется добавлением парковок/shard-ов.
Операция allocation имеет сложность O(log⁡N)O(\log N)O(logN) из-за ZADD/ZREM/ZRANGE, где NNN — число слотов нужного типа; при тысячах слотов latency остаётся низкой.
Redis обеспечивает быстрый operational state, но не должен быть единственным durable хранилищем: после изменения состояния публикуется event, а ticket/reservation пишется в PostgreSQL через outbox.
Минус подхода: строгая консистентность ограничена границей одного lot_id. Это приемлемо, поскольку один слот не принадлежит нескольким парковкам.

Failure handling

Если пользователь не оплатил бронь, TTL истекает; background worker или Redis keyspace event возвращает слот из HELD в AVAILABLE и снова добавляет его в Sorted Set.
После Redis failover клиент повторяет команду с тем же idempotency_key; сохранённый результат предотвращает повторное выделение.
Если запись в PostgreSQL временно недоступна, событие лежит в outbox/очереди и ретраится; статус слота не теряется благодаря Redis replication и persistence.[codemia]

2. Reservation and Payment Saga

Цель: превратить временный hold в подтверждённую бронь только после фактической оплаты, без распределённой транзакции между Redis, PostgreSQL и PSP.

State machine

text

PENDING_PAYMENT
  -> CONFIRMED       (PaymentSucceeded)
  -> PAYMENT_FAILED  (PaymentFailed)
  -> EXPIRED         (hold TTL expired)
  -> CANCELLED       (user cancellation)

CONFIRMED
  -> CHECKED_IN
  -> NO_SHOW         (grace period expired)
  -> CANCELLED

CHECKED_IN
  -> COMPLETED       (vehicle exit)

Flow

POST /reservations/hold вызывает Slot Allocation Service. Тот атомарно переводит слот AVAILABLE -> HELD и создаёт TTL, например 10 минут.
Reservation Service создаёт в PostgreSQL reservation со статусом PENDING_PAYMENT, а Payment Service создаёт payment_intent у PSP.
Клиент оплачивает через hosted payment page/SDK PSP. Номер карты не проходит через backend, что уменьшает PCI scope.
PSP вызывает POST /payments/webhooks/psp; Payment Service проверяет подпись webhook, payment_intent_id, сумму, currency и уникальность provider_event_id.
Payment Service сохраняет статус платежа и через transactional outbox публикует PaymentSucceeded(reservation_id).
Reservation Service получает событие, идемпотентно переводит бронь PENDING_PAYMENT -> CONFIRMED, а слот HELD -> RESERVED; после этого создаётся QR/token для въезда.
При PaymentFailed, отмене или expiry Reservation Service освобождает слот и при необходимости инициирует refund.

Reliability and trade-offs

Это Saga/eventual consistency между payment и reservation, но пользователь видит бронь как confirmed только после PaymentSucceeded; следовательно, оплаченная бронь не может быть подтверждена дважды.
Webhook может прийти несколько раз или раньше ответа клиенту. Дедупликация по provider_event_id и идемпотентный consumer делают повтор безопасным.
Transactional outbox предотвращает сценарий «статус платежа сохранён, но событие не опубликовано»; retry и DLQ обрабатывают временные сбои consumer’ов.
Компенсирующие операции вместо distributed transaction: release hold при неуспехе и refund, если отмена наступила после успешной оплаты.
Главный trade-off — небольшая задержка между оплатой и статусом CONFIRMED, зато нет хрупкой двухфазной транзакции с внешним PSP.[codemia]

3. Gate Entry/Exit Controller

Цель: поддерживать быстрый въезд/выезд и продолжать работу при временной потере связи с центральным backend.

Online entry

Камера LPR или QR scanner передаёт license_plate либо QR token в локальный Gate Controller.
Controller вызывает POST /parking-lots/{lot_id}/entry с idempotency_key, уникальным для попытки проезда.
Parking Service валидирует reservation/ticket, проверяет временное окно, атомарно переводит слот RESERVED -> OCCUPIED, создаёт ticket и возвращает gate_open=true.
Controller получает разрешение, открывает шлагбаум и сохраняет локальный event с временем, номером автомобиля и ticket_id.

Exit and charging

Gate Controller отправляет POST /parking-lots/{lot_id}/exit.
Parking Service находит активный ticket, рассчитывает стоимость как tariff(ticket, entry_time, exit_time), проверяет результат оплаты и только затем переводит слот OCCUPIED -> AVAILABLE.
После успешного освобождения слот снова добавляется в Redis Sorted Set для соответствующего vehicle type; сервис публикует VehicleExited для истории, аналитики и receipt.
Контроллер открывает шлагбаум только при exit_granted=true; повторные сообщения не освобождают слот второй раз благодаря ticket_id и idempotency_key.

Offline mode and scaling

Каждый Gate Controller хранит локальный encrypted cache недавно подтверждённых reservation QR-token и whitelist активных абонементов с коротким TTL.
При потере связи контроллер разрешает въезд только для валидного закешированного reservation или подписки; для неизвестной машины может выпустить локальный временный ticket согласно policy парковки.
Все offline events попадают в durable local queue и после восстановления сети отправляются в backend с уникальным event_id; backend дедуплицирует их.
Это осознанный trade-off: offline режим повышает availability, но при сетевом разделении возможна краткая задержка глобального отображения occupancy. Конфликтов избегают тем, что offline controller управляет только своей парковкой и отправляет события строго в порядке sequence number.[codemia]

Submissions

Displaying Solutions with Scores Ranging from 1 to 10

Submissions

Displaying Solutions with Scores Ranging from 1 to 10