Контракт API CV-модуля в МПС: что отдавать в UI

Зачем фиксировать контракт до вёрстки экрана

Экран поиска в МПС обычно уже существует: поле ввода, список, статусы. CV добавляет поток асинхронных событий с камеры. Если контракт «на словах», команда рисует UI под один набор статусов, а модуль отдаёт другой.

Мы описываем общий подход. Конкретные имена методов, типы и пакеты уточняются на техдемо и в документации поставки — здесь нет выдуманных сигнатур.

Что UI должен получать от модуля

Минимальный полезный набор для экрана:

• Кандидат / совпадение — распознанное значение (код, фрагмент заказа, артикул) и уверенность/статус сопоставления в рамках сценария.
• Пустой результат — кадр обработан, совпадения нет (это не то же самое, что ошибка).
• Несколько кандидатов — если сценарий допускает неоднозначность, UI должен уметь показать выбор, а не молча взять первый.
• Состояние сессии — идёт захват, пауза, нужна перенастройка камеры, завершено.

Метаданные для аналитики

Отдельно от UI-отображения модуль может отдавать события для метрик (попытка, длительность до совпадения). Состав агрегатов согласуется с заказчиком и не должен тащить кадры.

Ошибки и edge-кейсы, которые нельзя игнорировать

• Нет кадра / нет доступа к камере — отказ в permission, занятая камера, фон/килл процесса. UI показывает понятный recovery, а не вечный loader.
• Не распознано — нормальный рабочий исход; подсказки по углу и освещению лучше продуктовых «ошибка 500».
• Несколько совпадений — дать выбрать или уточнить контекст заказа/артикула.
• Устарела сессия поиска — заказ уже выдан или артикул сменили в справочнике; модуль не должен бесконечно подсвечивать старый контекст.
• Отмена пользователем — закрытие экрана освобождает камеру и подписки.

Идемпотентность событий

UI должен быть готов к повторным callback’ам с тем же кандидатом (стабилизация по кадрам). Иначе список «прыгает», а аналитика считает лишние попытки.

Как не блокировать UI

Инференс и захват кадров не должны идти на main thread UI. Паттерн: модуль работает асинхронно, UI подписан на поток событий, тяжёлая отрисовка — по мере необходимости. Сеть не входит в критический путь распознавания.

Практические правила:

• Не ждать сеть, чтобы показать результат кадра.
• Не держать модальные блокировки на каждый промежуточный кадр.
• Давать явный «Стоп» / «Отмена».
• Сохранять возможность ручного ввода как fallback — CV ускоряет, а не единственный путь.

Что согласовать на техдемо

Базовый обзор поставки и ролей команд — на посадочной SDK. Контракт UI — тема отдельной сессии с тимлидом МПС, не маркетинговый one-pager.

1. Список статусов и смысл каждого для вашего UX.
2. Формат кандидата относительно ваших справочников (заказ, артикул, ячейка).
3. Политика «несколько совпадений».
4. Тестовые фикстуры и критерий приёмки экрана.

Версионирование контракта и обратная совместимость

Когда контракт меняется — новый статус или другое поле кандидата — UI и модуль должны обновляться согласованно. Практичный приём: версия схемы событий и явная деградация. Старый UI игнорирует неизвестные поля; новый модуль не ломает старые статусы без migration notes в релизе.

Логирование на стороне МПС: пишите тип события и идентификатор сессии поиска, не кадр. Этого достаточно для разбора инцидента «почему не подсветило» без расширения модели угроз и без споров с ИБ о хранении изображений.

Тестовые двойники модуля (fake implementation) ускоряют разработку UI без камеры. Контракт fake и real должен совпадать по статусам — иначе экран «зелёный» на моках и красный на устройстве. Это частая причина срыва сроков пилота.

Документирование для смежных команд

Короткой таблицы статусов для дизайнера и QA часто достаточно. Не прячьте смысл статусов только в коде SDK. Иначе поддержка смены начнёт трактовать пустой результат как аварию.

Приёмка экрана перед пилотом

1. Permission denied — понятный экран с действием в настройки.
2. Пустой результат — подсказка, не алерт «ошибка системы».
3. Несколько кандидатов — выбор без автоподтверждения.
4. Отмена — камера освобождена, подписки сняты.
5. Уход в фон и возврат — сессия либо продолжает, либо явно перезапускается.

Этот чеклист приёмки согласуйте с тимлидом МПС на техдемо. Он важнее красивой анимации рамки. Детали API — в документации поставки; публичная статья задаёт ожидания, а не заменяет SDK docs.

После приёмки экрана имеет смысл прогнать те же статусы на реальных этикетках площадки. Контракт устойчив только если UI корректно реагирует и на «чистый» демо-набор, и на повреждённые коды из жизни.

Связь контракта с аналитикой и поддержкой

Каждый статус, который видит UI, должен иметь смысл для поддержки. Если аналитика пишет «error» на пустой результат, смена и поддержка будут чинить несуществующую аварию. Разделите продуктовые исходы и технические сбои уже на уровне контракта событий.

Для админки полезны агрегаты: попытки, пустые исходы, отмены, длительность до совпадения. Состав полей согласуйте заранее и не добавляйте туда изображения «на всякий случай». Это и продуктовое, и ИБ-решение.

Контракт также помогает онбордингу новых разработчиков МПС: таблица статусов и fake-модуль позволяют собрать экран без доступа к модели. Это ускоряет параллельную работу дизайна, Android и iOS.

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

Анти-паттерны контракта

Не отдавайте в UI «сырой» поток всех промежуточных гипотез без фильтрации — экран начнёт мигать. Не прячьте отказ камеры в общий error без recovery. Не подтверждайте заказ автоматически при первом совпадении, если сценарий допускает неоднозначность. Не блокируйте ручной ввод «пока камера думает».

Эти анти-паттерны чаще ломают пилот, чем отсутствие идеальной модели. Контракт и UX-дисциплина — часть поставки ценности on-device CV, а не мелочь после интеграции SDK.

Краткий итог для тимлида МПС

Зафиксируйте статусы, recovery для камеры, правило нескольких совпадений и fake-модуль для UI. Тогда встраивание SDK перестаёт быть сюрпризом на площадке.

Детали сигнатур оставьте документации поставки и техдемо. Эта статья задаёт каркас ответственности между модулем и экраном — его достаточно, чтобы начать проектирование без выдуманных API.