# 대기 번호표 시스템

실시간 대기 번호표 발급·관리·표시 웹앱입니다.  
하나의 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` |

### 빌드

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

### 서비스 관리

```bash
# 시작
systemctl start queue.service

# 중지
systemctl stop queue.service

# 상태 확인
systemctl status queue.service

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

### 업데이트 배포

```bash
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 관리)