# Уведомления модуля в шапке

← [К обзору UI-вкладов](contributions.md)

`admin_extension.notifications` добавляет элементы в общий колокольчик панели
управления AVE.cms. Модуль не рисует ещё одну кнопку: система суммирует все
поставщики данных, показывает общий badge и единый список.

Уведомление здесь означает текущее состояние, требующее внимания: новые заказы,
непрочитанные обращения, просроченные напоминания. Это не Toast после действия и
не постоянный аудит событий.

## 1. Описание в `module.php`

```php
use App\Adminx\Reminders\Notifications;

'admin_extension' => array(
    'notifications' => array(
        'code' => 'overdue',
        'provider' => array(Notifications::class, 'data'),
        'permission' => 'view_reminders',
        'sort_order' => 30,
    ),
),
```

Право проверяется до вызова поставщика. Выключенный или деинсталлированный модуль
не участвует в общей сводке.

## 2. Provider

```php
<?php

namespace App\Adminx\Reminders;

defined('BASEPATH') || die('Direct access to this location is not allowed.');

use App\Common\Auth;

class Notifications
{
    public static function data()
    {
        $userId = (int) Auth::id();
        if ($userId < 1) {
            return array();
        }

        $count = Model::overdueCount($userId);
        if ($count < 1) {
            return array();
        }

        return array(array(
            'key' => 'reminders_overdue',
            'title' => 'Просроченные напоминания',
            'text' => 'Срок прошёл — требуют внимания',
            'url' => '/reminders?state=overdue',
            'count' => $count,
            'icon' => 'ti ti-alarm',
            'bg' => 'var(--red-100)',
            'fg' => 'var(--red-600)',
        ));
    }
}
```

Поставщик может вернуть список напрямую или `array('items' => $items)`. Если
элементов нет, возвращайте пустой массив.

## 3. Формат элемента

| Ключ | Назначение |
| --- | --- |
| `title` | Обязательный короткий заголовок. |
| `text` | Пояснение состояния. |
| `url` | Ссылка. Путь с `/` автоматически получает префикс панели управления. |
| `count` | Положительное число для общего и строкового badge. `0` скрывает элемент. |
| `icon` | Класс Tabler-иконки, по умолчанию `ti ti-bell`. |
| `bg`, `fg` | Фон плитки и цвет иконки. |
| `key` | Необязательный ключ агрегации в общей summary. |

Система автоматически ограничивает визуальный badge значением `99+`. Не
форматируйте `count` строкой и не включайте число повторно в `title`.

Используйте семантический цвет: red для просроченного/критичного, amber для
ожидающего действия, blue для нового информационного элемента, green для
положительного состояния. Цвет не должен быть единственным носителем смысла.

## 4. Производительность

Поставщик уведомлений выполняется при построении каждой страницы панели
управления.
Правильный provider делает один индексируемый `COUNT` для текущего пользователя
или использует краткоживущий кеш.

Нельзя:

- загружать все строки только ради `count()` в PHP;
- выполнять внешний HTTP-запрос;
- делать отдельный запрос на каждый объект;
- бросать исключение при штатно отсутствующей таблице опционального источника;
- показывать элементы с `count = 0`.

Для часто меняющегося счётчика инвалидируйте адресный кеш при изменении сущности,
а не очищайте весь кеш системы.

## 5. Прочитано и скрыто

Общий колокольчик не хранит состояние прочтения. Он каждый раз показывает то,
что вернул provider. Переход по ссылке сам по себе не уменьшает `count`.

Если модулю нужны «прочитано», «отложено» или персональное скрытие, создайте
собственную таблицу состояния и учитывайте её в поставщике. POST-действие такого
механизма должно проверять CSRF, право и принадлежность записи пользователю.

## 6. Несколько типов уведомлений

Один provider может вернуть несколько строк, например отдельно критичные и
обычные задачи. Можно также объявить список описаний уведомлений с разными
правами и поставщиками. Задавайте уникальные `code` и `key`, а `sort_order` используйте
для предсказуемого порядка между модулями.

## Проверка

- без права поставщик не выполняется;
- нулевой результат не оставляет пустую строку;
- общий badge равен сумме `count` всех видимых элементов;
- относительная ссылка ведёт в текущую панель управления;
- поставщик учитывает текущего пользователя и выполняет индексируемый запрос;
- отключение модуля убирает его строки и уменьшает общий badge;
- ошибки источника не ломают шапку и диагностируются без раскрытия секретов.