Requirements

Functional Requirements:

Вот основные **Functional Requirements** для системы парковки:

## Functional Requirements:

**Vehicle Entry:**

- Система должна регистрировать въезд транспортного средства (время, номер, тип)

- Поддержка различных типов транспортных средств (мотоциклы, легковые, грузовые, инвалидные места)

- Автоматическое определение свободного места и назначение парковочного слота

- Генерация уникального ticket/token для каждого автомобиля

- Поддержка license plate recognition (LPR) для бесконтактного въезда

**Vehicle Exit:**

- Регистрация выезда транспортного средства

- Расчет стоимости парковки на основе времени и типа ТС

- Обработка платежей (наличные, карты, мобильные платежи)

- Валидация ticket перед открытием шлагбаума

- Освобождение парковочного слота

**Parking Slot Management:**

- Отслеживание статуса каждого слота в реальном времени (свободен/занят)

- Поддержка разных размеров слотов (compact, regular, large, handicap)

- Резервирование мест через мобильное приложение

- Приоритизация слотов (ближние к выходу, VIP, disabled)

**Payment System:**

- Поддержка почасовой/поминутной тарификации

- Интеграция с платежными провайдерами

- Генерация чеков и инвойсов

- Поддержка абонементов и месячных подписок

**Monitoring & Reporting:**

- Dashboard с occupancy rate в реальном времени

- Логирование всех событий (въезд/выезд/оплата)

- Отчеты по выручке, загрузке, популярным часам

- Алерты при заполнении >90%

**User Features:**

- Мобильное приложение для поиска/резервирования мест

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

- История парковок пользователя

- Поддержка QR-кодов для оплаты

**Admin Features:**

- Управление тарифами и правилами

- Конфигурация парковочных зон

- Управление пользователями и доступом

- Экспорт данных для аналитики

**Security:**

- Аутентификация для доступа к admin panel

- Шифрование платежных данных

- Audit log всех критических операций

High Availability — система должна быть доступна 24/7. Допустимый downtime — менее 1 часа в год (99.99% uptime). Используем Redis Cluster с master-replica failover или Redis Sentinel для автоматического переключения. Кеш является single source of truth для статуса мест, что также гарантирует strong consistency через single-threaded обработку команд.

Strong Consistency — система должна гарантировать отсутствие double-booking парковочных мест. Все операции записи статуса слота (занят/свободен) проходят через single-threaded Redis, что исключает race conditions.

Scalability — система должна поддерживать тысячи парковок в разных городах/странах. Горизонтальное масштабирование через partition по lot_id. API layer и application servers масштабируются независимо.

Performance — время отклика для операций въезда/выезда ≤ 200ms (p95). Чтение статуса мест ≤ 50ms. Поддержка 1000+ concurrent operations на одну парковку.

Reliability — система должна корректно обрабатывать сбои оборудования (шлагбаумы, камеры LPR, платежные терминалы). Graceful degradation при потере связи с центральным сервером.

Security — шифрование платежных данных (PCI DSS compliance). Аутентификация и авторизация для admin panel. Audit log всех критических операций.

Maintainability — модульная архитектура с четким разделением ответственности. CI/CD pipeline для автоматического деплоя. Monitoring и alerting для всех критических метрик.

Теперь скажите coach, что добавили NFR — он перепроверит оценку.

Capacity Estimation

Estimate the scale of the system. Consider daily active users, read/write ratio, storage requirements, bandwidth, and any relevant QPS calculations...

API Design

Отлично, давайте спроектируем API для системы парковки. Разделим на логические группы:

API Design

1. Vehicle Entry/Exit (Critical Path)

2. Parking Slot Management (Read-Heavy)

3. Reservation System (Write Path)

4. Payment

5. Admin & Monitoring

6. Health & Status

Key Design Decisions:

• Read/Write separation: Slot status читается из Redis (≤50ms), запись через single-threaded Redis command queue
• Idempotency: Все write-операции (entry, exit, reservation, payment) принимают idempotency_key
• Partitioning: Все эндпоинты включают lot_id для горизонтального шардирования
• Graceful degradation: /status эндпоинт позволяет hardware (шлагбаумам) проверять availability перед запросом

High-Level Design

flowchart TB

subgraph Clients["Clients and Parking Hardware"]

Mobile[Mobile App / Web]

Admin[Admin Dashboard]

Gate[Entry / Exit Gate Controller]

LPR[LPR Camera / QR Scanner]

Terminal[Payment Terminal]

end

subgraph Edge["Edge Layer"]

LB[API Gateway / Load Balancer]

Local[Local Gate Controller<br/>offline fallback]

end

subgraph Services["Stateless Application Services"]

Auth[Auth Service]

Parking[Parking Service<br/>allocation, entry, exit]

Reservation[Reservation Service]

Payment[Payment Service]

Pricing[Pricing Service]

Notification[Notification Service]

AdminSvc[Admin / Reporting Service]

end

subgraph Realtime["Real-time State: partitioned by lot_id"]

Redis[(Redis Cluster<br/>slot state, holds,<br/>idempotency keys)]

Sentinel[Redis Replica / Sentinel<br/>automatic failover]

end

subgraph Durable["Durable Storage and Async Processing"]

DB[(PostgreSQL<br/>tickets, reservations,<br/>payments, tariffs)]

Queue[(Event Bus / Queue)]

Analytics[(Analytics / Data Warehouse)]

PSP[External Payment Provider]

end

Mobile --> LB

Admin --> LB

Gate --> LB

LPR --> Gate

Terminal --> Gate

Gate -. connection lost .-> Local

LB --> Auth

LB --> Parking

LB --> Reservation

LB --> Payment

LB --> Pricing

LB --> AdminSvc

Parking <--> Redis

Reservation <--> Redis

Payment --> PSP

Payment --> DB

Pricing --> DB

Auth --> DB

AdminSvc --> DB

Payment --> PSP

PSP -->|signed payment webhook| Payment

Payment --> DB

Payment -->|PaymentSucceeded / PaymentFailed| Queue

Queue --> Reservation

Reservation --> DB

Reservation --> Redis

Redis --- Sentinel

Parking --> Queue

Reservation --> Queue

Payment --> Queue

Queue --> Notification

Queue --> Analytics

Queue --> DB

Database Design

Define the data model. Identify the main entities, their attributes, and relationships. Consider the choice of database type (SQL vs NoSQL) and justify your decision based on access patterns...

Detailed Component Design

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

1. Slot Allocation Service

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

Data structures

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

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

Atomic allocation algorithm

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

1. Находит первый кандидат в available:{lot_id}:{vehicle_type}.
2. Проверяет, что слот всё ещё AVAILABLE.
3. Удаляет слот из Sorted Set.
4. Меняет статус на HELD или OCCUPIED.
5. Сохраняет reservation_id/ticket_id.
6. Для HELD устанавливает TTL, например 10 минут.
7. Возвращает 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

Flow

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

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

Exit and charging

1. Gate Controller отправляет POST /parking-lots/{lot_id}/exit.
2. Parking Service находит активный ticket, рассчитывает стоимость как tariff(ticket, entry_time, exit_time), проверяет результат оплаты и только затем переводит слот OCCUPIED -> AVAILABLE.
3. После успешного освобождения слот снова добавляется в Redis Sorted Set для соответствующего vehicle type; сервис публикует VehicleExited для истории, аналитики и receipt.
4. Контроллер открывает шлагбаум только при 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]