출입 통제 시스템 개발 시 상태값을 도메인별로 분리 정의하는 기준을 소개합니다. 코드 네이밍 규칙, 문 상태 전이 상태머신 설계, 출입 로그 구분과 임시 권한 수명 주기 처리까지 실무 관점으로 정리했습니다.
- 출입 통제 상태값, 왜 도메인별로 분리해서 정의해야 하는가
- 단계 1: 상태값 코드 체계와 네이밍 규칙 수립
출입 통제 상태값, 왜 도메인별로 분리해서 정의해야 하는가
현장에서 가장 먼저 무너지는 지점부터 보자. 입장 게이트에서 QR을 스캔하면 3초 이내 입장 처리가 이뤄지고, 동일 QR 재사용은 실시간으로 차단된다. 이 판단이 3초 안에 나오려면 "이 참가자가 입장 가능한 상태인가"를 묻는 사용자 상태와 "이 게이트가 지금 어느 구역을 담당하는가"를 묻는 단말 상태가 분리되어 있어야 한다. 둘을 한 컬럼에 몰아넣으면 구역을 전환할 때마다 참가자 상태까지 함께 흔들린다.
사전등록 → QR 무인 체크인 → 명찰 출력 → 출입 통제 → e방명록으로 이어지는 흐름에서 각 도메인의 상태가 바뀌는 시점은 전혀 다르다.
단계 1: 상태값 코드 체계와 네이밍 규칙 수립
단계 1: 상태값 코드 체계와 네이밍 규칙 수립
상태값 설계에서 가장 먼저 무너지는 지점은 의외로 기술이 아니라 이름 짓기입니다. 개발자는 01, 운영자는 "입장대기", 관리자 페이지에는 "대기"로 표시되기 시작하면, 어느 순간 아무도 어떤 값이 어떤 상태인지 확신하지 못하게 됩니다.
| 항목 | 숫자 코드 (01, 02…) | 영문 코드 (DOOR_OPEN…) |
|---|---|---|
| 가독성 | 낮음 — 코드만 보고 의미 추론 불가 | 높음 — 코드 자체가 의미를 담음 |
| 타이핑·입력 오류 | 오타 가능성 낮음 | 길어지면 오타 위험 |
| 정렬·전이 순서 관리 | 정렬순 컬럼 없이도 자연 정렬 | 반드시 별도 정렬순 필요 |
| 하위 호환 | 중간 삽입 시 전체 재정렬 위험 | 신규 코드 추가가 기존에 무영향 |
실무 권장은 영문 코드 + 도메인 접두어 조합입니다. 숫자만 쓰면 "03이 입장인가 퇴장인가"를 매번 코드 테이블을 열어 확인해야 하지만, DOOR_ENTERED, DOOR_EXITED처럼 쓰면 로그 데이터만 봐도 흐름이 읽힙니다.
접두어는 "이 상태값이 어느 도메인의 것인가"를 코드만으로 알려주는 최소한의 안전장치입니다.
단계 2: 문 상태 전이를 상태머신으로 설계하고 무효 전이 차단하기
개장을 한 시간 앞두고 3번 출입문이 먹통이 됐습니다. 현장 기사가 관리 화면에서 '고장'을 '정상'으로 바로 되돌리려는 순간, 시스템이 변경을 거절합니다. 고장에서 정상으로 가는 직행 경로가 애초에 정의되지 않았기 때문인데, 이 장면이 상태머신 설계의 핵심을 보여줍니다.
허용 전이만 화이트리스트로 정의한다
문 상태를 정상·고장·수선·점검 네 가지로 정했다면,
단계 3: 출입 로그 상태 구분과 임시 권한 수명 주기 처리
현장에서 가장 난감한 순간은 스캐너에서 경고가 떴는데 담당자가 그게 뭔지 못 읽을 때다. 중복 스캔인지, 만료된 QR인지, 다른 세션용 코드인지에 따라 안내 멘트도 통계 집계도 완전히 달라지기 때문에, 입장·퇴장·거부·비정상 네 가지를 코드 단계에서부터 분리해두면 현장 혼란의 절반은 사라진다.
상태값 네 개를 나누는 기준
| 상태값 | 언제 발생하나 | 기록 항목 | 통계·리포트 반영 |
|---|---|---|---|
| 입장 | 유효 QR 최초 인식(3초 이내 처리) | 참가자·구역·입장 시각 | 출석 수 합산 |
| 퇴장 | 퇴장 스캔 또는 세션 종료 | 퇴장 시각 | 체류 시간·보수교육 평점용 산출 |
| 거부 | 만료·미등록·권한 없는 세션 QR | 사유 코드 | 합산 제외, 별도 집계 |
| 비정상 | 중복 스캔, 동일 QR 재사용 시도 | 원본 스캔 연결 | 부정 시도 추이로만 관찰 |
핵심은 거부와 비정상을 절대 출석 수에 섞지 않는 것이다. e-Regi가 동일 QR 재사용을 실시간 차단하는 이유도 여기에 있다. 차단은 했는데 그 로그가 입장 집계에 묻히면, "차단이 실제로 작동했는지"를 리포트에서 확인할 길이 없어진다.
흔한 실수·FAQ와 상태값 변경 시 하위 호환 전략, 그리고 마무리 체크리스트
흔한 실수·FAQ와 상태값 변경 시 하위 호환 전략, 그리고 마무리 체크리스트
상태값 설계는 처음보다 운영 중에 무너지는 경우가 많아요. 코드는 잘 정의했는데 프론트엔드에서 표시명을 하드코딩해두면, 새 상태값을 추가하는 순간 구 버전 앱에서 빈 화면이나 오류가 뜹니다. 학회 현장에서 참가자 3초 입장을 기대했는데 명찰 화면이 멈춰 있는 장면을 상상해보면 왜 문제인지 바로 와닿죠.
흔히 겪는 세 가지 실수
- 프론트 표시명 하드코딩:
"P"를 "입장 대기"로 앱에 박아두면, 상태 추가 시 구 버전 앱이 처리하지 못함 - 로그와 권한 상태 혼용: 입·퇴장 기록(로그)과 출입 권한(상태)을 같은 값으로 쓰면, 재입장 허용 정책을 바꿀 수 없음
- 코드 삭제: 폐기한 상태값을 DB에서 지워버리면 과거 데이터의 의미가 사라짐
특히 두 번째는 QR 기반 운영에서 자주 걸립니다. 예를 들어 e-Regi처럼 동일 QR 재사용을 실시간 차단하는 구조라면, "이미 입장한 참가자"라는 정보는 권한 상태가 아니라 스캔 이력 기반으로 판단해야 하거든요. 상태와 이력의 역할을 나눠두지 않으면 중복 스캔 방지 로직이 꼬입니다.