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`
**응답:**
```json
{
  "last_date": "2025-12-26",
  "total_days": 45,
  "total_records": 12345,
  "message": "12345건의 데이터가 45일에 걸쳐 저장됨"
}
```

### GET `/api/dashboard/okpos-receipt`
**응답:**
```json
{
  "last_date": "2025-12-26",
  "total_days": 30,
  "total_records": 5678,
  "message": "5678건의 데이터가 30일에 걸쳐 저장됨"
}
```

### GET `/api/dashboard/upsolution`
**응답:**
```json
{
  "last_date": "2025-12-26",
  "total_days": 25,
  "total_records": 8901,
  "message": "8901건의 데이터가 25일에 걸쳐 저장됨"
}
```

### GET `/api/dashboard/weather`
**응답:**
```json
{
  "last_date": "2025-12-26",
  "total_days": 365,
  "total_records": 87600,
  "message": "87600건의 데이터가 365일에 걸쳐 저장됨"
}
```

### GET `/api/dashboard/weekly-forecast`
**응답:**
```json
{
  "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)

**응답:**
```json
{
  "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)

### 실행 명령
```bash
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일
**상태**: ✅ 완전 완성

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