Support Hub/API & Integrations/Как обрабатывать повторяющиеся и поступившие не по порядку…
Translated from the English article and reviewed by a person. Read the English original
Developer

Как обрабатывать повторяющиеся и поступившие не по порядку события отметок

Как обрабатывать повторяющиеся и поступившие не по порядку события отметок

 

Учёт рабочего времени по биометрии в реальном времени выглядит просто: человек сканирует палец или лицо, ваша система получает событие и сохраняет его. На практике данные учёта получаются более запутанными. Одно и то же событие может прийти дважды. Сотрудник может дважды подряд приложить палец к сканеру. Устройство, потерявшее связь, может отправить утреннюю отметку ухода только во второй половине дня. Кто-то может нажать не ту кнопку отметки прихода. Если ваша система сохраняет каждое событие ровно в том виде, в котором оно пришло, эти мелкие проблемы превращаются в неверно посчитанные отработанные часы, споры по расчёту зарплаты и отчёты, которым никто не доверяет. В этом руководстве объясняются различные виды повторяющихся и поступивших не по порядку событий отметок, причины их появления и чёткий набор правил, основанных на OperationID и LogTime, которые помогают поддерживать записи учёта в чистоте.

01 · Проблема

Почему чистые данные учёта сложнее, чем кажется

События учёта поступают с физических устройств, разбросанных по объектам, используются реальными людьми и передаются по сетям, которые иногда прерываются. Каждый из этих факторов создаёт возможность того, что данные придут с искажениями. Ни один из них не является неисправностью биометрической системы. Это просто то, что происходит, когда физический мир встречается с программным обеспечением.

Хорошая новость в том, что каждое событие отметки из Cams Biometrics Gateway содержит информацию, необходимую для его очистки. Основную работу выполняют два поля:

Поле Что это такое Что это позволяет делать
OperationID Уникальный идентификатор каждого события, которое отправляет Gateway Распознать абсолютно одно и то же событие, если оно пришло более одного раза
LogTime Время, когда человек фактически отсканировался, с учётом смещения часового пояса устройства Расставлять события в реальном порядке их возникновения независимо от того, когда они поступили

Ещё три поля помогают в более сложных случаях: UserId определяет человека, SerialNumber определяет устройство, а Type указывает, была ли нажата отметка прихода или ухода.

Событие отметки из Callback API

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

02 · Не все дубликаты одинаковы

Четыре вида повторяющихся событий отметок

Самая распространённая ошибка заключается в том, что все дубликаты обрабатываются одинаково. Существует четыре различных вида, и каждый из них требует своего решения. Одни имеют техническую природу, другие возникают из-за того, как люди пользуются устройствами.

Вид дубликата Как это выглядит Как его распознать Что делать
Повторно доставленное событие Одно и то же событие приходит дважды Одинаковый OperationID Игнорировать вторую копию, но всё равно отправить ответ done
Пересекающийся импорт Событие, полученное через callback, повторно импортируется при сверке Одинаковые UserId, LogTime и SerialNumber из разных источников Игнорировать вторую копию
Двойное сканирование Человек дважды прикладывает палец к сканеру в течение нескольких секунд Разные OperationID, один и тот же человек, значения LogTime очень близки друг к другу Считать как одну отметку, используя правило минимального интервала
Отметка с неверным типом Человек нажимает отметку прихода, когда хотел отметить уход Две отметки прихода подряд без отметки ухода между ними Применять правило сопоставления пар отметок при расчёте часов

Технические дубликаты и дубликаты, созданные людьми

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

Почему происходит повторная доставка

Callback — это диалог: Gateway отправляет событие, а ваш сервер отвечает подтверждением done. Если ответ не доходит, потому что ваш сервер работал медленно, перезапускался или был ненадолго недоступен, событие может быть отправлено повторно. Ваш сервер мог уже сохранить первую копию. Поэтому правило всегда одно и то же: если вы уже видели OperationID, не сохраняйте его повторно, но обязательно ответьте done, чтобы Gateway знал, что событие получено. Точное поведение при повторной доставке для вашей конфигурации уточняйте в документации Cams Web API.

Ответ, который ваш приёмник отправляет на каждое событие, включая дубликаты

{ "status": "done" }

03 · Порядок поступления — не реальный порядок

Почему события отметок поступают не по порядку

Ваш сервер получает события в порядке их поступления. Учёт рабочего времени должен рассчитываться в порядке сканирования. В большинстве случаев эти порядки совпадают. Иногда — нет.

Причина Что происходит Пример
Устройство или объект офлайн Устройства продолжают локально записывать сканирования, а затем отправляют их все, когда связь восстанавливается Отметка ухода в 13:01 поступает в 13:41, уже после отметки в 13:35 с другого устройства
Задержки сети События с разных устройств идут разными маршрутами и занимают разное время Два сканирования с разницей в одну секунду поступают в обратном порядке
Несколько устройств на одного человека Сотрудник отмечает приход на главном КПП, а уход — на боковой двери События с двух устройств непредсказуемо чередуются
Импорт при сверке Недостающие события позже дозаполняются из журналов устройств Событие от понедельника добавляется в вашу систему во вторник

Полезная нагрузка уже показывает разницу. LogTime — это момент, когда произошло сканирование. Time — это временная метка самого сообщения в GMT. В приведённом выше примере полезной нагрузки сканирование произошло в 07:48 местного времени, а сообщение было отправлено в 04:19 по GMT, что соответствует 09:49 в том же часовом поясе, то есть на два часа позже. Именно такой разрыв характерен для периода работы в офлайн-режиме. Если бы вы сортировали по времени поступления, это сканирование оказалось бы не на своём месте.

Время поступления показывает, когда ваш сервер об этом узнал. LogTime показывает, когда это произошло. Учёт рабочего времени всегда должен следовать за LogTime.

04 · Восемь правил

Playbook по чистым данным учёта рабочего времени

Эти восемь правил охватывают все описанные выше случаи. Первые четыре относятся к вашему приёмнику callback и хранилищу. Последние четыре относятся к логике, которая преобразует сохранённые события в учёт рабочего времени.

1

Сначала сохраняйте каждое исходное событие

Сохраняйте каждую полезную нагрузку ровно в том виде, в котором она была получена, прежде чем делать с ней что-либо ещё. Если правило позже окажется неверным, вы сможете заново обработать исходные данные.

2

Игнорируйте повторяющиеся OperationID

Сделайте OperationID уникальным в вашем хранилище. Если тот же OperationID поступает повторно, не сохраняйте его, но всё равно отправьте ответ done.

3

Используйте естественный ключ для импорта

Для событий, импортированных при сверке, рассматривайте сочетание UserId, LogTime и SerialNumber как идентификатор сканирования, чтобы одно и то же сканирование никогда не сохранялось дважды из двух источников.

4

Сортируйте по LogTime, никогда по времени поступления

Разбирайте LogTime вместе со смещением часового пояса и всегда сортируйте по нему при расчёте учёта рабочего времени.

5

Пересчитывайте с учётом поздних событий

Не завершайте расчёт часов за день в тот момент, когда поступает отметка ухода. Пересчитывайте данные при поступлении поздних событий и фиксируйте день только после периода стабилизации, например перед запуском расчёта зарплаты.

6

Объединяйте двойные сканирования с минимальным интервалом

Считайте сканирования одного и того же человека в пределах короткого интервала, например двух минут, одной отметкой. Выбирайте интервал, подходящий для вашего рабочего места.

7

Сопоставляйте отметки по понятному правилу

Определите, как обрабатывать отметки с неверным типом, например сопоставляя сканирования по порядку времени или используя первое сканирование как приход, а последнее как уход. Применяйте одно и то же правило везде.

8

Ведите журнал всех исправлений

Когда правило объединяет, игнорирует или переименовывает сканирование, фиксируйте, что произошло и почему. HR и аудиторам нужно видеть, как исходные сканирования превратились в отработанные часы.

Следите за точностью часов устройств

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

05 · Применяем правила вместе

Пример: один сотрудник, один непростой день

Вот реалистичный день сотрудника 2 на объекте Burj Khalifa, показанный в том порядке, в котором события поступили на сервер. Объект на part of the day потерял связь.

Поступило OperationID Type LogTime Что делают правила
09:02 op-1001 CheckIn 08:58 Сохранено
09:03 op-1001 CheckIn 08:58 Тот же OperationID: проигнорировано, отправлен done
09:04 op-1002 CheckIn 08:59 В пределах двух минут от 08:58: объединено как двойное сканирование
13:40 op-1004 CheckIn 13:35 Сохранено
13:41 op-1003 CheckOut 13:01 Поздно поступило из периода офлайн-работы: помещено перед 13:35 по LogTime
18:05 op-1005 CheckIn 18:04 Вторая отметка прихода подряд: сопоставлена как итоговый уход за день

После сортировки по LogTime и очистки день превращается в два понятных рабочих периода:

Период Начало Конец Продолжительность
Утро 08:58 13:01 4 часа 3 минуты
День 13:35 18:04 4 часа 29 минут
Всего отработано 8 часов 32 минуты

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

06 · Создано для чистых данных

Как Cams Gateway помогает поддерживать чистоту данных

Чистые данные учёта рабочего времени начинаются с событий, которые содержат правильную информацию. Cams Biometrics Gateway спроектирован так, чтобы каждое событие, полученное вашей системой, можно было идентифицировать, упорядочить и отследить.

Возможность Cams Как помогает
OperationID в каждом событии Даёт вашей системе надёжный способ распознавать и игнорировать повторно доставленные события
LogTime со смещением часового пояса Позволяет расставлять события в их реальном порядке независимо от того, где и когда они поступили
UserId, SerialNumber и LabelName Определяют человека, устройство и объект, которые вместе образуют естественный ключ для импорта
Офлайн-кэш и очередь Сохраняют события во время перерывов в связи и доставляют их с исходными временными метками
Подтверждение done Даёт понятный сигнал о том, что каждое событие получено, поэтому доставка может быть подтверждена
RESTful-операции для загрузки журналов Позволяют запрашивать журналы устройств по требованию, чтобы выполнить сверку и заполнить любые пробелы
AI Code Generator Prompts Генерируют приёмник callback, который проверяет токены и журналирует каждое событие, готовый к добавлению правил из этого руководства

Кто за что отвечает

Cams Gateway доставляет каждое проверенное сканирование с информацией, необходимой для его очистки. Удаление технических дубликатов относится к вашему приёмнику callback. Объединение двойных сканирований, сопоставление отметок и расчёт часов относятся к вашей HRMS, системе расчёта зарплаты или логике учёта рабочего времени, где уже работают ваши бизнес-правила.

Часто задаваемые вопросы

Должен ли мой приёмник отклонять повторяющиеся события с ошибкой?

Нет. Отправляйте ответ done и на дубликаты. Событие было получено благополучно, а ответ с ошибкой может привести к его повторной отправке. Просто не сохраняйте его.

Можно ли использовать только LogTime для обнаружения дубликатов?

Нет, не только. Два разных человека могут отсканироваться в одну и ту же секунду. Для повторно доставленных событий используйте OperationID, а для импорта — сочетание UserId, LogTime и SerialNumber.

Какой должна быть продолжительность окна для двойного сканирования?

Достаточно длинным, чтобы поймать случайные повторные касания, и достаточно коротким, чтобы не объединять настоящие отдельные отметки. Окно от одной до двух минут подходит большинству рабочих мест, но выбирайте вариант, который соответствует вашим сменам и планировке объекта.

Когда следует фиксировать учёт рабочего времени за день?

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

Применяется ли это и к сканированию лица, карт и PIN-кодов?

Да. Каждый тип ввода поступает в одном и том же формате события, с одинаковыми полями OperationID и LogTime, поэтому одни и те же правила применяются независимо от того, как человек прошёл верификацию.

Заключение: доверие основано на правилах, а не на удаче

Повторяющиеся и поступившие не по порядку события отметок — не редкие исключительные случаи. Это обычная часть работы учёта рабочего времени по биометрии на реальных устройствах, в реальных сетях и с реальными людьми. Разница между данными учёта, которым доверяет HR, и данными, которые порождают споры, заключается не в удаче. Она состоит в небольшом наборе понятных правил, последовательно применяемых на практике.

Игнорируйте повторяющиеся OperationID. Сортируйте всё по LogTime. Рассматривайте дубликаты, созданные людьми, как бизнес-правила, а не технические ошибки. Пересчитывайте данные с учётом поздних событий, фиксируйте каждое исправление и поддерживайте точность часов устройств. С этими правилами каждое проверенное сканирование становится надёжной записью.

Cams Biometrics Gateway даёт данные, необходимые для работы этих правил. Каждое событие Callback содержит OperationID, LogTime со смещением часового пояса, а также данные о пользователе, устройстве и объекте, необходимые для идентификации каждого сканирования, с устройств более чем 15 брендов. Офлайн-кэш и очередь защищают события во время перебоев, а RESTful-операции позволяют выполнять сверку с журналами устройств в любой нужный момент. Изучить платформу можно на сайте CamsBiometrics.com, полную документацию Web API — на developer.camsbiometrics.com, а создать приёмник callback можно с помощью AI Code Generator Prompts.

Was this article helpful?