대기 번호표 시스템

실시간 대기 번호표 발급·관리·표시 웹앱입니다.
하나의 URL로 세 가지 역할(관리자 / 발급기 / 표시판)을 모두 운영합니다.

---

구조

관리자 디바이스   →  번호 호출 / 초기화
발급기 디바이스   →  고객이 번호표 수령
표시판 디바이스   →  호출 번호 대형 화면 표시

모든 디바이스는 PIN으로 같은 세션에 묶입니다.
같은 PIN이면 관리자 2대 + 표시판 2대처럼 여러 대를 동시에 운영할 수 있습니다.

---

시작하기

1. 첫 접속 (PIN 생성)

앱 URL에 접속하면 PIN 입력 화면이 나옵니다.

• 원하는 PIN을 자유롭게 입력합니다 (숫자 권장, 최소 4자리).
• 처음 입력하는 PIN은 자동으로 새 세션을 생성합니다.
• 접속 버튼을 누르거나 Enter를 치면 역할 선택 화면으로 이동합니다.

같은 PIN을 다른 디바이스에서 입력하면 동일한 세션에 합류합니다.

---

2. 역할 선택

역할	설명
⚙️ 관리자	번호 호출·초기화를 담당하는 직원용 화면
🎟️ 번호표 발급기	고객이 직접 번호를 뽑는 키오스크 화면
📺 번호 표시판	대기실에 띄워두는 대형 번호 화면

---

화면별 사용법

⚙️ 관리자 화면

![관리자 화면]

항목	설명
현재 호출 번호	지금 표시판에 표시 중인 번호
대기 중	아직 호출되지 않은 인원 수
발급 총계	지금까지 발급된 번호표 총 수

다음 호출 ▶ 버튼을 누르면

• 다음 번호가 호출됩니다.
• 표시판 화면이 즉시 업데이트됩니다.
• 대기 인원이 1 감소합니다.
• 대기자가 없으면 버튼이 비활성화됩니다.

번호 초기화 버튼을 누르면

• 확인 팝업이 뜨고 확인 시 모든 번호가 0으로 초기화됩니다.
• 발급기·표시판도 동시에 초기화됩니다.

역할 변경 버튼으로 역할 선택 화면으로 돌아갈 수 있습니다.

---

🎟️ 번호표 발급기 화면

고객이 직접 터치하는 키오스크 화면입니다.

• 화면 상단에 현재 대기 인원과 현재 호출 번호가 실시간으로 표시됩니다.
• 번호표 뽑기 버튼을 누르면 번호가 발급되고 초록색 박스로 표시됩니다.
• 발급 후에는 새 번호표 뽑기 버튼으로 다음 고객의 번호를 발급할 수 있습니다.
• 관리자가 번호를 호출하면 "앞에 N명 대기 중" 문구가 자동으로 업데이트됩니다.

---

📺 번호 표시판 화면

대기실 모니터에 띄워두는 화면입니다.

• 호출된 번호가 전체 화면 크기로 크게 표시됩니다.
• 새 번호가 호출될 때마다 노란색 플래시 애니메이션이 재생됩니다.
• 아직 호출된 번호가 없으면 -로 표시됩니다.
• 우측 하단의 역할 변경 버튼으로 돌아갈 수 있습니다.

---

다중 디바이스 운영

같은 PIN으로 접속하면 역할에 관계없이 몇 대든 연결 가능합니다.

예시: 2창구 운영

관리자 A (창구 1)  ─┐
관리자 B (창구 2)  ─┤  PIN: 1234  ─── 표시판 A (대기실 TV 1)
발급기             ─┤               ── 표시판 B (대기실 TV 2)

• 관리자 A, B 중 누가 "다음 호출"을 눌러도 표시판 A, B 모두 즉시 업데이트됩니다.
• 두 관리자가 동시에 누르지 않도록 운영 상 협의가 필요합니다.

---

배포 구성

항목	값
컨테이너 IP	10.89.0.25
내부 포트	3000
이미지	localhost/queue-app:latest
Quadlet	/etc/containers/systemd/queue.container
네트워크	proxy.network

빌드

cd /root/queue-app
npm install          # package-lock.json 생성
podman build -t queue-app:latest .

서비스 관리

# 시작
systemctl start queue.service

# 중지
systemctl stop queue.service

# 상태 확인
systemctl status queue.service

# 로그 확인
journalctl -u queue.service -f

업데이트 배포

cd /root/queue-app
podman build -t queue-app:latest .
systemctl restart queue.service

NPM(Nginx Proxy Manager) 설정

Proxy Host 추가 시 Websockets Support를 반드시 활성화해야 합니다.
Socket.IO 실시간 통신이 WebSocket 업그레이드를 사용하기 때문입니다.

• Forward Hostname: 10.89.0.25
• Forward Port: 3000
• ☑ Websockets Support

---

기술 스택

• 런타임: Node.js 20 (Alpine)
• 프레임워크: Express 4
• 실시간 통신: Socket.IO 4
• 상태 저장: 서버 메모리 (재시작 시 초기화)
• 컨테이너: Podman Quadlet (systemd 관리)