# Документация: Электронная очередь (Electronic Queue) Задача [https://e-comexpert.planfix.ru/task/79102/?comment=63813692](https://e-comexpert.planfix.ru/task/79102/?comment=63813692) Требования [https://docs.google.com/document/d/1JYbb9qtUsQtoZLgwHUHmoXprcgkEZsqQYJ-sWx8TNC8/edit?tab=t.0](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. Настройка прав (Операций)** Настройка прав доступа осуществляется в административной панели Битрикс: 1. Перейдите в **Настройки -> Пользователи -> Уровни доступа**. 2. Создайте или отредактируйте уровень доступа (например, "Менеджер очереди"). 3. На вкладке **Включаемые операции** отметьте необходимые операции (например, `queue_manager`). 4. Назначьте этот уровень доступа соответствующей группе пользователей. --- ### 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)** Логика выбора талона: 1. **Иерархия приоритетов**: Сначала обрабатываются типы очередей с наименьшим значением `UF_PRIORITY` в HL `ElectronicQueueButtons` (например, Юр. лица — 1, Кредит — 2, Обычные — 3). 2. **Готовность заказа**: Внутри одного типа очереди приоритет отдается талонам с `UF_READY_HIPPING = true` (заказ собран). 3. **FIFO**: При прочих равных выбирается самый старый талон по времени создания. 4. **Выбор менеджера**: - Используется алгоритм **Round-Robin** по количеству обслуженных талонов за текущий день. - Учитываются **пенальти**: приоритет менеджера снижается на величину штрафа, если в заказе есть соответствующие товары/разделы. --- ### 4. Доработки терминала #### **4.1. Таймер бездействия** На экранах ввода данных (номер заказа, телефон) реализован таймер бездействия (10 секунд). Если пользователь не совершает действий, экран автоматически возвращается на главную страницу, а данные не сохраняются. #### **4.2. Нумерация и буквы** - Лимит в 30 талонов снят. Максимальный диапазон настраивается в параметрах типа очереди в HL `ElectronicQueueTypes`. - Буквы для талонов выбираются из заданного массива в HL `ElectronicQueueTypes`, что исключает путаницу созвучных символов. --- ### 5. Озвучка талонов на TV Система TV-панели поддерживает автоматическую озвучку талонов при их назначении менеджеру (статус "Принят"). #### **5.1. Логика работы (W247ElectronicQueueTv)** 1. **Событие**: При получении через Comet-канал события `updateStatus` со статусом 2, TV-интерфейс добавляет талон в очередь на озвучку. 2. **Синтез речи (TTS)**: - Система формирует текстовое сообщение (например: "Талон номер А 123, готов к выдаче, подойдите к окну номер 1"). - Для улучшения произношения некоторых букв (например, "В") к ним программно добавляются вспомогательные звуки. - Текст отправляется на сервер (`ajax.php?action=getAudioTV`), где через сервис `EcomexpertSpeechKit` генерируется аудиофайл. 3. **Воспроизведение**: - Сначала проигрывается звук уведомления (`alert_35.mp3` или `Bell Magic H_2.wav`). - Затем воспроизводится синтезированный голос. - На время озвучки (10 секунд) информация о талоне отображается на весь экран TV. --- ### 6. Ручное тестирование (Кейсы) #### **Кейс 1: Кнопка готовности менеджера** 1. Войти в интерфейс менеджера, выбрать окно. 2. Убедиться, что кнопка "Принять клиента" голубого цвета. 3. Создать талон в очереди. 4. После назначения талона убедиться, что кнопка стала красной. 5. Нажать "Завершить обслуживание" -> Нажать "Принять клиента". 6. **Ожидаемый результат**: Кнопка снова стала голубой, окно готово к следующему талону. #### **Кейс 2: Проверка приоритизации по типу очереди** 1. Настроить в HL `ElectronicQueueButtons`: "Юридическое лицо" (UF\_PRIORITY = 1), "Обычный заказ" (UF\_PRIORITY = 3). 2. Создать талон "Обычный заказ" (префикс A). 3. Через 1 минуту создать талон "Юридическое лицо" (префикс U). 4. Освободить окно менеджера (нажать "Принять клиента"). 5. **Ожидаемый результат**: Первым будет назначен талон U (Юр. лицо), несмотря на то, что он был создан позже. Это подтверждает работу иерархии приоритетов `UF_PRIORITY`. #### **Кейс 3: Проверка приоритизации по штрафам (Penalties)** 1. В HL `ElectronicQueuePenalties` создать правило для Менеджера А: Штраф 100 на раздел "Крупногабаритный товар". 2. Авторизовать Менеджера А и Менеджера Б (у которого нет штрафов) в активных окнах. Оба менеджера должны быть "свободны". 3. Создать талон с заказом, содержащим "Крупногабаритный товар". 4. **Ожидаемый результат**: Талон должен быть назначен Менеджеру Б, так как у Менеджера А приоритет снижен из-за штрафа. #### **Кейс 4: Проверка равномерного распределения (Round-Robin)** 1. Авторизовать двух менеджеров (М1 и М2) в системе. 2. Обнулить счетчики обслуженных талонов за сегодня или убедиться, что они равны. 3. Последовательно создать 4 талона одного типа. 4. Поочередно освобождать окна менеджеров. 5. **Ожидаемый результат**: Талоны распределяются по схеме М1 -> М2 -> М1 -> М2. Система выбирает менеджера с наименьшим количеством назначенных талонов за текущие сутки. #### **Кейс 5: Проверка приоритета "Готов к выдаче"** 1. Создать талон Т1 (Обычный), статус заказа - "В сборке" (`UF_READY_HIPPING = false`). 2. Создать талон Т2 (Обычный), статус заказа - "Собран" (`UF_READY_HIPPING = true`). 3. Освободить окно менеджера. 4. **Ожидаемый результат**: Первым будет назначен талон Т2, так как собранные заказы имеют безусловный приоритет над несобранными внутри одного типа очереди. #### **Кейс 6: Таймер терминала** 1. На терминале нажать "У меня есть номер заказа". 2. Дойти до экрана ввода номера и ничего не нажимать 10 секунд. 3. **Ожидаемый результат**: Терминал автоматически вернулся на главный экран. #### **Кейс 7: Озвучка талона на TV** 1. Открыть интерфейс TV (`/queue/include/tv.php`). 2. В интерфейсе менеджера освободить окно и дождаться назначения нового талона (или создать новый). 3. **Ожидаемый результат**: - На TV-панели на 10 секунд появляется плашка с номером талона и окна на весь экран. - Воспроизводится звуковой сигнал (колокольчик). - Сразу после сигнала синтезированный голос четко произносит номер талона и номер окна, куда нужно подойти. - Проверить корректность произношения буквы талона.