GET /api/admin/v1/buildings/{buildingId}/override — Просмотр оверрайда корпуса (admin)

Назначение

Возвращает администратору платформы картину корпусного оверрайда (BuildingDisplayOverride, display-override.md): исходные значения источника (снапшот карточки проекта), текущий оверрайд (если есть) и эффективные значения витрины — чтобы решить, какие поля переопределить.

Зачем в ответе контекст проекта

Корпусные поля (ComplexName/Stars/DeliveryDate/ReadinessPercent/Address/DistanceMinutes) поднимаются на карточку проекта и денормализуются в объекты недвижимости корпуса — поэтому ответ включает контекст проекта (ProjectId/ProjectName/ProjectCardStatus).

Metadata

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

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

Проверка	Значение
Actor type	ExternalSystem (администратор платформы через admin API; m2m client-credentials — ADR-0053)
Auth policy / Permissions	policy AdminSystemOnly (клиент pin-admin-system); каталожное соответствие — permission catalog.overrides.view
Scope (RBAC)	платформа (не tenanted — ADR-0052 п.3)
Audit	read-sensitive: Comment — internal; чтение логируется

HTTP-контракт

Поле	Значение
Method	GET
Route	/api/admin/v1/buildings/{buildingId}/override
Success status	200
Idempotency header	не применяется (чтение)
Correlation	сквозной trace через traceparent; X-Admin-User-Id (Guid админа) — обязателен

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

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

Модель ответа BuildingOverrideView

Поле	Тип	Обязательность	Источник	Masking	Описание
BuildingId	Guid	Да	route (подтверждён шагом 2)	—	Корпус.
BuildingName	string	Да	CatalogPropertyObjectCard.BuildingName (любой объект недвижимости корпуса)	—	Название корпуса для формы админки.
ProjectId	Guid	Да	CatalogPropertyObjectCard.ProjectId	—	Проект корпуса.
ProjectName	string	Да	CatalogProjectCard.Name	—	Эффективное название проекта (контекст формы).
ProjectCardStatus	string (enum ProjectCardStatus)	Да	CatalogProjectCard.Status	—	Видимость проекта.
PropertyObjectsInBuilding	int	Да	число объектов недвижимости корпуса (кроме Delisted)	—	Сколько объектов недвижимости затронет правка.
Source	BuildingOverrideSourceBlock	Да	CatalogProjectCard.SourceSnapshot	—	Исходные значения до оверрайда.
Override	BuildingOverrideBlock?	Нет (null — оверрайда нет)	BuildingDisplayOverride	—	Текущий оверрайд.
Effective	BuildingOverrideEffectiveBlock	Да	CatalogProjectCard (эффективные колонки)	—	Что видит витрина.

Модель BuildingOverrideSourceBlock (проекция ProjectSourceSnapshotDocument — дом catalog-project-card.md)

Поле	Тип	Обязательность	Источник	Masking	Описание
Name	string	Да	SourceSnapshot.Name	—	Исходное название проекта/комплекса (chessboard).
Address	string	Да	SourceSnapshot.Address	—	Исходный адрес.
Stars	short?	Нет	SourceSnapshot.Stars	—	Исходная звёздность.
DeliveryDate	DateOnly?	Нет	SourceSnapshot.DeliveryDate	—	Исходный срок сдачи.
ReadinessPercent	short?	Нет	SourceSnapshot.ReadinessPercent	—	Исходная готовность.
DistanceMinutes	int?	Нет	SourceSnapshot.DistanceMinutes	—	Исходные минуты до точки.
ChessboardVersion	long	Да	SourceSnapshot.ChessboardVersion	—	Версия источника.

Модель BuildingOverrideBlock (проекция BuildingDisplayOverride — дом display-override.md)

Поле	Тип	Обязательность	Источник	Masking	Описание
Id	Guid	Да	BuildingDisplayOverride.Id	—	Идентификатор оверрайда.
IsVisible	bool?	Нет	BuildingDisplayOverride.IsVisible	—	false — корпус скрыт (все объекты недвижимости → Hidden); null = не переопределено.
ComplexName	string?	Нет	BuildingDisplayOverride.ComplexName	—	—
Stars	short?	Нет	BuildingDisplayOverride.Stars	—	—
DeliveryDate	DateOnly?	Нет	BuildingDisplayOverride.DeliveryDate	—	—
ReadinessPercent	short?	Нет	BuildingDisplayOverride.ReadinessPercent	—	—
Address	string?	Нет	BuildingDisplayOverride.Address	—	—
DistanceMinutes	int?	Нет	BuildingDisplayOverride.DistanceMinutes	—	—
Comment	string?	Нет	BuildingDisplayOverride.Comment	internal — только admin-область	Комментарий админа.
UpdatedAt	DateTimeOffset	Да	BuildingDisplayOverride.UpdatedAt	—	Последняя правка.
UpdatedByUserId	Guid?	Нет	UpdatedByUserId ?? CreatedByUserId	—	Автор последней правки.
Version	long	Да	BuildingDisplayOverride.Version	—	Для optimistic-check в PUT.

Модель BuildingOverrideEffectiveBlock (эффективные колонки CatalogProjectCard)

Поле	Тип	Обязательность	Источник	Masking	Описание
Name	string	Да	CatalogProjectCard.Name	—	Эффективное название комплекса.
Address	string	Да	CatalogProjectCard.Address	—	—
Stars	short?	Нет	CatalogProjectCard.Stars	—	—
DeliveryDate	DateOnly?	Нет	CatalogProjectCard.DeliveryDate	—	—
ReadinessPercent	short?	Нет	CatalogProjectCard.ReadinessPercent	—	—
DistanceMinutes	int?	Нет	CatalogProjectCard.DistanceMinutes	—	—

Алгоритм

1. Контекст и доступ. Актор — администратор платформы (admin API, m2m-клиент pin-admin-system, policy AdminSystemOnly); заголовок X-Admin-User-Id логируется как admin-доступ. Идемпотентность к чтению не применяется.
2. Проверка входа. BuildingId != Guid.Empty, AdminUserId != Guid.Empty; иначе ValidationError. Существование корпуса в витрине: корпус существует, только если в catalog.property_object_cards есть хотя бы один объект недвижимости с этим BuildingId (объект недвижимости — носитель BuildingId); ни одного объекта → CATALOG_BUILDING_NOT_FOUND (404). Граничный случай: все объекты корпуса Delisted (живых нет) — корпус считается несуществующим для витрины → CATALOG_BUILDING_NOT_FOUND (404). Состояние чтение не ограничивает (Published/Hidden объекты показываются — админ должен видеть скрытое).
3. Что читаем. Карточку проекта корпуса (по ProjectId любого объекта корпуса; существование гарантирует INV-2 ProjectFirst), живой оверрайд корпуса BuildingDisplayOverride (может отсутствовать → блок Override = null) и число объектов недвижимости корпуса в статусе, отличном от Delisted.
4. Маппинг. Source.* ← снапшот источника карточки проекта (SourceSnapshot); Override.* ← оверрайд корпуса (или null); Effective.* ← эффективные колонки карточки проекта; BuildingName ← название корпуса из объекта; PropertyObjectsInBuilding ← счётчик шага 3.
5. Результат. BuildingOverrideView; freshness — актуальная строка (source of truth оверрайдов — этот контекст).

Диаграмма

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
ValidationError	400	Пустой BuildingId/X-Admin-User-Id	Ошибка валидации запроса	no retry
UNAUTHORIZED	401	Нет/просрочен m2m client-credentials токен	Требуется авторизация	no retry
FORBIDDEN	403	Клиент не pin-admin-system / нет catalog.overrides.view	Доступ запрещён	no retry
CATALOG_BUILDING_NOT_FOUND	404	Ни одного живого объекта недвижимости с таким BuildingId в catalog.property_object_cards (нет объектов или все Delisted)	Корпус не найден в каталоге	no retry

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

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

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

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

• API (3): Catalog Admin API — реестр методов и общие правила области, GET /api/admin/v1/lots/{propertyObjectId}/override — Просмотр оверрайда объекта недвижимости (admin), PUT /api/admin/v1/buildings/{buildingId}/override — Создание/изменение оверрайда корпуса (admin)
• registries (1): Реестр API-методов PIN

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

• Сущности: display-override.md, catalog-project-card.md, catalog-property-object-card.md.
• Мутация: put-building-override.md; объект недвижимости: get-property-object-override.md.
• ADR-0053.