RealEstateApp

Контекст тестового задания

Тестовое задание реализовано как backend-модуль для мобильного приложения недвижимости. Основной поток: пользователь выбирает жилой комплекс, просматривает квартиры, открывает карточку квартиры и отправляет заявку на консультацию, бронирование или покупку с последующей передачей в CRM.

Каталог объектов

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

Заявки клиентов

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

CRM интеграция

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

20 уточняющих вопросов к заказчику перед стартом разработки.

11 шагов в предполагаемой логике работы пользовательского потока.

12 сценариев использования, включая позитивные и негативные.

8 блоков анализа, полностью закрывающих требования тестового задания.

1. Уточняющие вопросы к заказчику

До начала реализации важно зафиксировать бизнес-границы модуля, правила работы заявки и ожидания от интеграции с CRM.

Продукт и роли

Кто является пользователем модуля: анонимный клиент, авторизованный клиент или оба варианта?
Какие типы заявок обязательны в первой версии: консультация, бронь, покупка, ипотека, просмотр?
В чем бизнес-разница между заявкой на покупку и заявкой на бронирование?
Нужно ли полностью запрещать заявки для проданных квартир?
Можно ли принимать заявки по забронированным квартирам?

Жизненный цикл заявки

Допустимы ли несколько активных заявок по одной квартире от одного клиента?
Что считается успешной обработкой заявки: локальное сохранение, постановка в очередь или подтверждение CRM?
Интеграция с CRM синхронная или асинхронная?
Что делать, если CRM временно недоступна?
Нужны ли уведомления клиенту после создания заявки?

Данные и валидация

Нужна ли история изменения статусов заявки?
Какие поля являются обязательными: имя, телефон, email, комментарий, способ связи?
Нужна ли отдельная валидация номера телефона по стране?
Нужно ли хранить источник лида: iOS, Android, web, рекламный канал?
Есть ли SLA на обработку заявки менеджером?

Ограничения и сопровождение

Должна ли бронь иметь срок истечения?
Нужно ли фиксировать согласие на обработку персональных данных?
Нужна ли мультиязычность API и текстов ошибок?
Должна ли система поддерживать роли сотрудников или админ-панель?
Какие есть требования по аудиту, логированию и отказоустойчивости?

2. Предполагаемая логика работы модуля

Пользователь получает список жилых комплексов.
Выбирает жилой комплекс и фильтрует квартиры по параметрам.
Открывает карточку квартиры.
Система показывает атрибуты квартиры и доступные действия.
Пользователь заполняет форму заявки.
API валидирует поля запроса.
API проверяет бизнес-ограничения с учетом статуса квартиры.
Если передан тот же Idempotency-Key, система возвращает уже созданную заявку без дубля.
Если проверка успешна, заявка сохраняется в БД со стартовым статусом queued_for_sync.
Далее заявка отправляется во внешнюю CRM.
После ответа интеграции статус заявки обновляется.

3. Пользовательские сценарии

Основные сценарии

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

Негативные сценарии

Попытка создать заявку по проданной квартире.
Попытка забронировать квартиру, которая уже не available.
Повторная отправка того же запроса с тем же Idempotency-Key.
Отправка формы с невалидными данными.
Ошибка передачи данных во внешнюю CRM.

4. Бизнес-ограничения и исключительные ситуации

Ограничения

Для квартиры со статусом sold создание целевых заявок недоступно.
Заявка типа reservation разрешена только для квартир со статусом available.
Заявка типа purchase для квартиры со статусом reserved может требовать подтверждения менеджера.
Одна и та же заявка не должна создаваться повторно при сетевых ретраях клиента.

Исключительные ситуации

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

5. Возможные риски реализации

Гонки данных: квартира была доступна на момент просмотра, но изменила статус к моменту отправки заявки.
Дубли заявок из-за повторных отправок с мобильного клиента.
Потеря лидов при сбоях интеграции с CRM.
Рассинхронизация статусов между локальной системой и CRM.
Недостаточно формализованные бизнес-правила по типам заявок.
Слабая валидация контактов, ухудшающая качество лидов.
Усложнение логики при добавлении новых каналов и типов заявок.
Юридические риски по персональным данным и согласию пользователя.
Нехватка аудита по смене статусов и ручным действиям менеджеров.
Непрозрачные ошибки API для мобильного приложения.

6. Архитектурный подход

API-слой

REST + Request Validation

Endpoints для ЖК, квартир и заявок, request-валидаторы для входных данных и API resources для единообразного JSON-ответа.

Доменный слой

ResidentialComplex / Apartment / ApartmentRequest

Основные сущности предметной области и enum-ы для типов и статусов, чтобы бизнес-логика оставалась явной и управляемой.

Бизнес-логика

Сервисы и правила

Сервис создания заявки, определение доступных действий по квартире и идемпотентность на уровне сервиса и базы данных.

Интеграция

CRM Adapter / Gateway

Выделенный интеграционный слой для внешней CRM, чтобы изолировать transport logic и упростить доработки.

Надежность

Очереди и ретраи

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

Текущее состояние

Основа уже есть в проекте

В кодовой базе уже присутствуют модели, enum-ы, endpoint создания заявки, Swagger и feature-тесты пользовательского потока.

В проекте уже реализованы маршруты GET /api/v1/residential-complexes, GET /api/v1/residential-complexes/{id}, GET /api/v1/residential-complexes/{id}/apartments, GET /api/v1/apartments/{id} и POST /api/v1/apartments/{id}/requests. Swagger UI по-прежнему остается удобной точкой входа для проверки контракта API.

7. Структура данных

`residential_complexes`

id
name
slug
city
address
description
external_id
gallery

`apartments`

id
residential_complex_id
unit_number
rooms
floor
total_floors
area_sqm
price
currency
status
layout_image_url
finishing
orientation
features
description
booking_expires_at
external_system
external_id

`apartment_requests`

id
apartment_id
type
status
customer_name
phone
email
comment
preferred_contact_method
source_channel
idempotency_key
external_system
external_reference
integration_payload
submitted_at
created_at
updated_at

Дополнительно рекомендовано

таблица истории смены статусов заявки;
журнал попыток синхронизации с CRM;
поля согласия на обработку персональных данных;
привязка ответственного менеджера, если это требуется бизнесом.

8. Обоснование принятых решений

ApartmentRequest вынесена в отдельную сущность, потому что заявка имеет собственный жизненный цикл и статусную модель.
Идемпотентность обязательна, так как мобильный клиент может повторно отправить один и тот же запрос.
Локальное сохранение заявки до синхронизации с CRM снижает риск потери лида при сбоях внешней системы.
Использование enum-ов делает бизнес-правила более явными и уменьшает вероятность неконсистентных состояний.
Разделение API, доменной логики и интеграционного слоя упрощает поддержку и развитие решения.
Бизнес-проверки на стороне backend обязательны, потому что нельзя полагаться только на ограничения в мобильном интерфейсе.
Хранение source_channel полезно для аналитики и оценки качества каналов привлечения.
История статусов и журнал интеграции важны для поддержки, аудита и разбора инцидентов.

API для каталога недвижимости и заявок по квартирам