GET /api/v1/catalog/filters — Справочники значений фильтров

Назначение

Отдаёт значения для панели «Дополнительные фильтры» лент проектов и объектов недвижимости: доступные типы объектов, классы, регионы, города, статусы строительства, варианты комнатности, глобальные границы цен и список сортировок. Возвращает только значения, реально присутствующие в опубликованных (Published) карточках, плюс статические enum-ы — чтобы в UI не было пустых фильтров. Вызывается один раз при открытии панели; доступен и гостю (границы цен для гостя округляются — MASK-PRICE, README.md). Источники значений — витринные проекции catalog-project-card и catalog-property-object-card.

Источник гео-значений

Своей реплики справочника handbook (регионы/города) у каталога нет: regions/cities строятся distinct-ом пар (RegionId, RegionName) / (CityId, CityName) по проекциям — id и display-имена приходят денормализованными в снапшотах событий chessboard.

Metadata

Поле	Значение
Сервис/контекст	catalog
API area	public
Feature group	feed
Статус	draft

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

Проверка	Значение
Actor type	Guest / RefGuest / User (без гейта)
Auth policy / Permissions	none
Scope	платформа
Tenant isolation	не применяется (платформенная витрина)
Audit	none

HTTP-контракт

Поле	Значение
Method	GET
Route	/api/v1/catalog/filters
Success status	200
Idempotency	не применяется (safe GET)
Correlation	OpenTelemetry trace (traceparent)

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

Поле	Источник	Тип	Обязательность	Валидация / Ограничения	Безопасность
Kind	query	ProjectKind?	Нет	enum ResidentialComplex/ApartHotel; сужает справочники до ленты /lots или /hotels; отсутствует — по всем Published	—
ActorClass	identity middleware	Guest/RefGuest/User	Да	невалидный токен → 401	определяет MASK-PRICE для priceBounds

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

Поле	Тип	Обязательность	Источник	Masking	Описание
kinds	IReadOnlyList<FilterOptionModel>	Да	distinct Kind опубликованных проектов	—	Типы проектов (ЖК/отель).
propertyClasses	IReadOnlyList<FilterOptionModel>	Да	distinct PropertyClass проектов	—	Классы (фильтр «класс»).
constructionStatuses	IReadOnlyList<FilterOptionModel>	Да	distinct ConstructionStatus проектов	—	Статусы строительства.
regions	IReadOnlyList<RegionOptionModel>	Да	distinct (RegionId,RegionName) опубликованных проектов, по имени	—	Регионы (фильтр «регион»).
cities	IReadOnlyList<CityOptionModel>	Да	distinct (CityId,CityName) опубликованных проектов, по имени	—	Города (фильтр «город»).
propertyObjectTypeNames	IReadOnlyList<FilterOptionModel>	Да	distinct TypeName опубликованных объектов	—	Типы объектов (фильтр «тип» ленты объектов недвижимости).
roomsCounts	IReadOnlyList<short>	Да	distinct RoomsCount объектов, по возрастанию	—	Варианты комнатности (0 = студия).
priceBounds	NullableRange<decimal>	Да	минимальная / максимальная Price опубликованных объектов	MASK-PRICE (Guest: min↓/max↑ до 100 000 ₽)	Границы слайдера цены (ref-модель — README.md); null/null — каталог пуст.
sorts	IReadOnlyList<FilterOptionModel>	Да	статический список enum FeedSort (README.md)	—	Доступные сортировки для выпадающего списка.

FilterOptionModel

Поле	Тип	Обязательность	Описание
value	string	Да	Значение для query-параметра (enum-string / TypeName как есть).
label	string	Да	Отображаемый текст (ru): enum → словарь локализации API; TypeName → само значение.

RegionOptionModel

Поле	Тип	Обязательность	Описание
regionId	long	Да	RegionId — значение query-параметра regionId лент (ссылка на справочник handbook).
regionName	string	Да	RegionName — отображаемый текст опции.

CityOptionModel

Поле	Тип	Обязательность	Описание
cityId	long	Да	CityId — значение query-параметра cityId лент (ссылка на справочник handbook).
cityName	string	Да	CityName — отображаемый текст опции.

Алгоритм

1. Контекст и доступ. Актор без гейта — гость допустим; невалидный токен → 401. Idempotency неприменима (чтение).
2. Проверка входа. Kind ∈ enum {ResidentialComplex, ApartHotel} — иначе ValidationError (400). Существование/состояние проверять нечего: пустой каталог — валидный ответ с пустыми списками.
3. Сбор справочников. По опубликованным карточкам собрать уникальные значения: из проектов — типы, классы, статусы строительства, пары (RegionId, RegionName) и (CityId, CityName) (карточки с нерезолвленным гео — RegionId/CityId = null — в значения фильтров не попадают; у Published гео резолвлено — INV-PRJ-3 источника); из объектов недвижимости — типы объектов, варианты комнатности (по возрастанию), минимальную и максимальную цену. При заданном Kind выборка сужается до соответствующей ленты.
4. Сборка ответа. Enum-значения превращаются в FilterOptionModel через словарь локализации API (Comfort → «Комфорт», InProgress → «Строится» и т.д.); TypeName — как есть; sorts — статический список FeedSort. Для гостя над priceBounds применяется MASK-PRICE.
5. Результат. CatalogFiltersModel → 200. Консистентность — eventual; свежесть некритична (справочник панели фильтров), допустим HTTP-кэш Cache-Control: public, max-age=300 (значение — конфигурация).

Диаграмма

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
— (auth)	401	Передан невалидный/просроченный токен	без тела схемы	re-login
ValidationError	400	Kind вне enum	Список ошибок полей	no retry

Пустой каталог — не ошибка

200 со всеми пустыми списками и priceBounds = null/null — валидный ответ (UI прячет фильтры).

Acceptance Criteria

• Непустой каталог. Дано опубликованные проекты классов Comfort/Business и объекты недвижимости с комнатностью 0/1/2. Когда авторизованный пользователь открывает панель. Тогда propertyClasses содержит только Comfort и Business (реально присутствующие), roomsCounts = [0,1,2] по возрастанию, priceBounds — фактические min/max, sorts — полный статический список FeedSort.
• Гео-опции из проекций. Дано опубликованные проекты одного региона в двух городах. Когда собираются справочники. Тогда regions содержит одну пару (regionId, regionName), cities — две; регионы и города, у которых нет опубликованных проектов, в списках не появляются (статического справочника регионов у каталога нет).
• Сужение по Kind. Дано Kind = ApartHotel. Когда собираются справочники. Тогда значения берутся только из лент апарт-отелей; значения, присущие лишь ЖК, в списках не появляются.
• Гость — маскирование границ. Дано актор Guest. Когда возвращается priceBounds. Тогда min округлён вниз, max — вверх до 100 000 ₽ (MASK-PRICE); остальные списки без изменений.
• Пустой каталог. Дано нет опубликованных карточек. Когда приходит запрос. Тогда 200 со всеми пустыми списками и priceBounds = null/null — не ошибка (UI прячет фильтры).
• Невалидный Kind. Дано Kind = Cottage. Когда приходит запрос. Тогда ValidationError (400), справочники не собираются.
• Свежесть. Дано только что опубликованный проект (лаг проекции консюмера). Когда клиент запросил фильтры. Тогда в пределах окна eventual-consistency новые значения могут отсутствовать; ответ кэшируется Cache-Control: max-age=300, расхождение сходится по мере догона проекции.

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

• Новые списки-справочники — additive; удаление списка или смена формата value — breaking. Локализация label — не контракт (фронт использует value).
• Logs: Kind, размеры списков; metrics — catalog_filters_requests_total, latency histogram; traces/dashboard — общие правила area (README.md).

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

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

• API (4): Catalog Public API — реестр методов и общие правила, GET /api/v1/lots — Лента объектов недвижимости, GET /api/v1/projects — Лента проектов, GET /api/v1/projects/{id}/lots — Ассортимент проекта/отеля
• Консюмеры (1): Consumer: Chessboard Projection Sync (pin-catalog-chessboard-sync)
• registries (1): Реестр API-методов PIN

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

• Потребители: get-property-objects.md, get-projects.md, get-project-property-objects.md.
• Дома enum-ов: ../../domain/catalog-project-card.md (ProjectKind/PropertyClass/ConstructionStatus, гео-поля RegionId/RegionName/CityId/CityName), ../../domain/catalog-property-object-card.md (TypeName/RoomsCount).
• Ссылки на справочник: snapshot-модели гео — handbook/domain/snapshots.md.
• Общие правила area: README.md.