Entity / Aggregate: `CatalogPropertyObjectCard`

Дом полей денормализованной карточки объекта недвижимости публичного каталога (контекст catalog). Модели ответов public API (лента /lots, карточка /lots/[id]/info), payload событий и поисковые проекции ссылаются сюда и описывают только дельту.

Назначение

CatalogPropertyObjectCard — денормализованная витринная проекция объекта недвижимости для ленты /lots, ассортимента проекта /hotels/[id]/assortment и карточки /lots/[id]/info: все поля карточки отдаются из одной строки без джойнов в источники.

Правило «только дельта + ссылка на дом chessboard»

Source of truth структурных данных объекта недвижимости (номер, этаж, площади, комнатность, планировка, статус) — контекст chessboard (chessboard/domain/property-object.md). Этот документ владеет только витринной дельтой: эффективными (после оверрайдов) значениями отображения, метриками доходности из invest-analytics, комиссией из rewards и ранжированием. Колонка «Источник» в таблице полей указывает канонический дом каждого поля; переописывать поля источников в других документах запрещено.

Карточка обновляется только консюмерами и внутренними операциями каталога (оверрайд/ранжирование/ продвижение); прямых пользовательских мутаций нет. Правило вычисления каждого эффективного поля: Effective = Override(поле) ?? SourceSnapshot(поле) (оверрайды — display-override.md). Полнотекстовый поиск карточки вынесен в Elasticsearch-проекцию (../search/property-objects.md, ADR-0059) — tsvector/GIN здесь нет.

Классификация

Поле	Значение
Контекст	`catalog`
Kind	`Replica` (денормализованная read-проекция; мутируется консюмерами + пересчётом оверрайдов)
Базовые контракты	реплика-проекция, не агрегат — доменных инвариантов покупки/брони здесь нет, только правила проекции
Source of truth	структурные поля — `chessboard`; метрики — `invest-analytics`; комиссия — `rewards`; эффективные display-значения и ранжирование — этот контекст
Таблица	`catalog.property_object_cards`
Tenant isolation	не tenanted — платформенные данные витрины (ADR-0052 п.3); видимость решается `Status`/permissions; `Developer.DeveloperId` — обычная колонка для фильтров и ranking-scope
Search projection	Elasticsearch `property-objects` (ADR-0059)

Поля

Легенда источников

chessboard — событие pin.chessboard.property-object-upserted.v1/pin.chessboard.building-upserted.v1 (дом полей — chessboard/domain/property-object.md, chessboard/domain/building.md); invest-analytics — событие pin.invest-analytics.property-object-metrics.v1 (invest-analytics/domain/); rewards — событие pin.rewards.commission-rules.v1 (rewards/domain/reward-rule.md); override — display-override.md; catalog — вычисляется этим контекстом.

Поле	Тип	Обязательность	Ограничения (PK/FK/index/constraint)	Источник	Описание
`Id`	`Guid`	Да	PK	chessboard (`PropertyObject.Id`)	Идентификатор объекта = id в `chessboard`.
`ProjectId`	`Guid`	Да	index `ix_property_object_cards_project_id`; логическая ссылка на `catalog.project_cards.id` (без FK — порядок событий проектов/объектов не гарантирован; guard INV-2)	chessboard	Проект (ЖК/отель) объекта.
`Building`	`BuildingRefModel` (owned)	Да	см. VO; index `ix_property_object_cards_building_id`	chessboard	Здание/литер/корпус (id + название).
`Developer`	`DeveloperRefModel` (owned)	Да	см. VO; index `ix_property_object_cards_developer_id`	chessboard	Застройщик (id + имя): scope ранжирования, фильтр «девелопер», поисковая проекция.
`Number`	`string`	Да	`varchar(32)`	chessboard	Номер объекта.
`Title`	`string`	Да	`varchar(512)`	override → chessboard	Эффективный заголовок карточки (`Override.Title ?? SourceSnapshot.Title`).
`View`	`string?`	Нет	`varchar(64)`	chessboard	Вид из окон (море/город/двор).
`Badge`	`string?`	Нет	`varchar(64)`	override → chessboard	Маркетинговый бейдж карточки («Хит», «Скидка»).
`Address`	`string`	Да	`varchar(512)`	chessboard (проект)	Адрес проекта, денормализован в объект. Индексируется в поисковой проекции.
`DistanceMinutes`	`int?`	Нет	`>= 0`	override (building) → chessboard	Минуты до ключевой точки (море/центр).
`Stars`	`short?`	Нет	`1..5`	override (building) → chessboard	Звёздность апарт-отеля.
`DeliveryDate`	`DateOnly?`	Нет	index `ix_property_object_cards_delivery_date`	override (building) → chessboard	Срок сдачи.
`ReadinessPercent`	`short?`	Нет	`0..100`	override (building) → chessboard	Готовность строительства.
`Price`	`decimal(14,2)`	Да	`> 0`, index `ix_property_object_cards_price`	override → chessboard	Эффективная цена карточки (`Override.Price ?? SourceSnapshot.Price`). Сортировка «по цене» и фильтр «ценовой диапазон».
`Layout`	`PropertyObjectLayoutModel` (owned)	Да	см. VO	chessboard + catalog	Планировочные характеристики (тип/комнатность/площади/этаж/потолки/планировка/цена за м²).
`VisualizationFileId`	`Guid?`	Нет	без FK (внешний storage/CDN)	chessboard	Файл визуализации/планировки (пресайн — граница storage).
`PropertyObjectStatus`	`PropertyObjectAvailabilityStatus`	Да	хранится как text, `varchar(32)`, index `ix_property_object_cards_availability`	chessboard	Реплика статуса доступности: `Free` / `Reserved` / `Booked` / `Sold` / `Hidden` (дом статуса и переходов — `chessboard`).
`Payback`	`PropertyObjectPayback` (owned)	Нет (оба поля nullable вместе)	см. VO	override → invest-analytics	Окупаемость.
`Reliability`	`PropertyObjectReliability` (owned)	Нет	см. VO	override → invest-analytics	Индекс надёжности.
`GrowthPercent`	`decimal(5,2)?`	Нет	`-99.99..999.99`	invest-analytics	Прогнозный рост цены, %/год.
`RentalIncomePerYear`	`decimal(14,2)?`	Нет	`>= 0`	invest-analytics	Прогнозный арендный доход, руб/год.
`Rating`	`decimal(3,1)?`	Нет	`0.0..10.0`	override → invest-analytics	Рейтинг объекта.
`AgentCommission`	`PropertyObjectAgentCommission` (owned)	Нет	см. VO	rewards	Денормализованная комиссия агента; в ответах отдаётся только акторам с permission `catalog.commissions.view`.
`DeveloperPriority`	`int`	Да	`0..1000`, default `0`, index composite (см. Индексы)	catalog (ranking-rule.md)	Приоритет застройщика в рамках его объектов.
`PromotionBoost`	`int`	Да	`>= 0`, default `0`	consumer `promotion` (../consumers/promotion-boost.md)	Суммарный вес активных пакетов продвижения (проектных + по объектам недвижимости); наполняется консюмером `pin.promotion.purchase-changed.v1` (не владеется каталогом, ADR-0060). Ранжирование «Рекомендованные» остаётся у каталога (ranking-rule.md).
`PopularityViews`	`long`	Да	`>= 0`, default `0`	catalog (consumer `pin.user-activity.property-object-view-ended.v1`)	Счётчик завершённых просмотров объекта (ADR-0056 п.3); дом первичных данных — `user-activity/domain/property-object-view.md`.
`PopularityScore`	`decimal(12,4)`	Да	`>= 0`, default `0`, index `ix_property_object_cards_popularity`	catalog (job)	Сглаженная популярность (просмотры за 30 дней с экспоненциальным затуханием); пересчёт ночным job-ом. Сортировка «по популярности».
`Status`	`PropertyObjectCardStatus`	Да	хранится как text, `varchar(32)`, index `ix_property_object_cards_status`	catalog (правило видимости, INV-1)	`Published` / `Hidden` / `Delisted`.
`SourceSnapshot`	`PropertyObjectSourceSnapshotDocument` (jsonb)	Да	typed jsonb, `ContractVersion`	consumer-ы	Последние сырые значения источников для идемпотентного пересчёта (см. JSONB).
`PublishedAt`	`DateTimeOffset?`	Нет	index `ix_property_object_cards_published_at`	catalog	Первая публикация карточки; сортировка «по дате добавления».
`ChessboardSyncedAt` / `AnalyticsSyncedAt?` / `RewardsSyncedAt?`	`DateTimeOffset`	Да / Нет / Нет	—	consumer	Время применения последнего события `chessboard` / `invest-analytics` / `rewards`.
`CreatedAt` / `UpdatedAt`	`DateTimeOffset`	Да	—	app	Создание проекции / последний пересчёт.

Enum `PropertyObjectCardStatus` (хранится как text)

Значение	Описание
`Published`	Карточка видима в ленте/поиске/карточке проекта.
`Hidden`	Скрыта правилом видимости (INV-1): оверрайд `IsVisible=false` (объект или корпус), `PropertyObjectStatus=Hidden` у источника, скрытый/неопубликованный проект. Данные сохранены, из выдачи исключена.
`Delisted`	Объект удалён в источнике (`chessboard` прислал delete): карточка помечена и очищается retention-job-ом через 30 дней (ссылочная целостность избранного/подборок — по id, они переживают удаление).

Enum `PropertyObjectAvailabilityStatus` — реплика; дом значений и переходов — `chessboard/domain/property-object.md`

Значение	Отображение в каталоге
`Free`	«Свободен» — кнопка «Забронировать» активна.
`Reserved`	«Резерв» — таймер, бронирование недоступно.
`Booked`	«Бронь».
`Sold`	«Продан».
`Hidden`	Не отображается (карточка → `Hidden`, INV-1).

Value objects

`DeveloperRefModel` / `BuildingRefModel` (owned) — ссылки id + имя

Модель	Поле	Тип	Ограничения	Колонка
`DeveloperRefModel`	`DeveloperId`	`Guid`	index `ix_property_object_cards_developer_id`	`developer_id`
`DeveloperRefModel`	`DeveloperName`	`string`	`varchar(256)`; реплика из `pin.identity.companies.v1` через project-card; индексируется в поисковой проекции	`developer_name`
`BuildingRefModel`	`BuildingId`	`Guid`	index `ix_property_object_cards_building_id`	`building_id`
`BuildingRefModel`	`BuildingName`	`string`	`varchar(256)`	`building_name`

`PropertyObjectLayoutModel` (owned) — планировочные характеристики

Поле	Тип	Обязательность	Ограничения	Колонка
`TypeName`	`string`	Да	`varchar(64)`, index `ix_property_object_cards_type_name`	`layout_type_name`
`RoomsCount`	`short`	Да	`>= 0` (0 = студия), index `ix_property_object_cards_rooms_count`	`layout_rooms_count`
`AreaTotal`	`decimal(8,2)`	Да	`> 0`	`layout_area_total`
`AreaLiving`	`decimal(8,2)?`	Нет	`> 0`	`layout_area_living`
`PricePerMeter`	`decimal(12,2)`	Да	`> 0`; `round(Price / AreaTotal, 2)` — пересчёт при изменении `Price`/`AreaTotal`	`layout_price_per_meter`
`Floor`	`short`	Да	`>= -5`	`layout_floor`
`FloorsTotal`	`short`	Да	`>= 1`, `Floor <= FloorsTotal` (check)	`layout_floors_total`
`CeilingHeight`	`decimal(4,2)?`	Нет	`2.00..10.00`	`layout_ceiling_height`
`LayoutId`	`Guid?`	Нет	index `ix_property_object_cards_layout_id`	`layout_id`
`LayoutGroupId`	`Guid?`	Нет	—	`layout_group_id`

Использование полей layout

TypeName — фильтр «тип» (квартира/апартамент/паркинг/коммерция); RoomsCount — фильтр объектов проекта; LayoutId/LayoutGroupId — ключ матчинга правил комиссии rewards.

`PropertyObjectPayback` (owned)

Поле	Тип	Обязательность	Ограничения	Колонка
`Value`	`decimal(5,1)`	Да (внутри VO)	`> 0`	`payback_value`
`Period`	`PaybackPeriod` (enum-string)	Да	`Years` / `Months`, `varchar(16)`	`payback_period`

Нормализация периода

Сортировка «по окупаемости» использует нормализацию в годы: Value при Period=Years, Value/12 при Period=Months (вычисляется в query, не хранится).

`PropertyObjectReliability` (owned)

Поле	Тип	Обязательность	Ограничения	Колонка
`Value`	`short`	Да	`0..Max` (check)	`reliability_value`
`Max`	`short`	Да	`1..100`	`reliability_max`

`PropertyObjectAgentCommission` (owned) — денормализация правила `rewards`

Поле	Тип	Обязательность	Ограничения	Колонка
`Percent`	`NullableRange<decimal>`	Да	`Min`/`Max` каждый `0.00..100.00`, `Min <= Max`; `decimal(5,2)`	`commission_percent_min` / `commission_percent_max`
`BaseKind`	`CommissionBaseKind` (enum-string)	Да	`BasePrice` (до ремонта/скидки) / `FinalPrice` (базовая + ремонт), `varchar(32)` — дом определения: `rewards/domain/reward-rule.md`	`commission_base_kind`
`RewardRuleId`	`Guid`	Да	без FK (чужой контекст)	`commission_reward_rule_id`
`RuleVersion`	`long`	Да	`>= 1`; guard out-of-order событий rewards	`commission_rule_version`

Диапазон комиссии

Percent.Min = Percent.Max, когда правило одно; диапазон появляется, когда несколько правил застройщика матчатся по условиям (тип/планировка/группа/комнатность/площадь) и точный процент зависит от программы сделки. null (весь VO) — комиссия для объекта не задана; фронт не показывает блок.

Модели JSONB (versioned)

`PropertyObjectSourceSnapshotDocument` (jsonb, колонка `source_snapshot`, `ContractVersion = 1`)

Сырые значения источников до применения оверрайдов — чтобы пересчёт эффективных полей при создании/изменении/удалении оверрайда не требовал запроса в чужой контекст, а консюмеры были идемпотентны по версиям.

Поле	Тип	Обязательность	Ограничения	Since version
`ContractVersion`	`int`	Да	`= 1`	v1
chessboard-снимок	—	Да/Нет	`Title string(512)`, `Price decimal>0`, `Badge string?(64)`, `Stars short?1..5`, `DeliveryDate DateOnly?`, `ReadinessPercent short?0..100`, `DistanceMinutes int?>=0` — исходные значения до оверрайдов	v1
analytics-снимок	—	Нет	`PaybackValue decimal?>0`, `PaybackPeriod enum? Years/Months`, `ReliabilityValue short?`, `ReliabilityMax short?1..100`, `Rating decimal?0..10`	v1
`ChessboardVersion`	`long`	Да	`>= 1`; версия агрегата объекта в последнем применённом событии `chessboard` (guard INV-4)	v1
`AnalyticsAsOf`	`DateTimeOffset?`	Нет	момент расчёта метрик в применённом событии `invest-analytics`	v1

Версионирование snapshot

Правила версии: additive-поля — той же версией (nullable/default); изменение семантики — ContractVersion + 1 + migration-reader. Секреты/PII в jsonb запрещены (здесь их нет).

Связи

Связь	Тип	Ключ	Правило загрузки	Delete behavior
`CatalogProjectCard`	reference (логическая, без FK)	`property_object_cards.project_id → project_cards.id`	карточка проекта при пересчёте видимости; лента объектов — без джойна (всё денормализовано)	нет каскада: скрытие проекта → пересчёт `Status` объектов (INV-1)
`PropertyObjectDisplayOverride`	reference (обратная, 0..1)	`property_object_display_overrides.property_object_id → property_object_cards.id` (логическая)	живой оверрайд объекта при пересчёте	удаление оверрайда → пересчёт эффективных полей из `SourceSnapshot`
`BuildingDisplayOverride`	reference (логическая, 0..1 на корпус)	`building_display_overrides.building_id = property_object_cards.building_id`	живой корпусной оверрайд при пересчёте	то же
`chessboard.PropertyObject`	replica-источник	`Id`	consumer `pin.chessboard.property-object-upserted.v1`	delete-событие → `Status = Delisted`

Инварианты и переходы состояний

Инвариант	Условие	Где проверяется	Ошибка
INV-1 VisibilityRule	`Status = Published` ⇔ (`PropertyObjectStatus != Hidden`) ∧ (`PropertyObjectOverride.IsVisible != false`) ∧ (`BuildingOverride.IsVisible != false`) ∧ (project-card `Status = Published`)	пересчёт видимости — вызывается каждым консюмером и пересчётом оверрайда	нет ошибки — детерминированный пересчёт
INV-2 ProjectFirst	Карточка публикуется (`Published`) только при существующей `CatalogProjectCard` с тем же `ProjectId`; если проекта ещё нет (out-of-order событий) — карточка создаётся в `Hidden` и публикуется консюмером проекта	consumer объекта (проверка карточки проекта)	нет ошибки — отложенная публикация
INV-3 EffectiveFields	Для каждого оверрайдимого поля: `Effective = Override(поле) ?? SourceSnapshot(поле)`; `Layout.PricePerMeter = round(Price / Layout.AreaTotal, 2)`	пересчёт эффективных полей при применении оверрайдов	нет ошибки — детерминированный пересчёт
INV-4 MonotonicChessboard	Событие `chessboard` применяется только при `event.Version > SourceSnapshot.ChessboardVersion`	consumer, до мутации	нет — событие идемпотентно пропускается
INV-5 CommissionConsistency	`AgentCommission` обновляется только при `event.RuleVersion >= AgentCommission.RuleVersion`	consumer `rewards`	нет — пропуск
INV-6 PriceRange	Эффективная `Price > 0`; оверрайд с `Price <= 0` отклоняется на записи оверрайда	validator оверрайда (см. display-override.md)	`CATALOG_OVERRIDE_INVALID_PRICE`
INV-7 DelistedFrozen	Из `Delisted` нет переходов; консюмеры игнорируют события по `Delisted`-карточке кроме повторного upsert-а объекта (восстановление в источнике)	consumer guard	нет

Доменные и интеграционные события

Событие	Тип	Когда	Snapshot/поля
`PropertyObjectCardRecomputedEvent`	доменное	Любой пересчёт эффективных полей/статуса (внутренний триггер обновления агрегатов project-card: Price-диапазон/PropertyObjectsAvailable)	`Id`, `ProjectId`, `Price`, `Status`, `PropertyObjectStatus`

Карточка не публикует интеграционные события

Витрина — конечная точка данных; просмотры и поисковые действия пишет фронт событиями в user-activity (ADR-0054; user-activity/), статистика застройщика — dev-stats (ADR-0057). Продвижение — контекст promotion; буст наполняет консюмер ../consumers/promotion-boost.md по pin.promotion.purchase-changed.v1 (ADR-0060).

Индексы, хранение, безопасность

Аспект	Значение
Индексы	PK `pk_property_object_cards` (id); btree: `ix_property_object_cards_project_id`, `ix_property_object_cards_building_id`, `ix_property_object_cards_developer_id`, `ix_property_object_cards_layout_id`; ленточный композит `ix_property_object_cards_feed` (status, promotion_boost desc, developer_priority desc, popularity_score desc, published_at desc) where status = 'Published'; сортировки: `ix_property_object_cards_price` (status, price), `ix_property_object_cards_published_at` (status, published_at desc), `ix_property_object_cards_popularity` (status, popularity_score desc); фильтры: `ix_property_object_cards_type_name`, `ix_property_object_cards_rooms_count`, `ix_property_object_cards_availability`, `ix_property_object_cards_delivery_date`
Поиск	полнотекст — Elasticsearch-проекция `property-objects` (ADR-0059); в PostgreSQL FTS-колонок/GIN нет
Партиционирование / retention	none — карточек сотни тысяч максимум (simplicity-first, ADR-0056); `Delisted` очищаются job-ом через 30 дней
Concurrency	оптимистическая блокировка — консюмеры разных топиков могут писать одну строку; retry по конфликту
Permissions / PII	Чтение — public с гейтом ленты: авторизованный токен или реферальная cookie; для гостя без гейта — 401. Поле `AgentCommission` сериализуется в ответ только при permission `catalog.commissions.view` (агент/руководитель агентства; каталог permissions — `identity/domain/permission.md`). PII в карточке нет
Audit	Не требуется (read-проекция); происхождение значений трассируется `SourceSnapshot` + `*SyncedAt`

Конкурентность источников и согласованность

Одну строку карточки пишут консюмеры разных топиков и внутренний пересчёт оверрайда; порядок между топиками не гарантирован, поэтому каждый источник обновляет только свои поля под своим guard-ом версии, а конфликт параллельных писателей разрешается оптимистической блокировкой с повтором проигравшего.

Писатель	Событие (топик) / триггер	Обновляемые поля	Guard монотонности	Поведение при отсутствии/устаревании
`chessboard`	`pin.chessboard.property-object-upserted.v1` / `pin.chessboard.building-upserted.v1`	структурные поля, `SourceSnapshot`, `PropertyObjectStatus`	`event.Version > SourceSnapshot.ChessboardVersion` (INV-4)	нет события объекта → карточки нет; проекта нет → карточка `Hidden` до прихода проекта (INV-2)
`invest-analytics`	`pin.invest-analytics.property-object-metrics.v1`	`Payback`/`Reliability`/`GrowthPercent`/`Rating`/`RentalIncomePerYear`	`AnalyticsAsOf` (водяной знак)	не синхронизировано → метрики `null`, блок доходности в UI скрыт
`rewards`	`pin.rewards.commission-rules.v1`	`AgentCommission`	`event.RuleVersion >= AgentCommission.RuleVersion` (INV-5)	комиссия не задана → VO `null`, блок комиссии не показывается
`catalog` (оверрайд)	пересчёт при мутации оверрайда (display-override.md)	эффективные `Title`/`Price`/`Badge`/`Rating`/…	пересчёт из последнего `SourceSnapshot` (INV-3)	снятие оверрайда → эффективные значения возвращаются к `SourceSnapshot`
`catalog` (ранжирование)	мутация правила (ranking-rule.md)	`DeveloperPriority`	каскад INV-5 ranking	правило снято → приоритет по каскаду (объект → проект → 0)
`promotion`	`pin.promotion.purchase-changed.v1`	`PromotionBoost`	сумма активных вкладов	лаг продвижения → буст устаревает (некритично для «Рекомендованные»)
`user-activity`	`pin.user-activity.property-object-view-ended.v1`	`PopularityViews`	«слепой» инкремент, fail-open	заморожен на `Delisted` (INV-7); потеря единичного просмотра допустима

Кто побеждает

Писатели не пересекаются по данным (каждый владеет своим набором полей), поэтому конфликта значений нет; при гонке за версию строки проигравший повторяет операцию и переприменяет свой guard (устаревшее событие после повтора идемпотентно пропускается). Любой пересчёт эффективных полей/статуса поднимает PropertyObjectCardRecomputedEvent в том же коммите → обновление поисковой проекции (../search/property-objects.md); окно рассинхронизации витрины и поиска — секунды–минуты (отдаётся признак свежести).

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

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

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

catalog-project-card.md — карточка проекта (агрегаты цен/количества объектов).
display-override.md — оверрайды; ranking-rule.md — DeveloperPriority; ../consumers/promotion-boost.md — PromotionBoost; ../search/property-objects.md — Elasticsearch-проекция.
Дома источников: chessboard/domain/property-object.md, invest-analytics/, rewards/domain/reward-rule.md.
ADR-0052 (tenancy: платформенные данные), ADR-0056 (simplicity-first), ADR-0059 (Elasticsearch), ADR-0054/0057 (просмотры).

Назначение​

Классификация​

Поля​

Enum PropertyObjectCardStatus (хранится как text)​

Enum PropertyObjectAvailabilityStatus — реплика; дом значений и переходов — chessboard/domain/property-object.md​

Value objects​

DeveloperRefModel / BuildingRefModel (owned) — ссылки id + имя​

PropertyObjectLayoutModel (owned) — планировочные характеристики​

PropertyObjectPayback (owned)​

PropertyObjectReliability (owned)​

PropertyObjectAgentCommission (owned) — денормализация правила rewards​

Модели JSONB (versioned)​

PropertyObjectSourceSnapshotDocument (jsonb, колонка source_snapshot, ContractVersion = 1)​

Связи​

Инварианты и переходы состояний​

Доменные и интеграционные события​

Индексы, хранение, безопасность​

Конкурентность источников и согласованность​

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

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