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

GET /api/admin/v1/lots/{propertyObjectId}/override — Просмотр оверрайда объекта недвижимости (admin)

Назначение​

Возвращает администратору платформы полную картину витринных данных объекта недвижимости для правки: исходные значения источников (SourceSnapshot карточки), текущий оверрайд (если есть) и эффективные значения витрины (Effective = Override ?? SourceSnapshot, INV-3 catalog-property-object-card.md).

Зачем три блока

Три блока вместо голой строки оверрайда — чтобы админ видел, что именно он перекрывает.

Metadata​

ПолеЗначение
Сервис/контекстcatalog
API areaadmin (ADR-0053)
Feature groupadmin-overrides
Статусdraft
Документdocs/06-services/catalog/api/admin/get-property-object-override.md

Актор и доступ​

ПроверкаЗначение
Actor typeExternalSystem (администратор платформы через admin API; m2m client-credentials — ADR-0053)
Auth policy / Permissionspolicy AdminSystemOnly: OAuth2 client-credentials клиента pin-admin-system; каталожное соответствие — permission catalog.overrides.view (identity/domain/permission.md)
Scope (RBAC)платформа (оверрайды — платформенные данные, не tenanted — ADR-0052 п.3)
Auditread-sensitive: Comment оверрайда — internal; чтение логируется (admin-доступ), deep audit мутаций — в PUT-операции

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/admin/v1/lots/{propertyObjectId}/override
Success status200
Idempotency headerне применяется (чтение)
Correlationсквозной trace через traceparent; X-Admin-User-Id (Guid админа) — обязательный заголовок admin-области

Входные данные / параметры запроса​

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
PropertyObjectIdrouteGuidДа!= Guid.Empty; существование карточки — шаг 2 алгоритма—
AdminUserIdheader X-Admin-User-IdGuidДа!= Guid.Emptyлог admin-доступа

Модель ответа PropertyObjectOverrideView​

ПолеТипОбязательностьИсточникMaskingОписание
PropertyObjectIdGuidДаCatalogPropertyObjectCard.Id—Объект недвижимости.
CardStatusstring (enum PropertyObjectCardStatus)ДаCatalogPropertyObjectCard.Status—Published / Hidden / Delisted.
SourcePropertyObjectOverrideSourceBlockДаCatalogPropertyObjectCard.SourceSnapshot—Исходные значения источников до оверрайдов.
OverridePropertyObjectOverrideBlock?Нет (null — живого оверрайда нет)PropertyObjectDisplayOverride—Текущий оверрайд.
EffectivePropertyObjectOverrideEffectiveBlockДаCatalogPropertyObjectCard (эффективные колонки)—Что реально видит витрина.

Модель PropertyObjectOverrideSourceBlock (проекция PropertyObjectSourceSnapshotDocument — дом полей catalog-property-object-card.md)​

ПолеТипОбязательностьИсточникMaskingОписание
TitlestringДаSourceSnapshot.Title—Исходный заголовок (chessboard).
PricedecimalДаSourceSnapshot.Price—Исходная цена.
Badgestring?НетSourceSnapshot.Badge—Исходный бейдж.
PaybackValuedecimal?НетSourceSnapshot.PaybackValue—Окупаемость (invest-analytics).
PaybackPeriodstring? (enum PaybackPeriod)НетSourceSnapshot.PaybackPeriod—Years / Months.
ReliabilityValueshort?НетSourceSnapshot.ReliabilityValue—Надёжность.
ReliabilityMaxshort?НетSourceSnapshot.ReliabilityMax—Шкала надёжности.
Ratingdecimal?НетSourceSnapshot.Rating—Рейтинг.
ChessboardVersionlongДаSourceSnapshot.ChessboardVersion—Версия источника (диагностика расхождений).

Модель PropertyObjectOverrideBlock (проекция PropertyObjectDisplayOverride — дом полей display-override.md)​

ПолеТипОбязательностьИсточникMaskingОписание
IdGuidДаPropertyObjectDisplayOverride.Id—Идентификатор оверрайда.
IsVisiblebool?НетPropertyObjectDisplayOverride.IsVisible—null = не переопределено (правило всех полей блока).
Pricedecimal?НетPropertyObjectDisplayOverride.Price——
Titlestring?НетPropertyObjectDisplayOverride.Title——
Badgestring?НетPropertyObjectDisplayOverride.Badge——
ReliabilityValueshort?НетPropertyObjectDisplayOverride.ReliabilityValue——
ReliabilityMaxshort?НетPropertyObjectDisplayOverride.ReliabilityMax——
PaybackValuedecimal?НетPropertyObjectDisplayOverride.PaybackValue——
PaybackPeriodstring? (enum PaybackPeriod)НетPropertyObjectDisplayOverride.PaybackPeriod——
Ratingdecimal?НетPropertyObjectDisplayOverride.Rating——
Commentstring?НетPropertyObjectDisplayOverride.Commentinternal — только admin-область (в public-ответы не попадает)Комментарий админа «зачем правка».
UpdatedAtDateTimeOffsetДаPropertyObjectDisplayOverride.UpdatedAt—Последняя правка.
UpdatedByUserIdGuid?НетPropertyObjectDisplayOverride.UpdatedByUserId ?? CreatedByUserId—Автор последней правки.
VersionlongДаPropertyObjectDisplayOverride.Version—Счётчик правок — передаётся обратно в PUT для optimistic-check.

Модель PropertyObjectOverrideEffectiveBlock (эффективные колонки CatalogPropertyObjectCard)​

ПолеТипОбязательностьИсточникMaskingОписание
TitlestringДаCatalogPropertyObjectCard.Title—Эффективный заголовок.
PricedecimalДаCatalogPropertyObjectCard.Price—Эффективная цена.
PricePerMeterdecimalДаCatalogPropertyObjectCard.PricePerMeter—Пересчитанная цена за м².
Badgestring?НетCatalogPropertyObjectCard.Badge——
PaybackValuedecimal?НетCatalogPropertyObjectCard.Payback.Value——
PaybackPeriodstring? (enum PaybackPeriod)НетCatalogPropertyObjectCard.Payback.Period——
ReliabilityValueshort?НетCatalogPropertyObjectCard.Reliability.Value——
ReliabilityMaxshort?НетCatalogPropertyObjectCard.Reliability.Max——
Ratingdecimal?НетCatalogPropertyObjectCard.Rating——

Алгоритм​

  1. Контекст и доступ. Актор — администратор платформы (admin API, m2m-клиент pin-admin-system, policy AdminSystemOnly); X-Admin-User-Id логируется. Идемпотентность к чтению не применяется.
  2. Проверка входа. PropertyObjectId != Guid.Empty, AdminUserId != Guid.Empty; иначе ValidationError. Карточка объекта недвижимости существует; если нет → CATALOG_PROPERTY_OBJECT_NOT_FOUND (404). Состояние чтение не ограничивает: Hidden/Delisted карточки тоже показываются (админ должен видеть скрытое).
  3. Что читаем. Карточку объекта недвижимости (для блоков Source/Effective/CardStatus) и живой оверрайд объекта недвижимости PropertyObjectDisplayOverride (снятые оверрайды отфильтрованы; допустимо отсутствие → блок Override = null).
  4. Маппинг. Source.* ← снапшот источника карточки (SourceSnapshot); Override.* ← оверрайд (или null); Effective.* ← эффективные колонки карточки (Title, Price, PricePerMeter, Badge, Payback, Reliability, Rating); CardStatus ← статус карточки.
  5. Результат. PropertyObjectOverrideView; freshness — актуальное состояние строки (source of truth оверрайдов — этот контекст, лага нет).
примечание
Freshness блока Source

Source — снапшот источника на момент последнего применённого события chessboard/invest-analytics: если консюмер источника отстаёт, блоки Source и Effective отражают ещё старые значения. Source.ChessboardVersion — диагностический маркер, по которому админ видит расхождение витрины с источником (runbook сверки).

Диаграмма​

Ошибки и failure modes​

КодHTTP statusУсловиеСообщениеRetry
ValidationError400Пустой PropertyObjectId/X-Admin-User-IdОшибка валидации запросаno retry
UNAUTHORIZED401Нет/просрочен m2m client-credentials токенТребуется авторизацияno retry
FORBIDDEN403Клиент не pin-admin-system / нет catalog.overrides.viewДоступ запрещёнno retry
CATALOG_PROPERTY_OBJECT_NOT_FOUND404Карточка объекта недвижимости не существует в catalog.property_object_cardsОбъект недвижимости не найден в каталогеno retry

Совместимость и наблюдаемость​

  • Новые optional поля блоков — без breaking change (additive); удаление/переименование/смена типа — breaking (migration + rollout). Рост ContractVersion snapshot-документа отражается в Source additive-полями.
  • Logs: admin-property-object-override-viewed (propertyObjectId, adminUserId); metrics: catalog_admin_operations_total{operation="get-property-object-override"}, duration; traces: span приёма → span обработки → span обращения к хранилищу; correlation — сквозной trace через traceparent. Dashboard catalog-overview; runbook — сверка SourceSnapshot.ChessboardVersion с chessboard при расхождениях витрины.

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

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

Связанные документы​