Кросс-сервисные сценарии PIN (OVR)
Дом сквозных бизнес-сценариев (UC-OVR-*), которые связывают несколько bounded contexts, правил,
событий и пользовательских шагов в единый поток. Отдельные сервисные шаги живут в
docs/06-services/<context>/use-cases/; здесь — их оркестрация и события между сервисами.
Структура каждого документа — по system-scenario-template
(акторы, участвующие сервисы, sequenceDiagram, ссылки на сервисные UC, интеграционные события). Префикс
OVR — см. use-case-template; реестр —
use-cases-index.md.
Реестр сценариев
| ID | Сценарий | Ключевые контексты | Документ |
|---|---|---|---|
| UC-OVR-001 | Запрос консультации у агента недвижимости | catalog → crm → identity → referral → notifications | UC-OVR-001 |
| UC-OVR-002 | Запрос консультации у инвест-консультанта ПИН (+2a) | catalog → crm → identity → notifications | UC-OVR-002 |
| UC-OVR-003 | Бронирование объекта у агента (+3a) | catalog → crm/booking → chessboard → notifications | UC-OVR-003 |
| UC-OVR-004 | От реферальной ссылки до объекта у собственника | referral → crm → chessboard → investor-owner | UC-OVR-004 |
| UC-OVR-005 | От лида до сделки (4 фазы) | crm (lead → fixation → deal) | UC-OVR-005 |
| UC-OVR-006 | Сделка: от брони до регистрации (инвестор-инициатор) | crm/booking → chessboard → crm/deal | UC-OVR-006 |
| UC-OVR-007 | Просмотр каталога «глазами инвестора» (impersonation) | identity → catalog → favorites → user-activity | UC-OVR-007 |
| UC-OVR-008 | Агент выходит из агентства, сохраняя метрики | identity → crm → rewards → catalog/chessboard | UC-OVR-008 |
| UC-OVR-009 | Продвижение поста / объекта недвижимости | promotion → catalog → news → notifications | UC-OVR-009 |
| UC-OVR-010 | От завершённой сделки до выплаты комиссии и реферального вознаграждения | crm → rewards → wallet → notifications | UC-OVR-010 |
| UC-OVR-011 | Самозапись инвестора: от слота до исхода встречи и лида в воронке | calendar → crm → identity → notifications | UC-OVR-011 |
Как читать
- «Участвующие сервисы» — таблица
Scope И Участники: кто владеет данными, кто оркеструет, кто потребляет. - Стрелки на
sequenceDiagram— синхронные вызовы (API/internal) и асинхронные интеграционные события (pin.<context>.<event>.v1; надёжная доставка — ADR-0006). - Каждый шаг ссылается на конкретный сервисный UC/эндпоинт/событие — сценарий сам логику не дублирует.
- Каждый сценарий несёт Предусловие (что истинно до), Постусловие (что гарантированно после — какие сущности/статусы изменились, какие события ушли) и Acceptance Criteria (Given/When/Then на happy path, ключевые edge-cases и отказы). Читать сценарий как контракт «вход → гарантированный результат».
Синхронно, асинхронно, окно согласованности
Внутри одного сценария смешаны два вида взаимодействия — их важно различать при реализации и тестировании:
- Синхронные вызовы (сплошная стрелка
->>к API/internal-эндпоинту): результат виден вызывающему сразу, ошибка возвращается кодом (4xx/5xx) в том же обращении. Пример:crm→identityget-or-create,crm→referralправила привязки. - Асинхронные события (стрелка
-->>через «Шину событий»): публикуются атомарно со сменой состояния агрегата-издателя (до фиксации событие не уходит; после — доставка гарантированная, at-least-once). Потребитель применяет эффект с задержкой — окно eventual-consistency. В этом окне пользователь видит прежнее состояние у контекста-потребителя (напр. объект в шахматке ещё «Свободен», покаchessboardне обработалbooking-created). Типовые окна (SLA обработки): статус объекта вchessboardи буст вcatalog/news— < 1 мин; уведомления и карточки в чате — < 5 мин.
Сквозные гарантии и конвенции
- Порядок и ключ партиционирования. Порядок событий гарантирован per-aggregate ключом Kafka: лид —
LeadId, бронь —BookingId, завершение сделки —DealId, реф-связка (bond) —ReferredUserId, членство агента —AgentUserId, продвижение —PurchaseId. Между разными агрегатами глобального порядка нет — сценарии не должны на него закладываться. - Идемпотентность. Lazy-регистрация инвестора идемпотентна по телефону; повтор публичной заявки в окне
дедупликации →
409 DUPLICATE_PHONE; потребители дедуплицируют поMessageId, терминальные эффекты — по бизнес-ключу агрегата (объект в портфель / комиссия — first-seen поDealId); при повторной доставке эффект не дублируется. - Version-guard и конкурентность. Проекции статусов/бустов держат монотонный
Version-guard: событие с версией ≤ применённой игнорируется (защита от переупорядочивания и повторов). Конкурентная правка одной сущности разрешается оптимистической блокировкой — проигравший получает409 CONCURRENCY_CONFLICTи повторяет на свежем состоянии. - Единственный владелец статуса объекта. Статус объекта недвижимости меняет только
chessboardи только по событиямcrm; другие контексты его не пишут (защита от двойной брони/рассинхрона). - Иммутабельные снапшоты и атрибуция.
AgentUserId/AgencyCompanyIdв лидах/фиксациях/сделках — иммутабельны; back-fill при смене членства агента запрещён (ADR-0061). User-centric метрики агрегируются поAgentUserIdи переживают смену компании. - PII не в событиях. Интеграционные события несут id-ссылки и бизнес-факты без ФИО/телефона; display-данные
потребители берут из собственной реплики
pin.identity.users.v1, в логах маскируют (+7***1234).
Связанные документы
- ТЗ: technical-assignment.md (раздел «Сквозные сценарии»).
- Границы сервисов: architecture-overview.md, transaction-boundaries-and-sagas.md.
- Реестры: use-cases-index.md, events-index.md.