H-3729: GET /system-notifications/active

Co-Authored-By: Claude Opus 5.5 (1M context)

v2/swagger.yaml

@@ -79,6 +79,8 @@ tags:
     description: Methods for admin oversight of personal API tokens. Requires "api-tokens-admin" permission.
   - name: admin-employment
     description: Methods for administrative read-only access to employee employments, including external identifiers used by integrations. Requires "user-edit" permission.
+  - name: system-notifications
+    description: Methods for reading active HRBox system announcements (home page banner for portal administrators). Requires "admin-controls" permission.
 
 paths:
   /mobile/bind/{id}/{token}:
@@ -8264,6 +8266,63 @@ paths:
             Запись не найдена. Включает случаи обращения к записям,
             принадлежащим другим тенантам.
 
+  /system-notifications/active:
+    get:
+      tags: [system-notifications]
+      summary: Получить активные системные объявления
+      description: |
+        Возвращает постраничный список активных системных объявлений HRBox
+        (по умолчанию 20 на страницу, максимум 50). По умолчанию сортировка
+        по дате публикации, сначала новые. Используется для баннера
+        на главной странице портала.
+
+        Тело каждого объявления (`body_html`) рендерится из markdown на языке
+        профиля текущего пользователя с откатом на русский, если перевод
+        отсутствует, и очищается до ограниченного набора тегов: `p`, `br`,
+        `strong`, `em`, `del`, `ul`, `ol`, `li`, `a` (только `http`/`https`,
+        с `target="_blank" rel="noopener noreferrer"`). Если после очистки
+        текста не осталось, объявление всё равно попадает в выдачу
+        с пустым `body_html` — клиенты такие объявления не показывают.
+
+        Скрытие объявлений хранится только на стороне клиента (локально)
+        и не влияет на ответ этого метода.
+      operationId: systemNotificationsActive
+      parameters:
+        - name: per-page
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
+          description: Значение больше 50 урезается до 50.
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum:
+              - published_at
+              - -published_at
+          description: По умолчанию `-published_at`.
+      responses:
+        200:
+          description: Список активных объявлений.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/SystemNotification'
+                  _links:
+                    $ref: '#/components/schemas/_links'
+                  _meta:
+                    $ref: '#/components/schemas/_meta'
+        403:
+          description: |
+            У текущего пользователя отсутствует право `admin-controls`.
+
 components:
   securitySchemes:
     SessionAuth:
@@ -13830,6 +13889,31 @@ components:
         _meta:
           $ref: '#/components/schemas/_meta'
 
+    SystemNotification:
+      type: object
+      description: Системное объявление HRBox в баннере на главной странице портала.
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Идентификатор объявления.
+        body_html:
+          type: string
+          description: |
+            Текст объявления, отрендеренный из markdown в HTML на языке
+            профиля пользователя (откат на русский, если перевод отсутствует)
+            и очищенный до ограниченного набора тегов: `p`, `br`, `strong`,
+            `em`, `del`, `ul`, `ol`, `li`, `a` (только `http`/`https`,
+            с `target="_blank" rel="noopener noreferrer"`). Пустая строка,
+            если после очистки текста не осталось — такие объявления клиенты
+            не показывают.
+          example: "<p>Плановые работы <strong>1 октября</strong> с 02:00 до 04:00 МСК.</p>"
+        published_at:
+          type: string
+          format: date-time
+          description: Дата и время публикации, ISO 8601 со смещением.
+          example: "2026-09-24T16:30:04+03:00"
+
   parameters:
     boardDateTypeParam:
       in: query