Системные объявления

Системное объявление — это баннер, который администратор пишет один раз, а видят его все пользователи установки: о плановых работах, о сбое, о новой версии или о предстоящем событии.

Баннер появляется над всей рабочей областью, а не внутри отдельной страницы. Это сделано намеренно: человек, который в момент публикации сидит в редакторе моков, должен увидеть предупреждение о работах там же, не переходя никуда.

Четыре вида объявлений

Вид определяет и оформление баннера, и то, можно ли закрыть его навсегда.

Вид	Когда использовать	Что происходит после «Скрыть»
Плановые работы	Установка будет недоступна в известное время	Вернётся в следующей сессии, пока окно не кончилось
Сбой в работе	Что-то сломано прямо сейчас	Вернётся в следующей сессии, пока окно не кончилось
Что нового	Вышла новая версия, изменилось поведение	Не вернётся
Объявление	Вебинар, дедлайн, организационная новость	Не вернётся

Плановые работы и сбой возвращаются не по ошибке. Человек, закрывший баннер в понедельник, всё ещё должен узнать во вторник утром, что платформа остановится в полдень.

В пределах одной установки «Скрыть» запоминается на пользователя, а не на браузер: при входе в эту установку с двух компьютеров закрывать баннер дважды не придётся. Отдельные установки Desktop хранят состояние сообщений Cloud локально каждая у себя.

Как опубликовать

Публиковать может администратор. Объявление увидят все, кому оно адресовано, поэтому и публикация, и снятие записываются в журнал аудита — видно, кто и что повесил.

curl -X POST http://localhost:5770/api/v1/admin/announcements \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "maintenance",
    "title": "Плановые работы",
    "body": "Платформа будет недоступна с 02:00 до 03:00 UTC. Данные не пострадают.",
    "link_label": "Подробнее",
    "link_url": "https://status.example.com/maintenance/1",
    "starts_at": "2026-09-04T02:00:00Z",
    "ends_at": "2026-09-04T03:30:00Z"
  }'

Ответ содержит id — он понадобится, чтобы снять объявление.

Что важно знать про поля:

title и body — обычный текст. Разметка не отрисовывается, а показывается буквами. Пишите предложения, а не HTML.
Ссылка — это пара. Нужны и link_label, и link_url: подпись без адреса — мёртвая кнопка, адрес без подписи — непонятный клик. Адрес принимается только http:// или https://.
Окно задаётся в UTC. Баннер сам появляется в starts_at и сам исчезает в ends_at. Публиковать заранее — нормально: до начала окна объявление никому не показывается.
Заголовок — до 160 символов, текст — до 2000.

Если что-то не так, ответ назовёт конкретное поле, а не отправит вас искать:

{"error":"invalid_announcement","message":"announce: invalid announcement: the link must be an http(s) address"}

Кому показывать

По умолчанию объявление видят все — это обычный случай, и для него ничего указывать не нужно. Когда нужно сузить, есть три независимых фильтра:

{
  "audience_roles": ["admin"],
  "audience_namespaces": ["prod"],
  "audience_surfaces": ["desktop"]
}

audience_roles — только пользователи с такой ролью.
audience_namespaces — только те, кто смотрит в это пространство имён. Человек, не имеющий к нему доступа, объявления не увидит, даже если попробует его запросить.
audience_surfaces — platform (веб-интерфейс) или desktop (настольное приложение).

Пустой список означает «всем». Фильтры складываются: объявление с ролью admin и пространством prod увидит только администратор, работающий в prod.

Отбор происходит на сервере. Объявление, которое вам не адресовано, до вашего браузера не доезжает вовсе.
«Скрыть» тоже работает только с действующим объявлением, адресованным вам: знания чужого ID недостаточно, чтобы его скрыть.

Как снять

Работы закончились раньше, или объявление оказалось ошибочным:

curl -X DELETE http://localhost:5770/api/v1/admin/announcements/$ID \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Это не удаление: то, что люди уже видели, остаётся в записях, а снятие попадает в аудит.

Посмотреть, что запланировано и что уже отработало:

curl http://localhost:5770/api/v1/admin/announcements \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Через AI-агента

Агент, который останавливает установку на обслуживание, должен уметь предупредить пользователей сам — иначе его окно работ превращается в молчаливый сбой. Для этого есть инструменты MCP:

announcements_publish — повесить объявление. Обязательны только kind, title и body: если окно не указано, оно берётся как «сейчас плюс шесть часов», чего хватает для сообщения о сбое.
announcements_list — посмотреть, что висит, и найти id.
announcements_withdraw — снять по id, когда работы закончены.

Установки без выхода в интернет

Объявления хранятся в самой установке. Изолированному контуру не нужно никуда дотягиваться, чтобы предупредить своих пользователей о работах, — механика работает целиком локально, на PostgreSQL и на SQLite одинаково.

Когда десктоп подключён к Cloud, он также показывает сообщения, адресованные активному авторизованному профилю. Последние успешно полученные сообщения Cloud остаются видны без сети, пока в этом профиле сохранён вход. При переключении профиля или выходе сообщения прежнего профиля скрываются; сообщения самой локальной установки остаются видны. Если скрыть сообщение Cloud в одном профиле, в другом оно не будет скрыто.