Документация: Электронная очередь (Electronic Queue)

Задача https://e-comexpert.planfix.ru/task/79102/?comment=63813692

Требования https://docs.google.com/document/d/1JYbb9qtUsQtoZLgwHUHmoXprcgkEZsqQYJ-sWx8TNC8/edit?tab=t.0

* зачеркнутое на данный момент не реадизовано

Система электронной очереди предназначена для управления потоком клиентов в пунктах выдачи (складах). Система включает в себя клиентский терминал для выбора услуги, ТВ-панель для информирования клиентов и интерфейс менеджера/кладовщика для обработки заказов.

1. Авторизация и доступ (v2)

В обновленной системе (v2) произошел переход от HTTP-авторизации к стандартной авторизации 1С-Битрикс.

1.1. Общий вход

Доступ к разделу /queue/ ограничен параметром define("NEED_AUTH", true). При попытке входа неавторизованный пользователь будет перенаправлен на стандартную форму авторизации Битрикс.

1.2. Меню выбора страницы

После авторизации на главной странице /queue/index.php отображается меню выбора интерфейса. Доступность пунктов меню регулируется правами пользователя (операциями):

Менеджер (v2): Доступ по операции queue_manager.
Терминал: Доступ по операции queue_terminal.
TV: Доступ по операции queue_tv.
Склад: Доступ для определенных логинов (skladh2-051 и системные админы).
Менеджер (админ): Доступ по операции manage_queue.

1.3. Настройка прав (Операций)

Настройка прав доступа осуществляется в административной панели Битрикс:

Перейдите в Настройки -> Пользователи -> Уровни доступа.
Создайте или отредактируйте уровень доступа (например, "Менеджер очереди").
На вкладке Включаемые операции отметьте необходимые операции (например, queue_manager).
Назначьте этот уровень доступа соответствующей группе пользователей.

2. Структура данных (Highload-блоки)

Для работы очереди используются следующие Highload-блоки:

Терминал: Типы очереди (ElectronicQueueTypes)

Определяет категории услуг, доступные в терминале.

UF_NAME (Строка): Название типа (например, "Выдача заказов").
UF_LETTERS (Строка, множ.): Набор префиксов талонов (например, A, G, K).
UF_USER_GROUPS (Группа пользователей): Группа менеджеров, привязанная к этому типу.

Терминал: Кнопки (ElectronicQueueButtons)

Связывает типы очередей с конкретными складами и задает приоритет.

UF_NAME (Строка): Текст на кнопке терминала.
UF_QUEUE_TYPE (Привязка к HL): Тип очереди.
UF_STORE_ID (Склад): Склад, на котором отображается кнопка.
UF_PRIORITY (Число): Приоритет обслуживания (чем меньше число, тем выше приоритет).

Терминал: Окна (ElectronicQueueWindows)

Настройка рабочих мест (окон) выдачи.

UF_NAME (Строка): Название окна (например, "Окно 1").
UF_NUMBER (Число): Порядковый номер окна.
UF_STORE_ID (Склад): Привязка к конкретному складу.
UF_QUEUES (Привязка к HL): Типы очередей, которые обслуживаются данным окном.
UF_ACTIVE (Да/Нет): Активность окна.

Терминал: Занятые окна (ElectronicQueueBusyWindows)

Отслеживает текущее состояние окон в реальном времени.

UF_USER_ID (Пользователь): Менеджер, работающий в окне.
UF_WINDOW_ID (Привязка к HL): Окно, в котором работает менеджер.
UF_TICKET (Строка): Номер талона, который сейчас обслуживается (null, если окно готово к приему).

Терминал: Пенальти (ElectronicQueuePenalties)

Система коэффициентов для менеджеров.

UF_USERS (Пользователь, множ.): Список менеджеров, к которым применяется правило.
UF_PENALTIES (Таблица): Массив правил. Каждое правило содержит:
- UF_SECTIONS (Разделы): Разделы каталога товаров.
- UF_ELEMENTS (Элементы): Конкретные товары.
- UF_QUEUE_TYPE (Тип очереди): Типы очередей.
- UF_PENALTY (Число): Значение штрафа.

Терминал: Журналирование сессий (ElectronicQueueLog)

История действий пользователей.

UF_USER_ID (Пользователь): Кто совершил действие.
UF_EVENT_TYPE (Список): LOGIN (Вход), LOGOUT (Выход), LOGIN_WINDOW (Вход в окно), LOGOUT_WINDOW (Выход из окна).
UF_DATETIME (Дата/Время): Момент события.

Терминал: Счетчик талонов (ElectronicQueueCounter)

Генерация порядковых номеров талонов.

UF_STORE_ID (Склад): Склад.
UF_QUEUE_TYPE (Тип очереди): Тип очереди.
UF_DATE (Дата): Текущий день.
UF_TICKET_COUNT (Число): Последний выданный номер.

3. Общий функционал и логика работы

3.1. Создание талона

Талон создается через терминал (выбор кнопки) или автоматически.

Номер талона генерируется на основе UF_LETTERS из типа очереди.
Система использует настраиваемый набор букв (например, А, Г, К, Л, М) для исключения созвучности.

3.2. Выбор окна и готовность (managerv2.php)

При входе менеджер выбирает окно.
Кнопка "Принять нового клиента" (data-type="setLink") теперь не назначает талон принудительно, а сигнализирует о готовности окна:
- При нажатии поле UF_TICKET в HL ElectronicQueueBusyWindows устанавливается в null.
- Цвет кнопки меняется: Серый (по умолчанию) — окно готово принять клиента; Красный — талон уже назначен и находится в обработке.
Автоматическое назначение происходит только когда окно "свободно" (UF_TICKET is null).

3.3. Приоритетность и распределение (Ticket::assign)

Логика выбора талона:

Иерархия приоритетов: Сначала обрабатываются типы очередей с наименьшим значением UF_PRIORITY в HL ElectronicQueueButtons (например, Юр. лица — 1, Кредит — 2, Обычные — 3).
Готовность заказа: Внутри одного типа очереди приоритет отдается талонам с UF_READY_HIPPING = true (заказ собран).
FIFO: При прочих равных выбирается самый старый талон по времени создания.
Выбор менеджера:
- Используется алгоритм Round-Robin по количеству обслуженных талонов за текущий день.
- Учитываются пенальти: приоритет менеджера снижается на величину штрафа, если в заказе есть соответствующие товары/разделы.

4. Доработки терминала

4.1. Таймер бездействия

На экранах ввода данных (номер заказа, телефон) реализован таймер бездействия (10 секунд). Если пользователь не совершает действий, экран автоматически возвращается на главную страницу, а данные не сохраняются.

4.2. Нумерация и буквы

Лимит в 30 талонов снят. Максимальный диапазон настраивается в параметрах типа очереди в HL ElectronicQueueTypes.
Буквы для талонов выбираются из заданного массива в HL ElectronicQueueTypes, что исключает путаницу созвучных символов.

5. Озвучка талонов на TV

Система TV-панели поддерживает автоматическую озвучку талонов при их назначении менеджеру (статус "Принят").

5.1. Логика работы (W247ElectronicQueueTv)

Событие: При получении через Comet-канал события updateStatus со статусом 2, TV-интерфейс добавляет талон в очередь на озвучку.
Синтез речи (TTS):
- Система формирует текстовое сообщение (например: "Талон номер А 123, готов к выдаче, подойдите к окну номер 1").
- Для улучшения произношения некоторых букв (например, "В") к ним программно добавляются вспомогательные звуки.
- Текст отправляется на сервер (ajax.php?action=getAudioTV), где через сервис EcomexpertSpeechKit генерируется аудиофайл.
Воспроизведение:
- Сначала проигрывается звук уведомления (alert_35.mp3 или Bell Magic H_2.wav).
- Затем воспроизводится синтезированный голос.
- На время озвучки (10 секунд) информация о талоне отображается на весь экран TV.

6. Ручное тестирование (Кейсы)

Кейс 1: Кнопка готовности менеджера

Войти в интерфейс менеджера, выбрать окно.
Убедиться, что кнопка "Принять клиента" голубого цвета.
Создать талон в очереди.
После назначения талона убедиться, что кнопка стала красной.
Нажать "Завершить обслуживание" -> Нажать "Принять клиента".
Ожидаемый результат: Кнопка снова стала голубой, окно готово к следующему талону.

Кейс 2: Проверка приоритизации по типу очереди

Настроить в HL ElectronicQueueButtons: "Юридическое лицо" (UF_PRIORITY = 1), "Обычный заказ" (UF_PRIORITY = 3).
Создать талон "Обычный заказ" (префикс A).
Через 1 минуту создать талон "Юридическое лицо" (префикс U).
Освободить окно менеджера (нажать "Принять клиента").
Ожидаемый результат: Первым будет назначен талон U (Юр. лицо), несмотря на то, что он был создан позже. Это подтверждает работу иерархии приоритетов UF_PRIORITY.

Кейс 3: Проверка приоритизации по штрафам (Penalties)

В HL ElectronicQueuePenalties создать правило для Менеджера А: Штраф 100 на раздел "Крупногабаритный товар".
Авторизовать Менеджера А и Менеджера Б (у которого нет штрафов) в активных окнах. Оба менеджера должны быть "свободны".
Создать талон с заказом, содержащим "Крупногабаритный товар".
Ожидаемый результат: Талон должен быть назначен Менеджеру Б, так как у Менеджера А приоритет снижен из-за штрафа.

Кейс 4: Проверка равномерного распределения (Round-Robin)

Авторизовать двух менеджеров (М1 и М2) в системе.
Обнулить счетчики обслуженных талонов за сегодня или убедиться, что они равны.
Последовательно создать 4 талона одного типа.
Поочередно освобождать окна менеджеров.
Ожидаемый результат: Талоны распределяются по схеме М1 -> М2 -> М1 -> М2. Система выбирает менеджера с наименьшим количеством назначенных талонов за текущие сутки.

Кейс 5: Проверка приоритета "Готов к выдаче"

Создать талон Т1 (Обычный), статус заказа - "В сборке" (UF_READY_HIPPING = false).
Создать талон Т2 (Обычный), статус заказа - "Собран" (UF_READY_HIPPING = true).
Освободить окно менеджера.
Ожидаемый результат: Первым будет назначен талон Т2, так как собранные заказы имеют безусловный приоритет над несобранными внутри одного типа очереди.

Кейс 6: Таймер терминала

На терминале нажать "У меня есть номер заказа".
Дойти до экрана ввода номера и ничего не нажимать 10 секунд.
Ожидаемый результат: Терминал автоматически вернулся на главный экран.

Кейс 7: Озвучка талона на TV

Открыть интерфейс TV (/queue/include/tv.php).
В интерфейсе менеджера освободить окно и дождаться назначения нового талона (или создать новый).
Ожидаемый результат:
- На TV-панели на 10 секунд появляется плашка с номером талона и окна на весь экран.
- Воспроизводится звуковой сигнал (колокольчик).
- Сразу после сигнала синтезированный голос четко произносит номер талона и номер окна, куда нужно подойти.
- Проверить корректность произношения буквы талона.