프로젝트 소개

# Nebula Cafe — Predictive Footfall & Inventory Harmony System Nebula Cafe는 과거 리포팅을 넘어 예측 기반 의사결정으로 전환하려는 커피숍 오너 및 매니저를 위해 Streamlit으로 구축된 오픈소스 분석 대시보드입니다. 이 프로젝트는 고객 유입을 예측하고 재료 재고를 최적화하며, 따뜻하고 친근한 인터페이스로 운영 효율성과 균형을 맞추는 '의사결정 엔진'으로서 자신을 포지셔닝합니다. ## 핵심 목적 단순히 과거 판매량을 보고하는 전통적인 카페 분석 도구와 달리, Nebula Cafe는 시계열 예측(특히 LSTM 모델)을 사용하여 최대 7일 앞선 고객 트래픽을 예측합니다. 이를 통해 사용자는 다음이 가능합니다: - 예상되는 혼잡 시간대에 맞춰 지능적으로 인력을 배치 - JIT 방식으로 재고를 주문하여 부패성 폐기물 감소 (최대 30% 감소 주장) - 이벤트나 프로모션 일정을 위한 한산한 시간대 식별 - 여러 매장 간 패턴 비교 (지역 관리자용) ## 주요 기능 ### Predictive Footfall Mapping - 7일 고객 수 예측을 위한 LSTM 기반 시계열 모델 - 신뢰 구간이 시각화된 타임라인 ('구름 밴드'로 표현됨) - 공휴일 및 날씨 데이터를 기반으로 한 동적 조정 (선택적 API 통합) ### Intelligent Inventory Advisor - 예측된 매출과 현재 재고 수준을 교차 참조 - 색상 구분 재주문 목록 생성: 녹색 (재고 있음), 호박색 (2일 내 주문 필요), 빨간색 (즉시 주문 필요) - 과거 과잉 재고 실수로부터 학습하여 향후 추천 개선 ### User Experience - 태블릿 또는 스마트폰 화면에 적응하는 드래그 앤 드롭 위젯 레이아웃 - 영어, 스페인어, 중국어, 아랍어를 지원하는 다국어 UI - 내장 FAQ/지원 봇 (규칙 기반, 외부 API 키 불필요) - 색상 및 글꼴 커스터마이징을 위한 노코드 테마 에디터 - 인터넷 없이도 모든 기능을 사용할 수 있는 오프라인 모드 ### Privacy & Data Handling - 기본적으로 모든 데이터가 로컬에서 처리되며 클라우드 업로드 없음 - 인증 키 불필요 - 익명화된 집계를 통해 고객의 PII 저장 방지 - 테스트 및 실험을 위한 선택적 합성 데이터 생성기 ## Technology Stack - **Frontend:** Custom CSS를 사용한 Streamlit (JavaScript 라이브러리 없음) - **Backend:** Pandas, NumPy 및 Prophet을 활용한 Python 3.10+ - **Data Storage:** 로컬 CSV/JSON 파일 (선택적 SQLite 지원) - **Visualization:** 대화형 차트를 위한 Plotly, 정적 내보내기를 위한 Matplotlib - **Testing:** 단위 및 통합 테스트를 위한 PyTest ## Use Cases - **Solo Cafe Owner:** 예상되는 한산한 기간 동안 이벤트 계획 - **Regional Manager:** 직원 재배치를 위해 여러 매장의 유동 인구 비교 - **Roastery Partner:** 주간 원두 배송량 결정을 위해 Inventory Advisor 활용 - **Investor:** ROI 지표 및 고객 밀도 추세가 포함된 주간 보고서 내보내기 ## Roadmap (2026) - **Q1 2026:** 핵심 예측 및 재고 모듈 포함 v1.0 릴리스 - **Q2 2026:** 공개 메뉴 스크레이퍼를 통한 선택적 경쟁사 가격 추적 - **Q3 2026:** Open API를 통한 Square/Toast POS 통합 - **Q4 2026:** 즉각적인 유동 인구 알림을 위한 모바일 컴패니언 앱 (Flutter) ## Installation & Usage 사용자는 GitHub 페이지에서 ZIP 파일로 저장소를 다운로드하거나 git 클라이언트를 사용하여 복제할 수 있습니다. 이 프로젝트에는 Python 3.10+와 저장소에 나열된 의존성이 필요합니다. 설치 마법사는 필요하지 않으며 순수한 Python 코드만 사용합니다. ## Community & Contribution 다음과 같은 기여를 환영합니다: - 새로운 예측 모델 추가 (예: ARIMA, Facebook Prophet) - UI를 추가 언어로 번역 - 환경 지표(주변 소음, 온도)를 위한 새 위젯 디자인 프로젝트에는 `docs/` 폴더에 문서화가 포함되어 있으며 커뮤니티 지원을 위해 GitHub 이슈와 토론을 사용합니다. ## License MIT 라이선스에 따라 상업적 또는 비상업적 용도로 무료 사용, 수정 및 배포가 허용됩니다. ## Disclaimer 소프트웨어는 보증 없이 "있는 그대로" 제공됩니다. 예측 모델은 데모용으로 합성 훈련 데이터에 의존하며 보정 없이는 실제 정확도를 반영하지 못할 수 있습니다. 개발자는 대시보드 출력에 기반한 비즈니스 결정에 대해 책임을 지지 않습니다. 지원 봇은 크립트된 FAQ 어시스턴트이며 실시간 인간 상담원이 아닙니다. 사용자는 항상 물리적 카운트로 재고 추천 사항을 검증해야 합니다.