GET /api/admin/notifications/templates — Список шаблонов уведомлений
Назначение
Администратор платформы просматривает каталог шаблонов уведомлений
(NotificationTemplateEntity) — страницу с фильтрами по
Kind/Locale/Status для экрана управления шаблонами. Owning-контекст — notifications, feature group
templates.
| Поле | Значение |
|---|
| Сервис/контекст | notifications |
| API area | admin |
| Feature group | templates |
| Статус | draft |
| Документ | docs/06-services/notifications/api/admin/list-templates.md |
Актор и доступ
| Проверка | Значение |
|---|
| Actor type | Operator(Admin) |
| Auth policy / Permissions | notifications.templates.view |
| Scope (RBAC) | платформа |
| Tenant isolation | не tenanted (платформенный каталог) |
| Audit | read |
HTTP-контракт
| Поле | Значение |
|---|
| Method | GET |
| Route | /api/admin/notifications/templates |
| Success status | 200 |
| Idempotency header | не применяется |
| Correlation | сквозной trace через заголовок traceparent |
Входные данные / параметры запроса
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения | Безопасность |
|---|
Paging | query | PagingQuery | Да | PageSize 1..100 (default 50), sort по Kind/Locale | — |
Kind | query | NotificationKind? | Нет | значение enum (фильтр) | — |
Locale | query | string? | Нет | BCP-47 (фильтр) | — |
Status | query | TemplateStatus? | Нет | Draft/Active/Archived (фильтр) | — |
Модель ответа — страница TemplateListItemModel
TemplateListItemModel — проекция NotificationTemplateEntity:
TemplateId (Guid), Kind (NotificationKind), Locale (string), Code (string), Name
(string), Status (TemplateStatus), ChannelCount (int, число ChannelTemplateEntity с IsEnabled),
IsSystem (bool), Version (long), UpdatedAt (DateTimeOffset). Тело каналов в список не входит —
детально в update-template.md.
Алгоритм
Операцию выполняет администратор платформы; требуется право notifications.templates.view (нет →
FORBIDDEN). Проверяется корректность параметров: Paging в границах, Kind/Status — допустимые значения
enum (нарушение → VALIDATION_FAILED). Возвращается страница активных (не удалённых) шаблонов, отфильтрованных
по Kind/Locale/Status, с сортировкой по Kind, Locale; каждый элемент маппится в
TemplateListItemModel (ChannelCount — по включённым каналам шаблона).
Ошибки и failure modes
| Код | HTTP status | Условие | Сообщение | Retry |
|---|
FORBIDDEN | 403 | нет notifications.templates.view | «Недостаточно прав» | no retry |
VALIDATION_FAILED | 400 | Paging/фильтры вне границ | «Проверьте параметры» | no retry |
Полнота выборки и границы
- В выборку входят не удалённые шаблоны (
DeletedAt = null); Archived показываются только при явном
фильтре Status = Archived (для реверса/аудита), иначе экран управления оперирует Draft/Active.
- Фильтры комбинируются по «И» (
Kind ∧ Locale ∧ Status); ни один не обязателен.
- Пустой результат (нет шаблонов под фильтр, либо запрошена страница за пределами набора) — не ошибка:
200 с пустой страницей и корректными счётчиками пагинации.
ChannelCount считает только ChannelTemplateEntity с IsEnabled = true; тела каналов в список не входят.
Совместимость и наблюдаемость
- Новые фильтры/поля — additive. Logs:
templates-listed (число, фильтры); metrics:
notifications_templates_listed_total.
Acceptance criteria
- Given админ с
notifications.templates.view, when запрашивает список с фильтром Kind+Status,
then 200, только совпадающие не удалённые шаблоны, сортировка по Kind,Locale.
- Given фильтр не совпал ни с одним шаблоном, when запрос, then
200 с пустой страницей (не 404).
- Given
PageSize вне 1..100, when запрос, then 400 VALIDATION_FAILED.
- Given актор без
notifications.templates.view, when запрос, then 403 FORBIDDEN.
Обратные ссылки
Автоссылки: где используется этот документ.
Связанные документы