Версия ПО: Exzotron Server (сборка от 12.10.2026) · Проверено: 12.10.2026 · Ответственный компонент: расчёт факта, приём телеметрии, REST API, выгрузка в 1С. Документ описывает только сведения, допустимые для клиентской документации: адреса серверов, порты, учётные данные и внутренние идентификаторы не приводятся.
Статья для технического специалиста, интегратора и службы поддержки: как работает расчёт факта, откуда берутся данные, какие у системы интерфейсы и ограничения.
1. Источники навигационных данных и протоколы#
Выбираются при добавлении объекта в поле «Тип терминала». Для каждого протокола поднят отдельный приёмник.
| Протокол | Назначение | Статус |
|---|---|---|
| Galileosky | основной протокол трекеров; аналоговые входы, CAN, датчики уровня (LLS), счётчики | Реализовано и проверено на реальных приборах |
| Sinocastel (IDD-серия) | трекеры, датчики уровня топлива, CAN | Реализовано и проверено |
| ADM (1.09, семейство ADM50…600) | двоичный протокол | Реализовано и проверено |
| Wialon Combine | двоичный протокол Gurtam с расширяемыми полями | Реализовано; в агро-сценариях не подтверждено |
| Wialon IPS, Wialon Retranslator | текстовые протоколы | В коде, не подтверждено тестом |
| Navtelecom (NTCB/FLEX) | протокол Navtelecom | В коде, не подтверждено тестом |
На объектах ДемоАгро в проверке использовался тип терминала «УМка Wialon Combine»; в настройках объекта виден тип терминала и порт приёма.
Внешние системы мониторинга. В справочнике серверов API можно хранить подключения к внешним системам (Fort-Monitor, Wialon, Omnicomm, Glonass и др.). Фоновая служба для компаний с включённым «фактом работ» и заданной датой старта синхронизирует из Fort-Monitor трек, уровень топлива, скорость, зажигание и расход CAN в таблицу объекта блоками по 3 часа. Основной потребитель — отчёт «Работа спецтехники и топливо». Для агро-нарядов работа по данным внешних систем не подтверждена.
2. Путь данных и задержки#
- Приём. Приёмник разбирает пакет, приводит значения к единицам и сохраняет «сырые» данные в таблицу объекта (время хранится в UTC0). Расчётов приёмник не делает.
- Очередь расчёта. Для устройства обновляется запись о точке актуальности и времени последнего пакета.
- Расчётный конвейер датчиков. Пул воркеров берёт устройства из очереди и считает производные колонки той же таблицы: статус зажигания, работа механизма (время и 0/1), уровень топлива, пробег, скорость; события заправок и сливов; зеркало текущих значений. Размер окна расчёта ограничен (6 часов по умолчанию): большие разрывы догоняются порциями.
- Агро-проход. Раз в 15 минут (параметр планировщика) для объектов с графиком смен: окна смен сегодняшних и двух прошлых суток, глубина 36 часов; читаются готовые колонки, строятся отрезки и операции, пишутся в наряды.
Следствия: если конвейер выключен или отстаёт — факт пуст; изменения датчиков ведут к пересчёту истории объекта, а наряды обновятся при следующем проходе или по кнопке «Пересчитать».
| Этап | Значение |
|---|---|
| Приём → сырые данные | сразу |
| Сырые → производные колонки | цикл воркеров 10 с + очередь (фактическая задержка не измерена) |
| Производные → автонаряд | проход раз в 15 мин; окно без новых данных пропускается, но не реже раза в час пересчитывается принудительно |
| Наряд «На проверке» | после конца смены + 30 мин автоматически не пересчитывается |
| «Завершён» | не пересчитывается |
| Нагрузка | на тестовом объёме (118 объектов) проход занимал 1–4 с |
Время суток: сырые данные — UTC0; операции и периоды нарядов — местное время предприятия; время создания и завершения наряда записывается временем сервера базы данных.
3. Алгоритм расчёта факта#
3.1 Исходные данные#
| Данные | Источник и правило |
|---|---|
| Точки трека | таблица объекта (время, координаты, скорость, спутники) |
| Движение | датчик скорости; порог по умолчанию 2 км/ч; потолок достоверной скорости для сельхозтехники — 60 км/ч |
| Двигатель | датчик зажигания ≥ 0,5; без датчика — выводится из движения/работы механизма |
| Работа механизма | датчик механизма; без него у сельхозтехники движение внутри геозоны = работа |
| Качество навигации | спутников не меньше 4; недостоверность держится 10 минут после плохой точки |
| Пробег | приращение датчика пробега или CAN; шаг быстрее 130 км/ч отбрасывается; без датчика — по координатам |
| Геозоны | все геозоны предприятия, кроме групп; зона точки — «точка в фигуре» |
| Рабочие зоны | геозоны, привязанные к «Объектам работ» |
| Заправки, сливы | события датчика уровня (один датчик объекта, приоритет у сумматора) |
3.2 От точек к отрезкам#
| Двигатель | Движение | Механизм | Тип отрезка |
|---|---|---|---|
| выкл | да | — | стоянка (при настроенном зажигании движение при выключенном двигателе приравнивается к стоянке — защита от дрейфа GPS) |
| выкл | нет | — | стоянка |
| вкл | да | нет | переезд |
| вкл | нет | нет | холостой ход |
| вкл | да | да | работа в движении |
| вкл | нет | да | работа на месте |
| — | — | — | нет данных (пауза дольше «Неактивности», кроме паузы после стоянки с выключенным двигателем) |
Сработавший датчик механизма «склеивается» на 3 минуты. Новый отрезок начинается при смене типа, признака навигации или геозоны. Заправка накладывается поверх по событию датчика уровня.
3.3 От отрезков к операциям#
- «Работа» — по полю; смена поля — новая операция; «Переезд» — между зонами (откуда → куда); «Холостой ход» — отдельной строкой, если не короче «Мин. стоянки» (внутри работы входит в её простой); «Заправка» — по событию.
- Короткая стоянка вне геозон не рвёт идущую операцию.
- Работа в зоне, не являющейся полем, становится переездом; короткие заезды и «значимость поля» описаны в статье «Поля, геозоны и обработанные площади».
- Переезды короче 0,1 км удаляются как дрейф GPS, затем склеиваются соседние операции.
- Итоги: рабочее время — сумма «Работа»; переезды — сумма «Переезд»; холостой ход; моточасы — время с работающим двигателем (шире суммы операций; в таблице есть сверочные строки); пробег — путь «Переезд» и «Работа».
- «Перескок» (путь более 0,05 км при нулевом времени или скорости более 30 км/ч) в рабочий ход и площадь не входит.
3.4 Константы#
| Параметр | Значение |
|---|---|
| Склейка работы | 3 мин |
| Минимум для автонаряда | путь 0,3 км или работа 10 мин (+ зажигание непрерывно не менее «Мин. стоянки») |
| «Мин. стоянка» | 5 мин (настройка объекта) |
| «Неактивность» | 30 мин (настройка объекта) |
| Порог движения | 2 км/ч (настройка датчика) |
| Потолок скорости сельхозтехники | 60 км/ч |
| Потолок шага пробега | 130 км/ч |
| Рабочая скорость, выше — перескок | 30 км/ч |
| Минимум спутников | 4 |
| Дрейф переезда | 0,1 км |
| Короткий заезд на поле | менее 180 с и менее 0,3 км |
| Значимость поля | не менее 600 с и 5 % работы наряда (либо главное поле) |
| Ширина по умолчанию | 1,0 м |
| Окно возврата автосоздания | 36 ч |
| Период планировщика | 15 мин |
3.5 Площадь#
Площадь, га = Σ (путь рабочего хода, км × ширина, м / 10) по отрезкам «Работа в движении», не являющимся перескоком; округление — 0,01 га. Ширина: агрегат наряда → модель оборудования агрегата → «Ширина захвата» объекта → 1 м. Перекрытия и повторные проходы не учитываются, площадь не ограничивается площадью поля.
4. Пересчёт и ручной факт#
| Действие | Что делает |
|---|---|
| «Пересчитать факт» | пересчёт по окну смены; закрытый день и ручной факт блокируют |
| Планировщик (15 мин) | автонаряды; не трогает «Завершён» и «замороженные» «На проверке» |
| «Обработать период» | за прошлые даты (до 32 дней), в фоне, один запуск на предприятие |
| Ручной факт | часы, объём, пробег, заправка + причина; предупреждения правдоподобия без запрета |
| Смена статуса ручного наряда | пересчёт при «На проверке» и «Завершён» |
5. Закрытие дня, блокировка, выгрузка#
Закрытие дня. Единица — день × подразделение. Проверки: не завершён, нет исполнителя, нет факта, факт вручную, пробег при выключенном двигателе, пересечение нарядов техники, слив топлива. Решения по нарядам: «закрыть как есть» / «перенести на следующий день» (только ручной не завершённый наряд). Результат: статус «Завершён», сводка (хранится как документ), блокировка правок дня (правка, пересчёт, простои, ручной факт, создание и перенос наряда на эту дату). Открыть заново — администратор/расширенный пользователь; статусы нарядов не возвращаются.
Файл для 1С (схема exzotron.agro.export, версия 1): JSON-объект с полями schema, schemaVersion, company, period, documents[]. Документ = техника + исполнитель + дата + вид документа (AGRO_WAYBILL — путевой лист сельхозтехники); содержит vehicle, employee, division, rows[] (наряды дня) и totals. Строка наряда: orderId, source, shift, periodStart/End, workType, workObject, geozone, hours {engine, work, idle, transfer}, unit, planVolume, factVolume, factSource (TELEMETRY / MANUAL / NO_DATA), areaHa, distanceKm, refuelLiters, fields[] (факт по каждому полю: areaHa, workHours, distanceKm, transferKm, transferHours), downtimes[], note. Не рассчитанные часы выгружаются пустыми, а не нулями. Идентификаторы справочников (GUID) создаются при первой выгрузке и не меняются; ключи сопоставления — табельный номер, инвентарный номер техники, код вида работ и объекта работ.
Правила: в файл попадают завершённые наряды, ещё не выгружавшиеся (флажок «включить уже выгруженные» отменяет); период — до 93 дней; блокировок нет, предпросмотр выдаёт предупреждения. Файл хранится в системе и по повторному запросу отдаётся тем же.
Чего нет: передачи данных в 1С по сети; обратной загрузки справочников; статуса «принято в 1С»; расценок и зарплатных расчётов. Реальная загрузка файла в 1С в рамках проверки не выполнялась, формат с разработчиком 1С не согласован.
6. Программный интерфейс (REST API)#
- Префикс
/api/v1, формат JSON UTF-8. Предприятие определяется по пользователю — параметра «предприятие» нет. - Авторизация: сессия веб-входа либо HTTP Basic для интеграций; блокировка по IP при неверных попытках входа (ответ 429).
- Ошибки: бизнес-ошибки — HTTP 400 с телом
{"message": "…"}; прочие — 500. При просроченной сессии запрос из браузера может вернуть страницу входа. - Даты:
ГГГГ-ММ-ДД, времяГГГГ-ММ-ДД ЧЧ:ММ[:СС](местное время предприятия).
| Группа | Основные точки | Роли |
|---|---|---|
Заявки и наряды (/agro_orders) |
form_data, field_crops?year=, requests, requests/{id}/form_order, наряды (GET, POST, PUT, DELETE), status, recalc, fact, split, downtimes, downtime_reasons, backfill |
ADMIN, ADVANCED_USER, USER (backfill запуск — ADMIN, ADVANCED_USER) |
| Карточка наряда | /{id}, /{id}/ops, /{id}/track, /{id}/fuel |
те же |
Закрытие дня (/agro_day_close) |
pending, check, закрыть, range, сводка, открыть заново |
три роли; открыть заново — ADMIN, ADVANCED_USER |
Выгрузка в 1С (/agro_export) |
preview, формирование пакета, список, файл, print/{orderId} |
три роли |
Планы (/sowing-plans, /tech-plans) |
журнал, документы, строки, поля, fill-fields, fill-ops, отчёты report/rows, report/fields, report/execution |
ADMIN, ADVANCED_USER, USER, CUSTOMER |
Геозоны (/geozones) |
CRUD, import_kml/preview, import_kml, export_kml |
любая вошедшая роль |
| Справочники | виды работ, единицы, культуры, объекты работ, модели, операции, агрегаты | см. «Разграничение доступа» |
Подробный перечень параметров публикуется в техническом приложении; документация OpenAPI на стенде подключена, но публикуемость отдельных контроллеров не проверялась.
7. Разграничение доступа#
Четыре роли: ADMIN, ADVANCED_USER, USER, CUSTOMER (и служебная роль оператора АЗС без функций агромодуля). Защита REST — аннотации ролей; все /api/** требуют входа. Дополнительно — ограничение по подразделениям у пользователя: журналы, заявки, закрытие дня и выгрузка фильтруются по доступным подразделениям, записи без подразделения ограниченному пользователю не видны. Не охвачены: справочники, документы планов, геозоны, «Обработка периода». Видимость пунктов меню — настройка меню на сервере; скрытие пункта не заменяет защиту REST.
8. Ограничения и зависимости#
Обязательно для работы факта:
- работает расчётный конвейер датчиков;
- включён планировщик нарядов (иначе — ручные наряды и «Обработать период»);
- у объекта: тип «Сельхозтехника», график смен, подразделение;
- датчик зажигания с верным порогом и датчик скорости/пробега;
- геозоны-поля и «Объекты работ» с привязкой;
- ширина захвата (агрегат/модель/объект) — иначе 1 м;
- часовой пояс предприятия.
Ограничения: автонаряд — только по смене из графика; принятый наряд не пересчитывается; закрытый день блокирует правки; «Обработать период» — до 32 дней; выгрузка — до 93 дней; закрытие диапазона — до 31 дня; в окне «Закрыть день» — до 300 нарядов с замечаниями; журнал — до 5 000 записей; один наряд — один исполнитель; нумерация заявок и сводок дня сквозная по всей базе; импорт геозон — только KML-полигоны.
Не подтверждено / риски: работа ролей USER и CUSTOMER в интерфейсе агромодуля; несколько подразделений в живых данных; многосменный график и смена через полночь у сельхозтехники; загрузка файла в 1С; агро-расчёт по данным внешних систем; кадр времени ручных нарядов при часовом поясе предприятия, отличном от московского; нагрузочная проверка на боевых объёмах.
9. Что публиковать для клиента, а что нет#
В клиентской документации не приводятся: адреса и порты серверов и приёмников, учётные данные, токены и ключи, внутренние идентификаторы баз данных, имена внутренних таблиц сверх необходимого, номера кадров исходного кода. Для интеграторов эти сведения выдаются отдельно по запросу в рамках проекта внедрения.