spectaxi

Базовая концепция продукта SpexTaxi (MVP)

1) Позиционирование продукта

SpexTaxi — мобильный маркетплейс для поиска и заказа спецтехники.

Платформа поддерживает три пользовательских сценария в рамках одной учетной записи:

• частный клиент с разовыми заказами;
• регулярный бизнес-клиент (без обязательной сущности компании в MVP);
• владелец/водитель спецтехники как исполнитель.

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

2) Принципы MVP

• Не проектировать продукт как только B2B.
• Не проектировать продукт как только B2C.
• Не делать оплату в приложении обязательной для всех заказов.
• Разрешать прямую коммуникацию и прямую оплату между пользователями.
• Создавать ценность за счет скорости поиска, качества матчинга, карты, актуальности статусов, уведомлений и истории заказов.
• Считать обход платформы бизнес-риском, но не решать его жесткими техническими запретами.

3) Ключевые пользовательские сценарии

Полные шаги — в USER_SCENARIOS.md. Кратко:

Поиск и запрос (клиент)

Фильтр: тип, тариф (набор зависит от типа транспорта — часы/смены/месяцы или километры/рейсы), количество, срочный (без даты) или плановый (дата и время начала, справочно для исполнителя), точка, опционально потолок цены. Список ближайших машин, карта с кластерами. Цена на карточке = ставка × количество. Календаря занятости нет: по срочным показываются только исполнители с включённым флагом «принимаю срочные заказы». Контакты после «принять запрос». Один ожидающий запрос на заказ. Черновик можно сохранить без отправки. Подробности — SEARCH_ALGORITHM.md.

Парк, тарифы и статус (исполнитель)

Тарифы на единицу из списка категории. Тип транспорта — строка machinery_categories (code, категория прав, текст UI). Лицензия — одна на категорию, без approve админа машина не в поиске. Флаг «принимаю срочные заказы» — ручной чекбокс в профиле. Подписка исполнителя спрятана под executor_subscription_enabled.

Отклик, переговоры, работа

«Принять запрос» открывает контакты (срок подтверждения условий — 1 сутки). «Подтвердить условия» фиксирует посчитанную сумму. Сделка → оплата 1 сутки, иначе возврат в поиск; прямая → сразу работа. Пока не in_progress, срыв матча возвращает заказ к поиску; полную отмену делает только клиент, исполнитель только отклоняет партнёра. Из in_progress отмена только спором (исключение — плановый до даты начала); completed когда обе стороны подтвердили исполнение. Заказ без найденного исполнителя система снимает сама (срочный — 24 ч без действий клиента, плановый — дата начала).

4) Границы домена в MVP

Входит в MVP

• Профили: после OTP имя и current_mode; UI от текущего режима.
• Контакты: Telegram, WhatsApp, MAX и телефон всегда на форме; достаточно одного канала плюс имя.
• Аватар исполнителя, парк, тарифы, лицензия категории через админку.
• Поиск по фильтру заказа (SEARCH_ALGORITHM.md), черновики заказов.
• Запрос одному; 5 минут (в т.ч. плановый); не ответил = отказ, скрыт; спор; отзывы 1–5 звёзд.
• Цена = тариф × количество; assigned нет.
• in_progress до подтверждения обеими или спора; отмена начатой работы только спором (плановый до даты начала — отмена с причиной).
• Безопасная сделка опционально; холд только после реальной оплаты.
• Подписка исполнителя под флагом executor_subscription_enabled (в MVP выключен).
• Админка: споры, лицензии, блокировки, отмена заказа, разбор причин other (SERVICE_RULES.md, API_CONTRACT_MVP.md раздел 9).
• Плановый заказ (дата и время начала; занятость по календарю не считается; до даты начала — отмена с причиной, после — только спор).
• Выбор «безопасная сделка» — переключатель на экране отправки запроса, только при включённом флаге.

Не обязательно для MVP

• Обязательная «Безопасная сделка» для каждого заказа.
• Внутренний кошелек с учетом реальных денег в PostgreSQL.
• Хранение банковских карт на стороне платформы.
• Полная корпоративная модель (Company, CompanyMember, CompanyProject) до подтвержденной потребности.
• Массовая рассылка одного запроса нескольким исполнителям сразу.
• Запрос своей собственной технике.

5) Требования к модели заказа

Каждый заказ должен поддерживать два режима расчета:

• direct_payment — условия и оплата согласуются напрямую между сторонами;
• secure_deal — опциональная оплата через платежного провайдера.

Каталожные тарифы живут на единице транспорта и задаются исполнителем. Типы: час, смена, сутки, месяц, рейс, километр — какие доступны, зависит от категории (TARIFF_TYPES.md).

Стоимость заказа считает система: ставка выбранного тарифа машины × количество. Заказчик сумму не вводит. Исполнитель подтверждает эти условия отдельной кнопкой после первого «принять» (1 сутки).

Запрос на ожидании ответа — только одному исполнителю. Клиент может снять его до принятия/отказа и выбрать другого. Исполнитель, который отказал или не ответил 5 минут, по этому заказу в выдаче не показывается.

6) Требования к платежной архитектуре

Оплата через приложение не является обязательной для MVP, но архитектура должна быть готова к интеграции платежей.

Нужен абстрактный платежный слой:

• интерфейс PaymentProvider (адаптер провайдера);
• сервис PaymentService (прикладные сценарии);
• обработчик платежных вебхуков и событий;
• синхронизация платежных статусов.

Функции, которые должны поддерживаться архитектурно:

• создание платежа;
• резервирование/холд;
• списание/подтверждение;
• отмена;
• возврат;
• выплата исполнителю;
• комиссия платформы;
• статусы «Безопасной сделки».

Источник истины по реальным денежным средствам — внешний платежный провайдер, а не баланс в базе данных.

После captured платформа деньги больше не двигает (админ — только санкции).

7) «Безопасная сделка» как опциональный модуль

«Безопасная сделка» включается по выбору клиента и не должна быть обязательной по умолчанию.

Целевой поток:

1. клиент выбирает безопасную сделку;
2. исполнитель подтверждает условия (посчитанная сумма);
3. awaiting_payment, форма оплаты, 1 сутки;
4. провайдер холдит после оплаты клиентом; успех → in_progress;
5. обе стороны подтверждают исполнение → выплата;
6. спор до выплаты — деньги по решению админа; после выплаты — только санкции;
7. expires_at провайдера → disputed только если холд уже был (authorized);
8. одна апелляция на тот же спор;
9. комиссия платформы.

Если клиент не создал платёж — провайдер ничего не возвращает; наш таймаут возвращает заказ в поиск исполнителя.

Правка деталей на awaiting_payment — вернуть/отменить платёж, снова переговоры.

7.1) Подписка исполнителя (executor_subscription_enabled)

В MVP флаг выключен.

Когда включён — без активной подписки исполнитель не в поиске и не принимает заказы.

Автоактивация после оплаты (целевой вариант под флагом): отдельный платёж (не холд заказа), webhook → active + срок, по истечении expired и скрытие из поиска. Нужны: продукт подписки в ЮKassa, POST /executor/subscription/pay, идемпотентный webhook, джоба expiry.

Через админку: админ ставит active / срок вручную (оплата вне приложения или без оплаты). Нужны: экран очереди, аудит. Медленнее, зато без рекуррента.

Лицензии подтверждает админ отдельно, не смешивать с оплатой подписки.

Модуль должен быть изолирован так, чтобы MVP можно было запустить без него и безопасно подключить позже.

8) Правила назначения

На ожидании первого ответа — один исполнитель. Не ответил за 5 минут = отказ, повторно на этот заказ нельзя.

Первое «принять» открывает контакты. Если принят срочный заказ — остальные ожидающие срочные запросы этого исполнителя закрываются автоотказом, клиенты получают уведомление, их заказы остаются в поиске; плановые запросы висят до ответа. «Подтвердить условия» (1 сутки) → direct_payment сразу in_progress, secure_deal → awaiting_payment → холд → in_progress. completed — когда обе стороны подтвердили исполнение. На этом заказе после начала работы нового поиска нет.

Минимальные технические гарантии:

• конечный автомат заказа;
• не более одного ожидающего ответа кандидата на заказ;
• идемпотентный API принятия;
• гонка «принять» vs истечение 5 минут разрешается атомарно; автоотказ остальных срочных — в той же транзакции;
• запись об отказе, автоотказе и таймауте запрещает повторный запрос этому исполнителю на этот заказ.

9) Рекомендуемые сущности MVP

• User, ExecutorProfile, ExecutorLicense
• MachineryUnit, MachineryPhoto, MachineryPricingRule, MachineryCategory, PricingType, CategoryPricingType
• Order, OrderPricing, OrderCandidate, OrderAssignment, OrderStatusEvent, ContactExchangeEvent
• Dispute, DisputeMessage, Review, RatingEvent, Notification
• PaymentRecord, PaymentWebhookEvent

Сущности позже:

• Company, CompanyMember, CompanyProject

10) Черновые модели статусов

Статус заказа

• draft — сохранён без запроса
• published — поиск исполнителя (в том числе после срыва матча до работы)
• in_negotiation — контакты, правки, «подтвердить условия»
• awaiting_payment — ждём холд (secure_deal)
• in_progress — работа, пока обе не подтвердят исполнение или спор
• completed — обе подтвердили
• disputed — спор
• cancelled — отмена клиентом до работы, отмена планового до даты начала, «исполнитель не найден», отмена админом или исход спора

Статус платежа (только для secure_deal)

• not_required
• pending
• authorized
• captured
• failed
• cancelled
• refunded

11) Модели монетизации для проверки

Нужно проверить минимум три варианта:

1. подписка для исполнителей;
2. комиссия с «Безопасной сделки»;
3. гибридная модель.

В MVP можно стартовать с подписки (или бесплатного периода), а «Безопасную сделку» подключить после подтверждения базовой гипотезы и юридической модели.

12) Отдельный трек исследования для России

Перед запуском «Безопасной сделки» отдельно проверить:

• какие провайдеры в РФ поддерживают marketplace/split-сценарии;
• юридическую модель движения средств и комиссии;
• требования KYC/KYB и роли участников;
• ответственность по спорам и возвратам;
• налоговые и бухгалтерские последствия выбранной схемы;
• срок жизни холда. Работа по тарифу month или большому количеству day длится дольше стандартного холда провайдера; по текущей модели истечение холда переводит заказ в disputed. Нужно выяснить, позволяет ли ЮKassa задавать срок холда под заказ. До ответа ограничений по тарифу не вводим; если нельзя — варианты: ограничить безопасную сделку короткими заказами или перейти к списанию при старте работы (эскроу, другая юридическая модель).

13) Рекомендуемый поэтапный запуск

Этап 1 (быстрая проверка гипотезы):

• вход, контакты пользователя, аватар и парк исполнителя;
• поиск исполнителей (карта/список), запрос одному, таймер 5 минут, переговоры, завершение;
• спор (тред в приложении, закрытие в админке);
• внутренние рейтинги без UI;
• прямой контакт и прямая оплата вне приложения;
• плановый заказ.

Этап 2:

• опциональная «Безопасная сделка» через провайдера (выплата исполнителю после действия клиента на completed);
• запуск комиссии платформы.

Этап 3:

• B2B-надстройки только при подтвержденной потребности.

14) Непересматриваемые архитектурные ограничения

• Один аккаунт может быть и клиентом, и исполнителем. Роль в UI — current_mode.
• У одного исполнителя неограниченное число единиц техники.
• Каталожные тарифы задаёт исполнитель и они принадлежат единице транспорта.
• Запрос на ожидании ответа — только одному исполнителю на заказ.
• После отказа, автоотказа и таймаута 5 минут исполнитель не запрашивается повторно на этот заказ.
• Календаря занятости нет; доступность по срочным заказам — только ручной флаг исполнителя.
• Свою технику заказать нельзя.
• После начала работы поиск исполнителей на том же заказе не продолжается. До in_progress срыв матча возвращает тот же заказ в поиск; полную отмену до работы делает только клиент.
• Внутренние рейтинги не отображаются в UI.
• Платежный провайдер остается источником истины по деньгам. После выплаты админ деньги не двигает.
• «Безопасная сделка» остается опциональной и модульной.
• Ценообразование заказа остается расширяемым по типам тарифов.

15) Сроки в правилах сервиса

Текст правил — SERVICE_RULES.md:

• 5 минут на ответ исполнителя;
• 1 сутки на подтверждение условий;
• 1 сутки на оплату безопасной сделки (иначе возврат в поиск);
• 1 сутки на второе подтверждение исполнения, иначе автоприёмка;
• 24 часа бездействия в поиске для срочного заказа, для планового — до даты начала.