GET /api/admin/v1/property-object-types — Список настроек типов объектов недвижимости (admin)
Назначение
Отдаёт администратору платформы полный список настроенных типов объектов недвижимости — агрегатов
PropertyObjectTypeConfig (nullable-оверрайды платформенной
модели по группе планировок LayoutGroup) для таба «Настройка объектов недвижимости → типы объектов
недвижимости». Для каждого типа дополнительно отдаётся число помесячных оверрайдов
(monthOverridesCount) — админка показывает бейдж заполненности. Типы, для которых настройка не
создавалась, в список не входят (расчёт для них идёт по платформенному уровню); справочник всех групп
планировок админка берёт у chessboard.
| Поле | Значение |
|---|
| Сервис/контекст | invest-analytics |
| API area | admin (ADR-0053) |
| Feature group | admin-property-object-types |
| Статус | draft |
| Документ | docs/06-services/invest-analytics/api/admin/list-property-object-types.md |
Актор и доступ
| Проверка | Значение |
|---|
| Actor type | Operator(Admin) — администратор платформы (доступ через admin API, m2m client-credentials) |
| Auth policy / Permissions | policy AdminSystemOnly (клиент pin-admin-system); каталожное соответствие — permission invest-analytics.property-object-types.view |
| Scope (RBAC) | платформа |
| Tenant isolation | не применяется — платформенная настройка (ADR-0052 п.3) |
| Audit | read: не аудируется (PII нет) |
HTTP-контракт
| Поле | Значение |
|---|
| Method | GET |
| Route | /api/admin/v1/property-object-types |
| Success status | 200 |
| Idempotency header | не применяется (safe GET) |
| Correlation | сквозной trace через traceparent; X-Admin-User-Id — обязателен |
Входные данные / параметры запроса
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения | Безопасность |
|---|
AdminUserId | header X-Admin-User-Id | Guid | Да | != Guid.Empty | контекст admin-области |
Пагинация не применяется — таблица маленькая (единицы–десятки типов на всю платформу,
../../domain/property-object-type-config.md); отдаётся полный список.
Модель ответа PropertyObjectTypeListResult
| Поле | Тип | Обязательность | Источник | Masking | Описание |
|---|
items | IReadOnlyList<PropertyObjectTypeItemModel> | Да (может быть пуст) | проекция | — | Настроенные типы, сортировка по name ASC. |
PropertyObjectTypeItemModel
Проекция полей дома property-object-type-config.md (null =
«наследовать от платформы»; семантика коэффициентов —
economic-model-config.md):
| Поле | Тип | Обязательность | Источник | Masking | Описание |
|---|
groupId | long | Да | PropertyObjectTypeConfig.Id | — | Группа планировок (натуральный ключ, chessboard). |
name | string | Да | .Name | — | Отображаемое имя типа («Стандарт», «Люкс»…). |
marketPremium | decimal? | Нет | .MarketPremium | — | Оверрайд надбавки к прайсу. |
priceGrowthMonthly | decimal? | Нет | .PriceGrowthMonthly | — | Оверрайд роста цены. |
dailyRentM2 | decimal? | Нет | .DailyRentM2 | — | Оверрайд аренды. |
rentGrowthMonthly | decimal? | Нет | .RentGrowthMonthly | — | Оверрайд роста аренды. |
expenseShare | decimal? | Нет | .ExpenseShare | — | Оверрайд доли расходов. |
appreciationTaxMonthly | decimal? | Нет | .AppreciationTaxMonthly | — | Легаси-оверрайд (в расчёте не участвует). |
ebitdaTaxMonthly | decimal? | Нет | .EbitdaTaxMonthly | — | Легаси-оверрайд. |
occupancy | decimal? | Нет | .Occupancy | — | Оверрайд заполняемости. |
horizonMonths | int? | Нет | .HorizonMonths | — | Оверрайд горизонта. |
monthOverridesCount | int | Да | count по property_object_type_month_overrides.GroupId | — | Число помесячных оверрайдов типа. |
version | long | Да | .Version | — | Ревизия (для expectedVersion в PUT). |
updatedAt | DateTimeOffset | Да | .UpdatedAt | — | Последняя правка. |
updatedByUserId | Guid? | Нет | .UpdatedByUserId | — | Актор последней правки. |
Алгоритм
- Контекст и доступ. Администратор платформы через admin API (policy
AdminSystemOnly); scope —
платформа; право invest-analytics.property-object-types.view; заголовок X-Admin-User-Id.
- Проверка входа.
X-Admin-User-Id непустой — иначе ValidationError. Параметров у списка нет.
- Что читаем. Полный список настроенных типов, отсортированный по
name ASC; для каждого типа —
число его помесячных оверрайдов (агрегированный счётчик по GroupId, сами children не материализуются).
- Правила и маппинг. Каждый агрегат проецируется в
PropertyObjectTypeItemModel;
monthOverridesCount — счётчик из проекции (0, если оверрайдов нет).
- Результат. Список настроенных типов; пустой список — валидный ответ (ни один тип не настроен,
расчёты идут по платформенному уровню).
Ошибки и failure modes
| Код | HTTP status | Условие | Сообщение | Retry |
|---|
ValidationError | 400 | Отсутствует/пустой X-Admin-User-Id | Ошибка валидации запроса | no retry |
FORBIDDEN | 403 | Клиент не pin-admin-system / нет policy | Доступ запрещён | no retry |
Совместимость и наблюдаемость
- Additive-поля item-модели — без breaking; удаление/переименование — breaking. Если типов станет
много (сотни) — пагинация добавляется additive (
page/pageSize c дефолтом «всё»), текущий контракт
не ломается.
- Logs:
admin-property-object-types-listed (adminUserId, count). Metrics:
invest_analytics_admin_operations_total{operation="list-property-object-types"}. Traces — сквозной trace
через traceparent.
Acceptance Criteria
- Given настроено 2 типа объектов недвижимости, When администратор шлёт GET, Then
200 с
items из 2 элементов, отсортированных name ASC; у каждого — version и monthOverridesCount.
- Given тип имеет 5 помесячных оверрайдов, When GET, Then его
monthOverridesCount = 5
(children не материализуются — только агрегированный счётчик).
- Given ни один тип не настроен, When GET, Then
200 с items = [] — валидный ответ (расчёты
идут по платформенному уровню).
- Given заголовок
X-Admin-User-Id отсутствует/пуст, When GET, Then 400 ValidationError.
- Given клиент не
pin-admin-system, When GET, Then 403 FORBIDDEN.
Обратные ссылки
Автоссылки: где используется этот документ.
Связанные документы