내방객 출입관리 시스템

설계사무소 신사옥의 내방객 출입을 관리하는 웹 시스템입니다. 사내 ERP에서 방문 예약이 결재되면 방문자에게 QR을 문자로 발송하고, 방문 당일 QR로 게이트를 통과할 수 있도록 출입통제 장비와 연동합니다. 관리자는 방문 현황·이력·레포트를 한 화면 체계에서 관리합니다.

프로젝트 개요

• 범위: ERP 연동 API, 방문자 QR 발급·문자 안내, 출입통제 장비 연동, 관리자 웹(대시보드·방문 이력·레포트), 운영 배포
• 운영 형태: 상시 운영 업무 시스템. 사내 SSO 계정으로 관리자만 접속
• 연동 대상: 사내 ERP(결재), 출입통제 장비 DB, 문자 발송 API

주요 기능

• ERP 결재 연동: 결재 완료 시 ERP가 방문 정보를 API로 전달하면 자동 등록. 결재 취소도 동일 경로로 반영
• QR 발급·문자 안내: 방문 건마다 고유 방문코드와 QR을 생성해 방문자 휴대폰으로 발송. 장문은 LMS로 자동 전환
• 출입통제 연동: 방문자·출입 카드를 장비 DB에 등록하고 QR을 카드번호로 인코딩. 취소 시 장비 측 상태도 함께 갱신
• 대시보드: 오늘 방문 예정·완료·대기·취소 현황과 최근 방문. 문자 미전달·장비 동기화 실패 건은 상단 알림으로 표시하고 해당 건만 바로 조회
• 방문 이력: 기간·상태·검색어 필터, 연락처 마스킹, 페이지 조회
• 레포트: 기간별 상태 요약과 엑셀 내보내기

시스템 구성

• 프론트엔드: React, Vite, React Router
• 백엔드: Node.js(Express), Prisma ORM, Zod 입력 검증, 구조화 로깅
• 데이터: 자체 DB(SQLite) + 출입통제 장비 DB(MS SQL) 직접 연동
• 인증: 사내 SSO(OIDC) 연동, 서버 세션, 관리자 역할 검사. ERP 연동 API는 API 키 인증
• 배포: Docker 단일 컨테이너(정적 프론트 + API 동일 오리진), CI에서 린트·테스트 자동 실행

처리 흐름과 안정성

• 방문 등록은 3단계로 처리합니다. ① 방문코드·QR 생성 → ② 자체 DB 확정 → ③ 장비 등록·QR 재인코딩·문자 발송. ③이 실패해도 등록 자체는 보존되며 상태로 표시되어 재처리할 수 있습니다.
• 방문 상태: QR대기 → 등록완료 / 문자실패 / 동기화실패 → 방문완료 · 취소 · 만료. 종결 상태는 재활성화하지 않습니다.
• 동일 결재 건이 중복 수신되면 미완료 건은 이어서 처리하고 완료 건은 거절합니다(멱등 처리). 방문코드·카드번호는 충돌 시 자동 재시도합니다.

보안·운영

• 전화번호는 뒤 4자리·해시·암호문(AES-256-GCM)으로 분리 저장하고 화면에는 마스킹 표시
• 요청 속도 제한, CSP, 입력 인코딩 검증, 운영 환경 시크릿 검증 후 기동
• 운영 로그와 장비·문자 연동 결과 기록으로 장애 원인 추적