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

UC-OVR-007. Просмотр каталога «глазами инвестора» (impersonation)

Назначение​

Cross-service контракт-левел сценарий (реализация отложена): агент/менеджер ПИН просматривает каталог, избранное и историю просмотров своего лида-инвестора, чтобы вести консультацию по его контексту. Это не полноценный вход под инвестором, а read-only проекция активности инвестора для владельца лида, защищённая отдельным permission catalog.view-as-investor и жёстким аудитом. Здесь фиксируется контракт и границы; сам эндпоинт помечен как будущий.

Metadata​

ПолеЗначение
Статусdraft (реализация отложена)
Owning teamcatalog
Primary capabilityagent-view-as-investor
Risk levelhigh

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

УчастникРоль
Агент / Менеджер ПИНАктор: просматривает каталог в контексте инвестора
identityПроверка permission catalog.view-as-investor + запись ImpersonationKind в actor-контекст
crmПроверка record-level: инвестор — активный лид этого агента (право контекста)
catalogОтдаёт каталог с ранжированием/фильтрами инвестора (read-only)
favoritesИзбранное инвестора (read-only проекция)
user-activityИстория просмотров/действий инвестора (read-only)

Preconditions​

  • У агента есть активный лид с этим инвестором (crm) — контекстное основание доступа.
  • Агенту выдан permission catalog.view-as-investor в соответствующем scope.
  • Инвестор дал согласие на просмотр его активности (политика приватности — см. Риски).

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

  1. Агент в CRM открывает карточку лида и жмёт «Смотреть каталог как инвестор».
  2. Фронт вызывает будущий эндпоинт catalog с targetInvestorUserId (контракт — см. catalog/README.md, раздел impersonation; путь по конвенции).
  3. identity проверяет permission catalog.view-as-investor; в actor-контекст записывается признак impersonation ImpersonationKind.
  4. crm подтверждает record-level: targetInvestorUserId — активный лид актора (иначе 403).
  5. catalog формирует выдачу с фильтрами/ранжированием инвестора (read-only); favorites и user-activity отдают избранное и историю просмотров инвестора как проекции.
  6. Каждый такой доступ аудируется (кто, кого, когда смотрел); мутации от лица инвестора запрещены.

Sequence​

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

После каждого разрешённого доступа гарантированно:

  • актору возвращена read-only проекция каталога/избранного/истории просмотров в контексте инвестора (targetInvestorUserId); никакие сущности инвестора не изменены (мутации запрещены на уровне контракта);
  • в identity записан аудит-факт impersonation: кто (актор), кого (инвестор), когда, признак ImpersonationKind — на каждый вход, не только на первый;
  • состояние согласия инвестора и наличие активного лида перепроверены на момент доступа (не кэшируются между запросами).

Побочных доменных изменений и интеграционных событий сценарий не порождает (read-only): счётчики просмотров/избранное инвестора не растут от чужого просмотра.

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

СитуацияПоведение
Нет активного лида с инвестором403 — контекстного основания нет
Лид истёк/сконвертирован между входамиДоступ прекращается при следующем запросе (403) — право контекста проверяется каждый раз
Нет permission catalog.view-as-investor403 — доступ не выдан
Permission отозван во время сессииСледующий запрос → 403; открытая проекция не продлевается
Попытка мутации (добавить в избранное и т.п.)Запрещено — режим строго read-only
Инвестор отозвал согласиеДоступ закрывается; контракт учитывает флаг согласия (проверка на каждый вход)
favorites/user-activity недоступныДеградация: соответствующий блок скрыт, каталог отдаётся без проекции активности

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

  • Двойная проверка основания на каждый доступ: permission (identity) и активный лид (record-level в crm) и флаг согласия инвестора — все синхронно, до отдачи проекции; кэширование права между запросами запрещено (просроченное основание не должно давать доступ).
  • Строгий read-only на уровне контракта: любой мутирующий вызов от лица инвестора отклоняется; проекции favorites/user-activity отдают снимок на момент запроса (freshness — их обычный SLA чтения).
  • Аудит обязателен и не идемпотентен по смыслу: каждый вход добавляет отдельную запись (для расследования «кто и когда смотрел»), повторный доступ — новая запись, не дедуп.
  • Реализация отложена: здесь фиксируется контракт и границы; сам эндпоинт catalog помечен будущим.

Acceptance Criteria (Given/When/Then)​

  • Happy (просмотр по основанию). Дано: у агента активный лид с инвестором, выдан permission catalog.view-as-investor, инвестор дал согласие. Когда: агент открывает «Смотреть каталог как инвестор». Тогда: возвращается read-only проекция каталога/избранного/истории инвестора, записан аудит-факт, мутаций нет.
  • Нет активного лида. Дано: лида с инвестором нет. Когда: запрос проекции. Тогда: 403, аудит фиксирует отказ.
  • Нет/отозван permission. Дано: permission не выдан или отозван. Когда: запрос проекции. Тогда: 403.
  • Попытка мутации. Дано: разрешённая сессия просмотра. Когда: актор пытается добавить объект в избранное инвестора. Тогда: операция отклонена (строгий read-only), состояние инвестора неизменно.
  • Отзыв согласия. Дано: инвестор отозвал согласие между входами. Когда: следующий запрос. Тогда: доступ закрыт (403).

Source Of Truth И Данные​

ДанныеВладелецConsistency rule
Право контекста (активный лид)crmRecord-level, проверяется на каждый доступ
Permission / ImpersonationKindidentityПроверка + аудит на каждый вход
Каталог / избранное / историяcatalog / favorites / user-activityRead-only проекции, без мутаций

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

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

  • critical metrics: число impersonation-сессий, уникальные пары агент↔инвестор, доля отказов 403.
  • trace path: identity (permission) → crm (record-level) → catalog/favorites/user-activity.
  • alerts: аномальный рост impersonation одним агентом; доступ без активного лида.

Риски И Guardrails​

  • Риск: слежка за инвестором без основания. Control: обязательный активный лид + permission + аудит каждого входа.
  • Риск: подмена данных инвестора. Control: строгий read-only, мутации от его лица запрещены на уровне контракта.
  • Риск: приватность. Control: флаг согласия инвестора; реализация отложена до проработки политики приватности.

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

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