feat: 실시간 대기 번호표 웹앱 초기 커밋
PIN 기반 세션으로 관리자·발급기·표시판 3개 역할을 하나의 앱에서 운영. Socket.IO 실시간 동기화, Podman Quadlet(10.89.0.25) 배포 구성 포함. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
gm
168
README.md
Normal file
168
README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 대기 번호표 시스템
|
||||
|
||||
실시간 대기 번호표 발급·관리·표시 웹앱입니다.
|
||||
하나의 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 관리)
|
||||
Reference in New Issue
Block a user