중복 및 순서가 뒤바뀐 출퇴근 이벤트 처리 방법
실시간 생체인식 출결은 단순해 보입니다. 사람이 스캔하면 시스템이 이벤트를 받고, 그 이벤트를 저장하면 됩니다. 하지만 실제로 출결 데이터는 훨씬 복잡합니다. 같은 이벤트가 두 번 도착할 수도 있습니다. 직원이 스캐너를 연달아 두 번 터치할 수도 있습니다. 연결이 끊겼던 장치가 오전의 퇴근 기록을 오후에 전송할 수도 있습니다. 또한 잘못된 출근 버튼을 누를 수도 있습니다. 시스템이 도착한 이벤트를 있는 그대로 모두 저장하면, 이런 작은 문제들이 잘못된 근무 시간, 급여 분쟁, 아무도 신뢰하지 않는 보고서로 이어집니다. 이 가이드에서는 중복 및 순서가 뒤바뀐 펀치 이벤트의 여러 유형과 발생 원인을 설명하고, 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으로 수신한 이벤트가 대사(reconciliation) 중에 다시 가져와짐 | 동일한 UserId, LogTime, SerialNumber이지만 출처가 다름 | 두 번째 사본은 무시 |
| 이중 스캔 | 사람이 몇 초 안에 스캐너를 두 번 터치 | OperationID는 서로 다르고, 같은 사람이며, LogTime이 매우 가까움 | 최소 간격 규칙을 적용하여 하나의 펀치로 처리 |
| 잘못 표시된 펀치 | 사람이 퇴근을 의도했지만 출근 버튼을 누름 | 퇴근 기록 없이 출근 기록이 두 번 연속으로 나타남 | 근무 시간을 계산할 때 짝짓기 규칙을 적용 |
|
기술적 중복과 사람에 의한 중복 비교 앞의 두 유형은 기술적 중복입니다. 시스템이 같은 스캔을 두 번 인식한 것이므로 단순히 무시하면 됩니다. 뒤의 두 유형은 사람에 의한 중복입니다. 실제로 별개의 스캔이 이루어진 것이므로, 그것이 무엇을 의미하는지는 업무 규칙으로 결정해야 합니다. 두 유형의 처리 방식은 분리해서 관리하십시오. 수신기(receiver)는 기술적 중복만 제거해야 하며, 사람에 의한 중복이 무엇을 의미하는지는 출결 로직에서 결정해야 합니다. |
재전송이 발생하는 이유
Callback은 일종의 대화입니다. Gateway가 이벤트를 보내면 서버는 done 확인 응답으로 답합니다. 서버가 느리거나, 재시작되었거나, 일시적으로 연결할 수 없어서 응답이 도착하지 않으면, 이벤트가 다시 전송될 수 있습니다. 서버는 이미 첫 번째 사본을 저장했을 수도 있습니다. 그래서 규칙은 항상 같습니다. 이미 확인한 OperationID라면 다시 저장하지 말고, 대신 done으로 응답하여 Gateway가 이벤트를 받았음을 알 수 있도록 하십시오. 사용 환경에 맞는 정확한 재전송 동작은 Cams Web API 문서에서 확인하십시오.
|
중복을 포함한 모든 이벤트에 대해 수신기가 보내는 응답 { "status": "done" }
|
03 · 도착 순서는 실제 발생 순서가 아닙니다
펀치 이벤트가 순서 없이 도착하는 이유
서버는 이벤트를 도착한 순서대로 받습니다. 하지만 출결은 스캔이 발생한 순서대로 계산해야 합니다. 대부분의 경우 두 순서는 같지만, 항상 그런 것은 아닙니다.
| 원인 | 발생하는 상황 | 예시 |
|---|---|---|
| 장치 또는 현장의 오프라인 상태 | 장치가 스캔 기록을 로컬에 저장해 두었다가 연결이 복구되면 한꺼번에 전송 | 13:01 퇴근 기록이 다른 장치의 13:35 스캔 이후인 13:41에 도착 |
| 네트워크 지연 | 서로 다른 장치의 이벤트가 각기 다른 경로를 거쳐 서로 다른 시간이 걸림 | 1초 간격의 두 스캔이 거꾸로 도착 |
| 사람별 여러 장치 사용 | 직원이 정문에서 출근 기록을 남기고 측면 출입구에서 퇴근 기록을 남김 | 두 장치의 이벤트가 예측할 수 없이 뒤섞여 도착 |
| 대사 가져오기 | 누락된 이벤트가 나중에 장치 로그에서 채워짐 | 월요일 이벤트가 화요일에 시스템에 추가됨 |
페이로드에는 이 차이가 이미 나타나 있습니다. LogTime은 스캔이 발생한 시점이고, Time은 메시지 자체의 타임스탬프로 GMT 기준입니다. 위의 예시 페이로드에서 스캔은 현지 시간 07:48에 발생했지만, 메시지는 GMT 04:19에 전송되었습니다. 같은 시간대로 환산하면 09:49이므로, 약 두 시간 뒤에 전송된 셈입니다. 이러한 시간 차이가 바로 오프라인 기간이 남기는 흔적입니다. 도착 순서로 정렬하면 이 스캔은 잘못된 위치에 놓이게 됩니다.
|
도착 시간은 서버가 이벤트를 언제 알게 되었는지를 알려 주고, LogTime은 실제로 언제 발생했는지를 알려 줍니다. 출결은 항상 LogTime을 기준으로 해야 합니다. |
04 · 여덟 가지 규칙
깨끗한 출결 데이터를 위한 플레이북
이 여덟 가지 규칙은 위에서 설명한 모든 경우를 다룹니다. 처음 네 가지는 callback 수신기와 저장소에 적용하고, 마지막 네 가지는 저장된 이벤트를 출결 기록으로 변환하는 로직에 적용합니다.
|
원본 이벤트를 먼저 모두 저장 다른 작업을 하기 전에 각 페이로드를 받은 그대로 저장하십시오. 나중에 규칙이 잘못된 것으로 밝혀지더라도 원본 데이터로부터 다시 처리할 수 있습니다. |
|
|
반복된 OperationID 무시 저장소에서 OperationID가 고유하도록 설정하십시오. 같은 OperationID가 다시 도착하면 저장을 건너뛰되, 여전히 done으로 응답하십시오. |
|
|
가져오기에는 자연 키 사용 대사 과정에서 가져온 이벤트의 경우 UserId, LogTime, SerialNumber의 조합을 스캔의 식별자로 취급하십시오. 그래야 두 출처에서 같은 스캔이 두 번 저장되는 일을 막을 수 있습니다. |
|
|
도착 순서가 아닌 LogTime으로 정렬 시간대 오프셋을 포함하여 LogTime을 파싱하고, 출결을 계산할 때는 항상 LogTime으로 정렬하십시오. |
|
|
도착 즉시가 아니라 나중에 계산 퇴근 기록이 도착하는 순간 그날의 근무 시간을 확정하지 마십시오. 늦게 도착하는 이벤트가 생기면 다시 계산하고, 급여 처리 전과 같이 정산 기간이 지난 후에만 해당 일자를 잠그십시오. |
|
|
최소 간격으로 이중 스캔 병합 예를 들어 2분처럼 짧은 시간 창 안에 있는 같은 사람의 스캔은 하나의 펀치로 취급하십시오. 시간 창은 해당 사업장에 맞게 선택하십시오. |
|
|
명확한 규칙으로 펀치 짝짓기 잘못 표시된 펀치를 어떻게 처리할지 결정하십시오. 예를 들어 스캔을 시간순으로 짝짓거나, 첫 번째 스캔을 출근, 마지막 스캔을 퇴근으로 볼 수 있습니다. 같은 규칙을 모든 곳에 일관되게 적용하십시오. |
|
|
모든 수정 사항 기록 유지 규칙이 스캔을 병합하거나, 무시하거나, 다시 표시할 때마다 무슨 일이 일어났고 왜 그랬는지를 기록하십시오. HR과 감사 담당자는 원본 스캔이 어떻게 근무 시간으로 바뀌었는지 확인할 수 있어야 합니다. |
|
장치 시계를 정확하게 유지하십시오 LogTime은 장치의 시계에서 가져옵니다. 장치의 시간이 잘못되어 있으면 그 장치의 모든 스캔이 잘못됩니다. 아무리 정렬을 잘해도 이 문제는 해결되지 않습니다. 각 장치의 날짜, 시간, 시간대가 올바른지 확인하고, 정전이나 펌웨어 업데이트 후에도 반드시 다시 점검하십시오. |
05 · 규칙 종합 적용
실제 사례: 한 직원, 복잡했던 하루
부르즈 칼리파 사이트의 직원 2번에 대한 실제 하루를 서버에 이벤트가 도착한 순서대로 보여 드립니다. 이 사이트는 하루 중 일부 시간 동안 연결이 끊겼습니다.
| 도착 시각 | 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로부터 2분 이내: 이중 스캔으로 병합 |
| 13:40 | op-1004 | CheckIn | 13:35 | 저장됨 |
| 13:41 | op-1003 | CheckOut | 13:01 | 오프라인 기간의 지연 도착: LogTime 기준으로 13:35 이전에 배치 |
| 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 코드 생성기 프롬프트 | 토큰을 검증하고 모든 이벤트를 기록하는 callback 수신기를 생성하며, 이 가이드의 규칙을 추가할 준비가 된 상태로 제공 |
|
역할 분담 Cams Gateway는 검증된 각 스캔을 정리하는 데 필요한 정보와 함께 전달합니다. 기술적 중복의 제거는 callback 수신기에서 처리합니다. 이중 스캔 병합, 펀치 짝짓기, 근무 시간 계산은 이미 업무 규칙이 존재하는 HRMS, 급여 또는 출결 로직에서 처리하십시오. |
자주 묻는 질문
|
수신기가 중복 이벤트를 오류와 함께 거부해야 하나요? 아니요. 중복 이벤트에도 done으로 응답하십시오. 이벤트는 이미 안전하게 도착했으며, 오류 응답은 이벤트를 다시 전송하게 만들 수 있습니다. 단순히 저장만 건너뛰면 됩니다. |
|
중복을 찾는 데 LogTime만 사용할 수 있나요? 단독으로는 어렵습니다. 서로 다른 두 사람이 같은 초에 스캔할 수도 있기 때문입니다. 재전송된 이벤트에는 OperationID를 사용하고, 가져오기에는 UserId, LogTime, SerialNumber의 조합을 사용하십시오. |
|
이중 스캔 시간 창은 얼마나 길어야 하나요? 실수로 반복 터치한 스캔은 잡아내고, 실제로 별개인 펀치는 병합하지 않을 만큼 짧아야 합니다. 대부분의 사업장에는 1~2분의 시간 창이 적합하지만, 교대 근무와 현장 구조에 맞게 선택하십시오. |
|
하루의 출결은 언제 잠가야 하나요? 지연된 이벤트가 도착할 수 있도록 정산 기간을 둔 후에 잠그십시오. 예를 들어 다음 날 아침이나 급여 처리 직전이 될 수 있습니다. 그전까지는 그날의 새 이벤트가 도착할 때마다 다시 계산하십시오. |
|
이 내용은 얼굴, 카드, PIN 스캔에도 적용되나요? 네. 모든 입력 유형은 동일한 OperationID와 LogTime 필드를 포함한 같은 이벤트 형식으로 도착하므로, 사람이 어떤 방식으로 인증했든 같은 규칙이 적용됩니다. |
결론: 신뢰는 운이 아니라 규칙에서 나옵니다
중복 및 순서가 뒤바뀐 펀치 이벤트는 드문 예외 상황이 아닙니다. 실제 장치, 실제 네트워크, 실제 사람을 통해 생체인식 출결을 운영할 때 발생하는 일반적인 현상입니다. HR이 신뢰하는 출결 데이터와 분쟁을 일으키는 데이터의 차이는 운이 아니라, 일관되게 적용되는 간단하고 명확한 규칙 몇 가지에서 비롯됩니다.
반복된 OperationID는 무시하고, 모든 것을 LogTime으로 정렬하십시오. 사람에 의한 중복은 기술적 오류가 아니라 업무 규칙으로 취급하십시오. 늦게 계산하고, 모든 수정 사항을 기록하며, 장치 시계를 정확하게 유지하십시오. 이러한 규칙을 갖추면 검증된 모든 스캔이 신뢰할 수 있는 기록이 됩니다.
Cams Biometrics Gateway는 이러한 규칙이 작동하도록 필요한 데이터를 제공합니다. 모든 Callback 이벤트에는 OperationID, 시간대 오프셋이 포함된 LogTime, 그리고 각 스캔을 식별하는 데 필요한 사용자, 장치, 사이트 정보가 포함되며, 15개 이상의 브랜드 장치에서 지원됩니다. 오프라인 캐시 및 큐는 연결이 끊긴 동안 이벤트를 보호하며, RESTful 작업을 통해 언제든지 장치 로그와 대사할 수 있습니다. 플랫폼은 CamsBiometrics.com에서 살펴보실 수 있으며, 전체 Web API 문서는 developer.camsbiometrics.com에서 확인하실 수 있습니다. 또한 AI 코드 생성기 프롬프트를 사용하여 callback 수신기를 생성하실 수 있습니다.