AOA(Angle of Arrival) 블루투스 기술 기반 실시간 입출입 추적 시스템
목적: 화재 등 긴급상황 발생 시 1초 이내 건물별 재실자 현황 파악
시스템 규모:
- 6개 건물
- 36개 출입구
- 36개 AOA 앵커
- 실시간 태그 위치 추적
# .env 파일 생성 및 편집
cp .env.example .env
# REDIS_PASSWORD 및 DB_PASSWORD 설정# 모든 서비스 시작
docker-compose up -d
# 서비스 상태 확인
docker-compose ps# PC 대시보드 (React)
cd frontend && npm install && npx vite --host
# → http://localhost:5173
# 모바일 앱 (React)
cd Mobile && npm install && npx vite --host --port 5174
# → http://localhost:5174주요 접속 URL:
- PC 대시보드:
http://localhost:5173(개발 모드) - API 문서 (Swagger):
http://localhost:8001/docs - 게이트 모니터링 (레거시):
http://localhost:8001/static/gate-monitor.html
AOA 앵커 (36개)
↓
데이터 수집 레이어 (TCP 9000)
↓
Redis (실시간 버퍼)
↓
이벤트 감지 엔진
↓
MariaDB (영구 저장)
↓
FastAPI REST API / WebSocket
↓
웹 대시보드
서비스 구성:
- redis: 실시간 데이터 저장소 (재실 현황 단일 진실 공급원)
- mariadb: 영구 데이터 저장소 (이력/분석)
- api: FastAPI REST API 서버
- ingestion: 원시 데이터 수집
- processor: 필터링 및 이벤트 감지 (v6 존재 기반)
- frontend: PC 대시보드 (React, Nginx)
- mobile: 모바일 앱 (React, Nginx)
curl -s http://localhost:8001/api/v1/realtime/gates | jq# 특정 게이트에서 5개 태그가 10분간 입출입
docker-compose exec api python scripts/gate_simulator.py \
--gate GATE-B01-01 \
--anchor 20:BA:36:9A:FD:00 \
--mode continuous \
--tags 5 \
--duration 10http://localhost:8001/static/gate-monitor.html접속- 드롭다운에서 게이트 선택
- 실시간 궤적 확인!
- 건물별 현재 재실자 수
- 태그별 위치 추적
- 1초 이내 조회 (긴급상황 대응)
- 앵커 중심 실시간 궤적 추적
- 태그별 색상 구분
- 0.5초 간격 업데이트
- 2D 극좌표 시각화 및 3D 시각화 (Three.js)
- Three.js 기반 실시간 3D 시각화
- 앵커/문/바닥 3D 렌더링
- 좌표계: X(좌우), Y(전후), Z(높이)
- 앵커 캘리브레이션 설정 패널
- 가상 출입선 통과 감지
- ENTRY: RSSI ≥ -75dBm 감지 시 즉시 입실 처리
- EXIT 경로: 펄스+침묵(45초) → 크로스빌딩 → 소멸타이머(2시간) → 야간리셋(04:00)
- 다중 앵커 ENTRY: 2개 이상 앵커에서 60초 내 감지 시 ENTRY (약신호 보완)
- 신뢰도 점수 계산 (confidence)
- 전체 이벤트 로그
- 건물/태그/날짜별 필터링
- 페이지네이션 지원
# 시스템 시작
docker-compose up -d
# 시스템 중지
docker-compose down
# 전체 재시작
docker-compose down && docker-compose up -d
# 로그 확인
docker-compose logs -f
# 특정 서비스 로그
docker-compose logs -f api
docker-compose logs -f processor# MariaDB
docker-compose exec mariadb mysql -u aoa_user -p merck_aoa
# Redis
docker-compose exec redis redis-cli -a your_password# API 헬스 체크
curl http://localhost:8001/api/v1/health
# 컨테이너 상태
docker-compose ps- CLAUDE.md - 개발자 가이드 (아키텍처, 명령어, 알고리즘)
- CHANGELOG.md - 버전별 변경 이력
- QUICK_START.md - 빠른 시작 가이드
- USER_MANUAL.md - 운영자 사용 매뉴얼
- docs/ENTRY_EXIT_ALGORITHM.md - 입출입 감지 알고리즘 (v4/v6)
- docs/API_USAGE_GUIDE.md - REST API 전체 명세
- docs/ANCHOR_ORIENTATION_GUIDE.md - 앵커 방향 설정
- GATE_SIMULATOR_GUIDE.md - 시뮬레이터 가이드
- DATA_FORMAT_GUIDE.md - AOA 데이터 형식
- merck_aoa_docs.md - 전체 PRD 및 기술 설계
백엔드:
- Python 3.11+
- FastAPI (REST API + WebSocket)
- AsyncIO (비동기 I/O)
데이터 처리:
- NumPy, SciPy (수치 연산)
- FilterPy (칼만 필터)
데이터베이스:
- Redis (실시간 데이터)
- MariaDB 10.11 (영구 저장)
인프라:
- Docker Compose
- Nginx (프로덕션용)
프론트엔드 (PC):
- React + TypeScript + Vite
- Tailwind CSS
- JWT 인증
프론트엔드 (모바일):
- React + TypeScript + Vite
- Capacitor (Android)
| 지표 | 목표 | 설명 |
|---|---|---|
| 긴급 대응 | < 1초 | 건물 재실자 조회 |
| 데이터 처리 | < 500ms | 수집부터 저장까지 |
| API 응답 | < 200ms | 실시간 재실 조회 |
| 데이터 유실률 | < 0.1% | 신뢰성 |
| 이벤트 정확도 | 오탐 <5%, 미탐 <2% | 입출입 감지 |
GET /api/v1/health # 헬스 체크
GET /api/v1/realtime/occupancy # 전체 건물 재실 현황
GET /api/v1/emergency/building/{id}/occupants # 긴급 재실자 조회
GET /api/v1/events/history # 출입 이력
WS /api/v1/ws/positions # 실시간 위치 (전체)
WS /api/v1/ws/gate/{gate_id} # 실시간 위치 (게이트별)
GET /api/v1/buildings # 건물 목록 조회
GET /api/v1/buildings/{building_id} # 건물 상세 조회
POST /api/v1/buildings # 건물 생성
PUT /api/v1/buildings/{building_id} # 건물 수정
DELETE /api/v1/buildings/{building_id} # 건물 비활성화
GET /api/v1/gates # 게이트 목록 조회
GET /api/v1/gates/{gate_id} # 게이트 상세 조회
POST /api/v1/gates # 게이트 생성
PUT /api/v1/gates/{gate_id} # 게이트 수정
DELETE /api/v1/gates/{gate_id} # 게이트 비활성화
GET /api/v1/anchors # 앵커 목록 조회
GET /api/v1/anchors/{anchor_id} # 앵커 상세 조회
GET /api/v1/anchors/{anchor_id}/status # 앵커 상태 조회
POST /api/v1/anchors # 앵커 생성
PUT /api/v1/anchors/{anchor_id} # 앵커 수정 (캘리브레이션 포함)
DELETE /api/v1/anchors/{anchor_id} # 앵커 비활성화
GET /api/v1/tags # 태그 목록 조회
GET /api/v1/tags/{tag_id}/status # 태그 상태 조회
GET /api/v1/tags/low-battery # 배터리 부족 태그 목록
POST /api/v1/tags # 태그 생성
PUT /api/v1/tags/{tag_id} # 태그 수정
DELETE /api/v1/tags/{tag_id} # 태그 비활성화
전체 API 문서: http://localhost:8001/docs (FastAPI Swagger UI)
docker-compose down -v
docker-compose up -d# Windows
netstat -ano | findstr :3307
tasklist | findstr <PID>
# docker-compose.yml에서 포트 변경# 시뮬레이터 실행
docker-compose exec api python scripts/gate_simulator.py \
--gate GATE-B01-01 --anchor 20:BA:36:9A:FD:00 --mode continuous
# Processor 재시작
docker-compose restart processor자세한 내용은 CLAUDE.md 참조
MerckAOA/
├── app/ # 백엔드 애플리케이션
│ ├── api/ # REST API (routes/, v1/)
│ ├── core/ # 핵심 로직 (필터, 감지, 인증)
│ ├── services/ # 백그라운드 서비스
│ └── db/ # 데이터베이스 연결
├── frontend/ # PC 대시보드 (React+Vite+TS)
│ ├── src/ # React 소스코드
│ ├── dashboard/ # 레거시 HTML 대시보드
│ └── nginx.conf # 프로덕션 Nginx 설정
├── Mobile/ # 모바일 앱 (React+Vite+Capacitor)
│ ├── src/ # React 소스코드
│ └── android/ # Android 빌드
├── scripts/ # 유틸리티 스크립트
│ └── gate_simulator.py # 게이트 시뮬레이터
├── sql/ # 스키마, 시드, 마이그레이션
│ └── init_full.sql # 전체 초기화 (신규 서버용)
├── docs/ # 상세 기술 문서
├── docker-compose.yml # Docker 구성
└── requirements.txt # Python 의존성
- 기본 시스템 구축
- 실시간 위치 추적
- 이벤트 감지 알고리즘
- 게이트 모니터링 대시보드
- 게이트 전용 시뮬레이터
- JWT 인증/권한 관리
- React PC 대시보드
- 모바일 앱 (Android)
- 비상상황 발령/대피 체크인
- 운영자/집결지 관리
- v6 존재 기반 감지기 (펄스+침묵 EXIT, 다중 앵커 ENTRY)
- 재실 API Redis 기반 전환
- Docker 컨테이너 프론트엔드 배포
- 알람/알림 시스템 고도화
- 분석 리포트 자동 생성
Proprietary - Merck Korea
프로젝트 관리: Merck Korea IT Team
문서 버전: 3.2 최종 업데이트: 2026-03-05
# ✅ 시스템 시작
docker-compose up -d
# ✅ 시뮬레이터 실행
docker-compose exec api python scripts/gate_simulator.py \
--gate GATE-B01-01 --anchor 20:BA:36:9A:FD:00 \
--mode continuous --tags 5 --duration 10
# ✅ 대시보드 접속
http://localhost:8001/static/gate-monitor.html
# ✅ 로그 확인
docker-compose logs -f
# ✅ 시스템 중지
docker-compose down더 많은 정보는 CLAUDE.md를 참조하세요!