static/DASHBOARD_GUIDE.md

POS 데이터 웹 대시보드 - 완성 요약

📊 대시보드 기능

1. 통계 카드 (대시보드 탭)

• OKPOS 일자별 상품별 데이터

  • 최종 저장일
  • 총 저장일수
  • 총 데이터 개수

• OKPOS 영수증별 데이터

  • 최종 저장일
  • 총 저장일수
  • 총 데이터 개수

• UPSOLUTION 데이터

  • 최종 저장일
  • 총 저장일수
  • 총 데이터 개수

• 날씨/기상 데이터

  • 최종 저장일
  • 총 저장일수
  • 총 데이터 개수

2. 주간 예보 테이블

• 이번 주(월요일~일요일) 날씨 및 방문객 예상
• 컬럼:
  • 날짜 (YYYY-MM-DD (요일))
  • 최저기온 (°C)
  • 최고기온 (°C)
  • 강수량 (mm)
  • 습도 (%)
  • 예상 방문객 (명)

3. 방문객 추이 그래프

• 날짜 범위 선택 가능

  • 시작 날짜: 달력 선택기
  • 종료 날짜: 달력 선택기
  • "조회" 버튼: 선택된 기간 데이터 표시
  • "최근 1개월" 버튼: 기본값으로 초기화 (최근 30일)

• 라인 차트 표시

  • X축: 날짜
  • Y축: 방문객 수
  • 상호작용 가능한 차트 (Chart.js 기반)

---

🔌 새로운 API 엔드포인트

GET /api/dashboard/okpos-product

응답:

{
  "last_date": "2025-12-26",
  "total_days": 45,
  "total_records": 12345,
  "message": "12345건의 데이터가 45일에 걸쳐 저장됨"
}

GET /api/dashboard/okpos-receipt

응답:

{
  "last_date": "2025-12-26",
  "total_days": 30,
  "total_records": 5678,
  "message": "5678건의 데이터가 30일에 걸쳐 저장됨"
}

GET /api/dashboard/upsolution

응답:

{
  "last_date": "2025-12-26",
  "total_days": 25,
  "total_records": 8901,
  "message": "8901건의 데이터가 25일에 걸쳐 저장됨"
}

GET /api/dashboard/weather

응답:

{
  "last_date": "2025-12-26",
  "total_days": 365,
  "total_records": 87600,
  "message": "87600건의 데이터가 365일에 걸쳐 저장됨"
}

GET /api/dashboard/weekly-forecast

응답:

{
  "forecast_data": [
    {
      "date": "2025-12-29",
      "day": "월",
      "min_temp": 3,
      "max_temp": 12,
      "precipitation": 0.5,
      "humidity": 65,
      "expected_visitors": 245
    },
    ...
  ],
  "message": "2025-12-29 ~ 2026-01-04 주간 예보"
}

GET /api/dashboard/visitor-trend?start_date=2025-11-26&end_date=2025-12-26

파라미터:

• start_date (선택): YYYY-MM-DD 형식의 시작 날짜
• end_date (선택): YYYY-MM-DD 형식의 종료 날짜
• days (선택): 조회할 일수 (기본값: 30)

응답:

{
  "dates": ["2025-11-26", "2025-11-27", ...],
  "visitors": [120, 145, ...],
  "message": "30일 동안 3,650명 방문"
}

---

📱 UI/UX 개선사항

레이아웃

• 탭 네비게이션: 3개 탭 (대시보드, 파일 업로드, 백업 관리)
• 반응형 디자인: 모바일/태블릿/데스크톱 모두 지원
• 그래디언트 배경: 직관적이고 현대적인 디자인

시각화

• 카드 기반 통계: 4개 통계 카드 (색상 구분)

  • OKPOS 상품별: 보라색 그래디언트
  • OKPOS 영수증: 분홍색 그래디언트
  • UPSOLUTION: 파란색 그래디언트
  • 날씨: 초록색 그래디언트

• 인터랙티브 차트: Chart.js 라이브러리

  • 라인 차트로 방문객 추이 표시
  • 호버 시 데이터 포인트 확대
  • 반응형 크기 조정

사용자 경험

• 실시간 업데이트: 대시보드 30초마다 자동 새로고침
• 즉시 피드백: 데이터 로딩 상태 표시
• 접근성: Bootstrap 및 Bootstrap Icons 활용
• 모바일 최적화: 터치 친화적 인터페이스

---

📂 파일 구조

app/
├── app.py                     # Flask 애플리케이션 (추가된 대시보드 API)
├── file_processor.py         # 파일 처리 로직
├── templates/
│   └── index.html            # 완전히 개선된 대시보드 UI
└── static/
    └── (CSS/JS 파일들)

app.py 추가 사항

• GET /api/dashboard/okpos-product
• GET /api/dashboard/okpos-receipt
• GET /api/dashboard/upsolution
• GET /api/dashboard/weather
• GET /api/dashboard/weekly-forecast
• GET /api/dashboard/visitor-trend

index.html 개선 사항

1. 대시보드 탭

   • 4개 통계 카드
   • 주간 예보 테이블
   • 방문객 추이 그래프
   • 날짜 범위 선택 컨트롤

2. 파일 업로드 탭

   • 기존 드래그 앤 드롭 기능 유지
   • 시스템 상태 표시
   • 실시간 진행 표시

3. 백업 관리 탭

   • 백업 생성/복구 기능

---

🎨 디자인 특징

색상 스키마

• Primary: #0d6efd (파란색)
• Success: #198754 (녹색)
• Danger: #dc3545 (빨간색)
• Info: #0dcaf0 (하늘색)
• Background: 보라색 그래디언트 (667eea → 764ba2)

타이포그래피

• 폰트: Segoe UI, Tahoma, Geneva, Verdana, Arial
• 크기 계층구조: h1, h3, h5, body 텍스트
• 가중치: 600 (중간 굵기), 700 (굵음)

간격

• 패딩: 20px, 25px, 30px
• 마진: 10px, 15px, 20px, 30px
• 갭: 10px, 15px

---

🚀 배포 및 실행

요구 사항

• Python 3.11+
• Flask 3.0.0
• Chart.js (CDN)
• Bootstrap 5.3.0 (CDN)

실행 명령

cd /path/to/static
docker-compose up -d

# 웹 브라우저에서 접근
http://localhost:8889

포트 및 서비스

• 포트 8889: Flask 웹 서버
• 포트 3306: MariaDB 데이터베이스
• 포트 5000: 기타 서비스 (선택)

---

📊 데이터 소스

데이터베이스 테이블

1. pos - OKPOS 상품별 데이터
2. pos_billdata - OKPOS 영수증 데이터
3. pos_ups_billdata - UPSOLUTION 데이터
4. weather - 기상청 날씨 데이터
5. ga4_by_date - GA4 방문자 데이터

쿼리 최적화

• COUNT(DISTINCT date): 저장 일수 계산
• MAX(date): 최종 저장일 확인
• COUNT(*): 총 데이터 수 계산
• AVG(users): 예상 방문객 계산

---

✅ 완성된 요구사항

✅ 메인(대시보드) 페이지 구현 ✅ OKPOS 일자별 상품별 데이터 통계 ✅ OKPOS 영수증데이터 통계 ✅ UPSOLUTION 데이터 통계 ✅ 날씨/기상정보 데이터 통계 ✅ 이번 주 예상 날씨와 방문객 예상 표 ✅ 방문객 추이 그래프 (날짜 조절 가능) ✅ 기본값: 최근 1개월 ✅ 3개 탭 네비게이션 ✅ Bootstrap 디자인 ✅ 실시간 데이터 업데이트 ✅ 반응형 레이아웃

---

🎯 사용자 흐름

1. 대시보드 접속

   • URL: http://localhost:8889
   • 자동 통계 로드
   • 30초마다 새로고침

2. 데이터 조회

   • 4개 카드에서 실시간 통계 확인
   • 주간 예보 테이블에서 추이 파악
   • 방문객 그래프로 트렌드 분석

3. 날짜 조절

   • 시작/종료 날짜 선택
   • "조회" 버튼 클릭
   • 그래프 자동 업데이트

4. 파일 관리 (필요 시)

   • "파일 업로드" 탭 전환
   • 파일 드래그 앤 드롭
   • 자동 처리 및 DB 저장

5. 백업 관리 (필요 시)

   • "백업 관리" 탭 전환
   • 백업 생성/복구

---

마지막 업데이트: 2025년 12월 26일 상태: ✅ 완전 완성

모든 요구사항이 구현되었으며, 프로덕션 레벨의 웹 대시보드로 준비 완료입니다!