feat: Flask 애플리케이션 모듈화 및 웹 대시보드 구현

- Flask Blueprint 아키텍처로 전환 (dashboard, upload, backup, status) - app.py 681줄 95줄로 축소 (86% 감소) - HTML 템플릿 모듈화 (base.html + 기능별 templates) - CSS/JS 파일 분리 (common + 기능별 파일) - 대시보드 기능 추가 (통계, 주간 예보, 방문객 추이) - 파일 업로드 웹 인터페이스 구현 - 백업/복구 관리 UI 구현 - Docker 배포 환경 개선 - .gitignore 업데이트 (uploads, backups, cache 등)
2025-12-26 17:31:37 +09:00
parent 9dab27529d
commit 7121f250bc
46 changed files with 6345 additions and 191 deletions
--- a/DASHBOARD_GUIDE.md
+++ b/DASHBOARD_GUIDE.md
@ -0,0 +1,307 @@
+# 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일
+**상태**: ✅ 완전 완성
+
+모든 요구사항이 구현되었으며, 프로덕션 레벨의 웹 대시보드로 준비 완료입니다!