Перейти к основному содержимому

UC-OVR-004. От реферальной ссылки до объекта у собственника

Назначение​

Сквозная воронка «от ссылки до покупки» (матрица): реферальная ссылка агента → регистрация инвестора → лид → фиксация клиента у застройщика → бронь → сделка → завершённая сделка → объект в портфеле инвестора-собственника. Пересекает referral → crm → chessboard → investor-owner и связывает их через интеграционные события. Крупные под-воронки вынесены в UC-OVR-005 (лид→сделка) и UC-OVR-006 (бронь→регистрация).

Metadata​

ПолеЗначение
Статусdraft
Owning teamcrm (оркестрация воронки)
Primary capabilityend-to-end-purchase-funnel
Risk levelhigh

Scope И Участники​

УчастникРоль
АгентВладелец реф-ссылки, ведёт лид, фиксирует клиента, создаёт бронь/сделку
ИнвесторПереходит по ссылке, регистрируется, покупает объект
Менеджер застройщикаОдобряет фиксацию, ведёт сделку со стороны девелопера
referralПривязка «инвестор↔агент» (bond) + запрос привязки лида
crmЛид → фиксация → бронь → сделка (ядро воронки)
chessboardСтатус объекта недвижимости (Резерв/Бронь/Продан)
investor-ownerПортфель собственника: объект после завершённой сделки
rewards / notificationsМетрики/комиссии агента, уведомления по этапам

Preconditions​

  • У агента есть активная реф-ссылка (UC-REF-001).
  • Объект застройщика опубликован в шахматке и доступен к бронированию.

Основной Сценарий​

  1. Ссылка. Агент делится реф-ссылкой; аноним открывает её — cookie referralUrl (UC-REF-002).
  2. Регистрация. Инвестор регистрируется/авторизуется; referral создаёт связку (bond) и запрашивает привязку лида — UC-REF-004 → pin.referral.bonds.v1, pin.referral.lead-attachments.v1.
  3. Лид. Заявка на консультацию/бронь (UC-OVR-001 / UC-OVR-003) → pin.crm.lead-created.v1 в воронке агента.
  4. Фиксация. Агент фиксирует клиента у застройщика (create-fixation.md, UC-FIX-001); менеджер застройщика одобряет (UC-FIX-002) → pin.crm.fixation-approved.v1 (rewards инкрементит user-centric метрику агента).
  5. Сделка. Из лида/одобренной фиксации создаётся сделка (UC-CRM-002) → pin.crm.deal-created.v1. Подробности лид→сделка — UC-OVR-005.
  6. Бронь. Создаётся бронь объекта → pin.crm.booking-created.v1/booking-paid.v1; chessboard переводит объект в «Резерв»/«Бронь» (UC-CHS-006).
  7. Ведение сделки. Канбан-этапы (UC-CRM-003) → pin.crm.deal-stage-changed.v1; регистрация/эскроу — UC-OVR-006.
  8. Завершение. Сделка завершается (UC-CRM-005) → pin.crm.deal-completed.v1; chessboard — объект «Продан».
  9. Собственник. investor-owner (consumer crm-deal-completed.md) добавляет объект в портфель инвестора (UC-OWN-002) → property-added.md / owner-linked.md.

Sequence​

Постусловие​

После полного прохода воронки (happy) гарантированно:

  • в referral есть связка (bond) инвестор↔агент (key = ReferredUserId), журнал привязки лида подтверждён;
  • в crm последовательно созданы и связаны Lead → одобренный FixationRequest → Deal → Booking; лид помечен сконвертированным; сделка достигла Completed; снапшоты AgentUserId/AgencyCompanyId иммутабельны на всех сущностях;
  • chessboard провёл объект Свободен → Резерв/Бронь → Продан (по событиям crm);
  • rewards учёл одобрение фиксации (user-centric метрика агента) и начислил комиссию по deal-completed (база — FinalPrice);
  • investor-owner завёл объект в портфель инвестора (first-seen по DealId) и опубликовал property-added/owner-linked;
  • по этапам ушли уведомления сторонам.

Инвариант атрибуции: агент, зафиксированный в лиде/сделке снапшотом AgentUserId, остаётся получателем метрик/комиссии до конца воронки независимо от последующей смены его членства (см. UC-OVR-008).

Альтернативные Сценарии И Отказы​

СитуацияПоведение
Фиксация отклонена застройщикомpin.crm.fixation-rejected.v1 (UC-FIX-003); сделка не создаётся; агент может уточнить и повторить (правила окна фиксации)
Бронь истекла/отмененаbooking-expired/booking-cancelled → объект возвращается в «Свободен»; воронка откатывается к этапу брони
Сделка отмененаdeal-cancelled вместо deal-completed; pin.crm.deal-completed.v1 не публикуется — объект в портфель не попадает, комиссия не начисляется
Реф-привязки нетВоронка идёт по ПИН-маршруту (UC-OVR-002); комиссия/атрибуция — у ПИН
deal-completed доставлен повторноinvestor-owner/rewards/chessboard идемпотентны (first-seen по DealId) — портфель/комиссия/статус не дублируются
Событие этапа опередило предыдущее (переупорядочивание)Порядок per-DealId гарантирован ключом; потребители держат Version-guard, устаревшее событие игнорируется
Агент вышел из агентства во время воронкиИсторические снапшоты AgencyCompanyId/AgentUserId не пересчитываются (back-fill запрещён, ADR-0061); воронка завершается на прежней атрибуции

Согласованность И Идемпотентность​

  • Событийная цепочка, а не распределённая транзакция. Этапы связаны асинхронными событиями (bonds/lead-attachments → lead-created → fixation-approved → deal-created → booking-created → deal-stage-changed → deal-completed → property-added). Каждое — атомарно с изменением своего агрегата; между этапами есть окна eventual-consistency (статус объекта/буст < 1 мин, метрики/уведомления < 5 мин).
  • Многошаговая координация с компенсацией вынесена в саги: бронь (Резерв → Бронь → передача в продажу) и завершение сделки (fan-out) — см. UC-OVR-006. Отказ на этапе не «ломает» ранее зафиксированные факты — он публикует компенсирующее/терминальное событие (fixation-rejected, booking-expired, deal-cancelled).
  • Идемпотентность терминала. deal-completed терминален и публикуется ровно один раз на сделку; downstream-эффекты (объект в портфель, комиссия, статус «Продан») — first-seen по DealId.
  • Порядок per-инвестор/per-сделка. Реф-связки упорядочены по ReferredUserId, событийная жизнь сделки — по DealId; глобального порядка между сделками нет.

Acceptance Criteria (Given/When/Then)​

  • Happy (ссылка → объект в портфеле). Дано: у агента активная реф-ссылка, объект застройщика опубликован. Когда: инвестор проходит регистрацию, лид, одобренную фиксацию, бронь и сделку до завершения. Тогда: объект переходит в «Продан», появляется в портфеле инвестора (property-added), агент получает user-centric метрику и комиссию с атрибуцией по снапшоту AgentUserId.
  • Фиксация отклонена. Дано: активный лид, отправлена фиксация. Когда: застройщик отклоняет. Тогда: fixation-rejected, сделка не создаётся, воронка останавливается на этапе фиксации.
  • Сделка отменена. Дано: сделка в работе. Когда: сделка отменяется. Тогда: deal-completed не публикуется, объект не попадает в портфель, комиссия не начисляется.
  • Нет реф-привязки. Дано: инвестор без bond к агенту. Когда: проходит воронку. Тогда: атрибуция и комиссия у ПИН (ПИН-маршрут).
  • Идемпотентность завершения. Дано: deal-completed доставлен дважды. Когда: потребители обрабатывают повтор. Тогда: объект в портфеле и комиссия — по одному разу (first-seen по DealId).

Source Of Truth И Данные​

ДанныеВладелецConsistency rule
Связка инвестор↔агент (bond)referralKey = ReferredUserId, строгий порядок per-инвестор
Лид/фиксация/бронь/сделкаcrmВ одном согласованном изменении; снапшоты AgencyCompanyId/AgentUserId иммутабельны
Статус объектаchessboardМеняется только по событиям crm (eventual)
Объект в портфелеinvestor-ownerСоздаётся по pin.crm.deal-completed.v1 (идемпотентно по DealId)

Контракты И Зависимости​

Наблюдаемость​

  • critical metrics: конверсия по этапам (ссылка→рег→лид→фиксация→бронь→сделка→завершено); time-to-close.
  • trace path: referral → crm (цепочка событий) → chessboard → investor-owner.
  • alerts: обрыв воронки на этапе (падение конверсии); объект «Продан» без записи в портфеле.

Риски И Guardrails​

  • Риск: потеря атрибуции агента при рассинхроне bond↔lead. Control: снапшот AgentUserId в лиде/сделке, back-fill запрещён.
  • Риск: дубль объекта в портфеле. Control: идемпотентность consumer по DealId (property-added first-seen).
  • Риск: рассинхрон статуса объекта. Control: chessboard — единственный владелец, изменения только событиями.

Обратные ссылки​

Автоссылки: где используется этот документ.