Интеграция оборудования Гарвекс: как документировать ограничения стороннего протокола

Зачем документировать ограничения протокола

Интеграция оборудования начинается не с обещания, что устройства «точно совместимы», а с проверки документов на каждую сторону обмена. Название интерфейса само по себе не подтверждает совместимость: важны версия протокола, формат обмена и условия, которые описал производитель подключаемого устройства.

Документирование помогает разделить три категории сведений:

• Подтверждено документацией — характеристика или ограничение прямо указаны в руководстве.
• Требует проверки — данных недостаточно, нужно запросить документацию или уточнение.
• Не входит в согласованный объём — например, настройка или ремонт стороннего оборудования.

Такой подход особенно важен, когда в одном проекте участвуют контроллер, колонка, датчики и программное обеспечение разных производителей.

Что зафиксировать до интеграции

1. Идентифицировать оборудование и документы

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

2. Разделить интерфейс и протокол

В документации контроллера «Квота-2» указано, что обмен со сторонними устройствами налива производится по RS-485. В том же руководстве перечислены поддерживаемые протоколы: «Топаз» (протокол 2.0) и Sanki Dispenser Protocol v2.2. Эти сведения относятся к указанному контроллеру и не являются подтверждением совместимости с любой колонкой или устройством, где есть RS-485.

Руководство также указывает: построение линии, её топология, длина и используемый кабель должны соответствовать инструкции подключаемого устройства налива. Подключение датчиков уровня топлива к линии RS-485, где подключены внешние устройства выдачи, невозможно. Эти ограничения стоит внести в проектную документацию отдельно, со ссылкой на источник.

Перед использованием сведений сверьте их с актуальными документами. Материалы размещены в разделе документации «Гарвекс».

3. Заполнить матрицу совместимости

Матрица — это не список обещаний, а рабочая таблица статусов и подтверждений. Для каждой пары устройств фиксируйте, на каком документе основан вывод.

Не заменяйте статус «нет данных» формулировкой «совместимо». Если нужного описания нет, укажите, какой документ или ответ требуется получить.

Как описать границы проверки

В протоколе обследования или техническом задании полезно зафиксировать:

1. Какие модели и версии оборудования рассматриваются.
2. На каких документах основан каждый подтверждённый пункт.
3. Какие режимы и сценарии обмена входят в проверку.
4. Какие сведения остаются неподтверждёнными и кто должен их предоставить.
5. Какие действия относятся к оборудованию Гарвекс, а какие — к стороннему устройству.

Для чужого оборудования корректно запросить руководство и контакт ответственного поставщика. Не следует подменять отсутствующую документацию инструкциями по настройке или ремонту сторонней колонки, контроллера либо датчика.

Отдельно зафиксируйте программный обмен

Интеграция может включать не только линию между устройствами, но и передачу данных в учётную систему. В описании API «АЗС-Онлайн» указаны REST, HTTPS и формат JSON. Документ также отмечает, что промежуточные состояния между запросами не сохраняются; если клиентской программе они нужны, их следует хранить на её стороне.

Это отдельный участок матрицы: интерфейс и протокол оборудования не следует смешивать с API программного сервиса. Для каждого обмена укажите источник описания, требуемые доступы и вопросы, которые нужно согласовать до начала работ.

Чек-лист перед согласованием

• [ ] Модели и версии участников интеграции перечислены.
• [ ] Для интерфейса и протокола указаны документальные основания.
• [ ] Версия протокола записана точно, без предположений.
• [ ] Ограничения линии и подключаемых устройств вынесены отдельно.
• [ ] Неизвестные параметры отмечены как вопросы.
• [ ] Границы ответственности сторон согласованы.
• [ ] Проверка охватывает только заранее описанные сценарии.

Такая фиксация делает сопровождение интеграции АЗС понятнее: участники видят, что подтверждено, что предстоит проверить и где заканчивается согласованный объём работ. Для уточнения проекта и состава исходных данных можно обратиться через страницу контактов «Гарвекс». Подготовьте список оборудования и имеющиеся руководства — это поможет предметно обсудить следующие шаги.