GET /api/developers/v1/promotion-packages — Доступные пакеты продвижения

Назначение

Возвращает менеджеру компании витрину платформенных пакетов продвижения (PromotionPackage Status=Active, promotion-package.md) — экран «Продвижение» ЛК: пакеты «продвигать проект чаще» / «продвигать объекты проекта чаще» + продвижение постов ленты; покупка без оплаты — решение №10.

Metadata

Поле	Значение
Сервис/контекст	promotion
API area	developers
Feature group	promotions
Статус	draft
Документ	docs/06-services/promotion/api/developers/list-promotion-packages.md

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

Проверка	Значение
Actor type	User (менеджер компании — JWT identity)
Auth policy / Permissions	permission promotion.packages.view в scope организации
Scope (RBAC)	организация
Record-level	не применяется
Tenant isolation	пакеты не tenanted (каталог платформы, ADR-0052 п.3); актор всё равно принадлежит компании (для feature flag и телеметрии)
Audit	none (чтение платформенного каталога)

HTTP-контракт

Поле	Значение
Method	GET
Route	/api/developers/v1/promotion-packages
Success status	200
Idempotency header	не применяется (чтение)
Correlation	сквозной trace через заголовок traceparent

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

Поле	Источник	Тип	Обязательность	Валидация / Ограничения	Безопасность
Kind	query	string? (enum PromotionPackageKind)	Нет	∈ {ProjectBoost, PropertyObjectBoost, PostBoost}; null — все	—

Пагинация не применяется: активных пакетов — единицы/десятки (SEED-каталог платформы), отдаётся контейнер целиком.

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

Поле	Тип	Обязательность	Источник	Masking	Описание
Items	PromotionPackageItem[]	Да (может быть пустым)	активные пакеты	—	Активные пакеты.
PurchaseEnabled	bool	Да	feature flag promotion.enabled	—	Доступна ли покупка (флаг «скрыть покупку до готовности»).

Модель PromotionPackageItem (проекция PromotionPackage)

Поле	Тип	Обязательность	Источник	Masking	Описание
Id	Guid	Да	PromotionPackage.Id	—	Пакет.
Code	string	Да	PromotionPackage.Code	—	Стабильный код (project-boost-week).
Name	string	Да	PromotionPackage.Name	—	Название.
Description	string?	Нет	PromotionPackage.Description	—	Маркетинговый текст.
Kind	string (enum PromotionPackageKind)	Да	PromotionPackage.Kind	—	ProjectBoost / PropertyObjectBoost / PostBoost.
BoostWeight	int	Да	PromotionPackage.BoostWeight	—	Вес буста.
DurationDays	int	Да	PromotionPackage.DurationDays	—	Срок действия.
MaxTargetsPerPurchase	int?	Нет	PromotionPackage.MaxTargetsPerPurchase	—	Лимит целей (PropertyObjectBoost/PostBoost; null при ProjectBoost).
PriceAmount	decimal	Да	PromotionPackage.Price.Amount	—	Прейскурант (информационно; оплата не требуется — решение №10).
PriceCurrencyId	short	Да	PromotionPackage.Price.CurrencyId	—	Ссылка на запись справочника валют handbook (RUB — ADR-0048); display-код/знак клиент берёт из lookup справочника.

Алгоритм

Тривиальное чтение витрины. Операцию выполняет менеджер компании (permission promotion.packages.view). Вход — необязательный фильтр Kind ∈ enum (иначе ValidationError). Отобрать активные пакеты (Status = Active, архив и черновики исключены) с фильтром по Kind, сортировка по Kind, затем BoostWeight (детерминированный порядок при равенстве — по Code). Поля пакета маппятся в PromotionPackageItem (Price → PriceAmount/PriceCurrencyId); PurchaseEnabled — из feature flag promotion.enabled. Результат — PromotionPackageListResult, 200.

Граничные случаи. Нет активных пакетов (или под фильтр Kind ничего не подошло) → 200 с пустым Items (не ошибка). При promotion.enabled = false пакеты всё равно отдаются, но PurchaseEnabled = false — витрина видна, кнопка покупки скрыта/заблокирована; сама покупка в этом режиме вернёт PROMOTION_DISABLED (purchase-promotion.md).

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
ValidationError	400	Невалидный Kind	Ошибка валидации запроса	no retry
UNAUTHORIZED	401	Нет/просрочен JWT	Требуется авторизация	no retry
FORBIDDEN	403	Нет permission promotion.packages.view	Доступ запрещён	no retry

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

• Новые optional поля item-а (будущие платёжные атрибуты) — additive; удаление/переименование — breaking.
• Logs: promotion-packages-listed (tenantId актора, count); metrics: promotion_operations_total{operation="list-promotion-packages"}; traces — сквозной trace через traceparent. Dashboard promotion-overview.

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

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

• Домен (CQRS) (1): Entity / Aggregate: PromotionPackage
• API (6): GET /api/admin/v1/promotion-packages — Управленческий список пакетов (admin), GET /api/developers/v1/promotions — Мои покупки продвижения, POST /api/admin/v1/promotion-packages — Создание пакета продвижения (admin), POST /api/developers/v1/promotions — Покупка пакета продвижения (без оплаты), POST /api/developers/v1/promotions/{purchaseId}/cancel — Отмена покупки продвижения, PUT /api/admin/v1/promotion-packages/{packageId} — Изменение/публикация/архивация пакета (admin)
• Use Cases (1): UC-PRM-002. Администратор управляет пакетами продвижения
• registries (1): Реестр API-методов PIN

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

• Сущность: promotion-package.md (дом полей, статусы).
• Покупка: purchase-promotion.md; мои покупки: list-my-promotions.md; admin CRUD пакетов — ../admin/create-promotion-package.md.
• Решение №10 technical-assignment.md (оплата отложена); ADR-0060.