# [정원에이전시] 비전 AI & 스마트 시설 관제 부서 운영 가이드
(Vision AI & Facility Analytics Department)

---

## 1. 부서 개요 및 관제 범위
본 부서는 정원에이전시 내의 **물리적 공간(매장, 사무실, 창고 등)에 설치된 로컬 카메라 영상**을 실시간으로 분석하여 방문자 통계, 고객 재방문 인식, 공간 혼잡도 및 보안 알림을 제공하는 컴퓨터 비전(Computer Vision) 전담 부서입니다.

- **관제 대상 범위**: 사용자가 직접 지정·연결한 특정 로컬 카메라(스마트폰 IP Webcam, USB 웹캠, RTSP 스트림 등)의 렌더링 화각 내
- **데이터 처리 원칙**: 로컬 엣지(Edge) 환경에서 프라이빗하게 연산하며, 외부 유출 없이 로컬 DB(`visitors.db`)에 안전하게 저장

---

## 2. 핵심 기능 모듈 인벤토리

| 파일명 | 역할 및 기능 | 지원 모델 |
| :--- | :--- | :--- |
| `test_simulator.py` | 가상 고객 출입 시뮬레이션 및 파이프라인 검증 | YuNet + SFace ONNX |
| `face_visitor_counter.py` | 실시간 카메라 연동 안면 인식 및 방문 횟수 카운터 | OpenCV DNN, ONNX |
| `human_detector.py` | 구역 내 인원 실시간 객체 탐지 및 CSV 로깅 | YOLOv8n (`yolov8n.pt`) |
| `Heatmap_People_Crowd.py` | 구역 내 유동 인구 이동 경로 및 혼잡도 히트맵 시각화 | YOLOv8/11 + OpenCV |
| `YoloV8_cars_detection.py` | 주차 공간 및 출입 차량 실시간 카운팅 | YOLOv8n 차량 클래스 |
| `web_server.py` | Flask 기반 실시간 스트리밍 대시보드 (SSE 이벤트) | Flask 3.1, HTML5 |
| `telegram_bot.py` | 신규/재방문 고객 포착 시 관리자 텔레그램 실시간 알림 | Telegram Bot API |
| `db_manager.py` | 방문자 프로필, 안면 임베딩, 방문 횟수 관리 | SQLite (`visitors.db`) |

---

## 3. 엔드투엔드 파이프라인 테스트 결과 (PASS)

2026-10-20 자동화 가상 시뮬레이션을 통해 전 과정이 정상 동작함을 검증하였습니다.

1. **신규 방문자 감지 (`Guest #1`)**:
   - 가상 고객 최초 출입 시 YuNet 얼굴 감지 및 SFace 특징 벡터(Embedding) 추출
   - 신규 프로필 생성 및 얼굴 스냅샷 저장 (`captured_faces/`)
   - 관리자 텔레그램 알림 자동 전송 확인
2. **재방문자 재식별 (Visit Count 2)**:
   - 고객 재출입 시 코사인 유사도 기반 기존 프로필 매칭 성공
   - 누적 방문 횟수(2회) 자동 갱신 및 자체 학습(Self-Learning) 임베딩 보정
3. **결과 비디오 렌더링**:
   - 실시간 관제 대시보드 오버레이가 적용된 영상 파일 정상 생성 (`simulation_result.mp4`)