static/IMPLEMENTATION_GUIDE.md

POS 데이터 파일 업로드 웹 서버 - 구현 요약

📋 프로젝트 구조

static/
├── app/                          # Flask 웹 애플리케이션
│   ├── __init__.py
│   ├── app.py                    # 메인 Flask 앱 (포트 8889)
│   ├── file_processor.py         # 파일 처리 로직
│   ├── templates/
│   │   └── index.html            # Bootstrap UI (드래그앤드롭, 실시간 모니터링)
│   └── static/                   # CSS, JS 정적 파일
├── lib/
│   ├── pos_update_daily_product.py    # OKPOS 파일 처리 (process_okpos_file())
│   ├── pos_update_upsolution.py       # UPSOLUTION 파일 처리 (process_upsolution_file())
│   ├── common.py                # setup_logging(), get_logger()
│   └── ...                       # 기타 데이터 수집 모듈
├── conf/
│   ├── db.py                     # DB 설정 (load_config, get_engine, get_session)
│   ├── db_schema.py              # DB 스키마 (pos, pos_ups_billdata 등)
│   ├── config.yaml               # 설정 파일
│   └── service-account-credentials.json
├── data/                         # 데이터 디렉토리
│   ├── finish/                   # 처리 완료 파일
│   └── cache/                    # 캐시 데이터
├── uploads/                      # 임시 파일 업로드 폴더 (웹 서버용)
├── dbbackup/                     # 데이터베이스 백업 폴더 (Docker 마운트)
├── logs/                         # 애플리케이션 로그
├── db_data/                      # 데이터베이스 데이터 (Docker 마운트)
├── output/                       # 출력 데이터
├── build/
│   └── Dockerfile                # 컨테이너 이미지 정의
├── docker-compose.yml            # 다중 컨테이너 오케스트레이션
├── requirements.txt              # Python 의존성
├── .env                          # 환경 변수
├── daily_run.py                  # 일일 자동 실행 스크립트
└── README.md                     # 프로젝트 문서

🔧 핵심 컴포넌트

1. Flask 웹 서버 (app/app.py)

포트: 8889

API 엔드포인트:

• GET / - 메인 페이지
• POST /api/upload - 파일 업로드 처리
• GET /api/status - 시스템 상태 조회
• POST /api/backup - 데이터베이스 백업 생성
• POST /api/restore - 데이터베이스 복구
• GET /api/backups - 백업 목록 조회

주요 기능:

• 최대 100MB 파일 크기 지원
• 한글 JSON 응답 지원
• 에러 핸들러 (413, 500)
• 종합적인 로깅

2. 파일 처리 로직 (app/file_processor.py)

클래스: FileProcessor

주요 메서드:

• get_file_type(filename) - UPSOLUTION, OKPOS 파일 타입 감지
• validate_file(filename) - 파일 검증 (확장자, 패턴)
• process_uploads(uploaded_files) - 다중 파일 배치 처리
• process_file(filepath, file_type) - 개별 파일 처리
• _process_okpos_file(filepath) - OKPOS 파일 처리
• _process_upsolution_file(filepath) - UPSOLUTION 파일 처리
• create_database_backup() - mysqldump를 통한 백업 생성
• restore_database_backup(filename) - mysql을 통한 복구
• list_database_backups() - 백업 목록 조회

파일 타입 감지 규칙:

• UPSOLUTION: 파일명에 "UPSOLUTION" 포함
• OKPOS: "일자별" + "상품별" 또는 "영수증별매출상세현황" 포함

지원 파일 형식: .xlsx, .xls, .csv

3. 파일 처리 함수

OKPOS 처리 (lib/pos_update_daily_product.py)

def process_okpos_file(filepath):
    # 반환: {'success': bool, 'message': str, 'rows_inserted': int}

UPSOLUTION 처리 (lib/pos_update_upsolution.py)

def process_upsolution_file(filepath):
    # 반환: {'success': bool, 'message': str, 'rows_inserted': int}

4. 웹 사용자 인터페이스 (app/templates/index.html)

디자인: Bootstrap 5.3.0

주요 기능:

• 드래그 앤 드롭 파일 업로드
• 파일 목록 표시 및 제거
• 실시간 시스템 상태 모니터링
  • 데이터베이스 연결 상태
  • 업로드 폴더 상태
  • 업로드된 파일 수
• 업로드 진행 상황 표시
• 데이터베이스 백업 생성
• 백업 목록 조회
• 백업 복구 기능
• 실시간 알림 (5초 자동 숨김)

색상 테마:

• 주색: #0d6efd (파란색)
• 성공: #198754 (녹색)
• 경고: #dc3545 (빨간색)

5. Docker 환경 설정

docker-compose.yml

서비스:

1. mariadb - MariaDB 11.2

   • 포트: 3306
   • 볼륨:
     • ./db_data:/var/lib/mysql - 데이터베이스 데이터
     • ./dbbackup:/dbbackup - 백업 폴더
     • ./conf/install.sql:/docker-entrypoint-initdb.d/init.sql - 초기화 스크립트

2. fg-static - Python 애플리케이션

   • 포트: 8889 (Flask), 5000 (기타)
   • 볼륨:
     • ./uploads:/app/uploads - 파일 업로드 폴더
     • ./dbbackup:/app/dbbackup - 백업 폴더
     • ./data:/app/data - 데이터 폴더
     • ./logs:/app/logs - 로그 폴더
   • 헬스체크: /api/status 엔드포인트

Dockerfile

베이스 이미지: python:3.11-slim-bullseye

설치 패키지:

• gcc, g++, build-essential
• libmysqlclient-dev, libssl-dev, libffi-dev
• curl, wget, git, cron
• mariadb-client (mysqldump, mysql 도구)

실행 서비스:

1. Cron 데몬 - 일일 자동 실행
2. File Watch 서비스 - 로컬 파일 감시
3. Flask 웹 서버 - 포트 8889

6. 환경 변수 (.env)

DB_ROOT_PASSWORD=rootpassword
DB_NAME=firstgarden
DB_USER=firstgarden
DB_PASSWORD=Fg9576861!
DB_PORT=3306
DB_HOST=mariadb
TZ=Asia/Seoul
PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1
LOG_LEVEL=INFO
FLASK_ENV=production
FLASK_DEBUG=0

📊 데이터 처리 흐름

웹 브라우저
    ↓
드래그 앤 드롭 파일 선택
    ↓
POST /api/upload (FormData)
    ↓
Flask app.upload_files()
    ↓
FileProcessor.process_uploads()
    ├─ 파일 검증 (확장자, 패턴)
    │
    ├─ 파일 저장 (uploads/)
    │
    ├─ FileProcessor.process_file()
    │  ├─ OKPOS 감지 → _process_okpos_file()
    │  │              → process_okpos_file() 호출
    │  │              → pos 테이블 저장
    │  │
    │  └─ UPSOLUTION 감지 → _process_upsolution_file()
    │                      → process_upsolution_file() 호출
    │                      → pos_ups_billdata 테이블 저장
    │
    └─ 성공: 파일 삭제, 응답 반환
       실패: 에러 로깅, 에러 응답 반환
    ↓
JSON 응답 (성공/실패, 메시지, 행 수)
    ↓
HTML UI 업데이트

🔄 백업/복구 흐름

백업 생성

웹 UI "백업 생성" 클릭
    ↓
POST /api/backup
    ↓
FileProcessor.create_database_backup()
    ↓
mysqldump 실행
    (hostname, user, password, database)
    ↓
./dbbackup/backup_YYYYMMDD_HHMMSS.sql 생성
    ↓
JSON 응답 (filename)

복구

웹 UI "복구" 버튼 클릭
    ↓
POST /api/restore (filename)
    ↓
FileProcessor.restore_database_backup()
    ↓
mysql 실행 (backup_YYYYMMDD_HHMMSS.sql)
    ↓
성공/실패 응답

🚀 시작 방법

Docker Compose로 실행

# 이미지 빌드 및 서비스 시작
cd /path/to/static
docker-compose up -d

# 로그 확인
docker-compose logs -f fg-static

# 웹 접근
http://localhost:8889

필수 디렉토리

• ./uploads/ - 파일 업로드 (자동 생성)
• ./dbbackup/ - 백업 폴더 (자동 생성)
• ./logs/ - 로그 폴더 (자동 생성)
• ./db_data/ - DB 데이터 (자동 생성)

📝 로깅

로그 위치:

• Flask 앱: /app/logs/flask_app.log
• Cron: /app/logs/cron.log
• File Watch: /app/logs/file_watch.log
• 일일 실행: /app/logs/daily_run.log

Docker 컨테이너 로그:

docker-compose logs fg-static

✅ 검증 체크리스트

• Flask 앱이 포트 8889에서 실행
• 파일 업로드 endpoint 구현
• OKPOS/UPSOLUTION 파일 타입 감지
• 파일 검증 로직
• DB 저장 함수 (process_okpos_file, process_upsolution_file)
• 백업/복구 기능 (mysqldump/mysql)
• Bootstrap UI (드래그앤드롭, 실시간 모니터링)
• Docker 바인드 마운트 설정
• 환경 변수 설정
• 한글 주석 추가
• 종합적인 로깅

🔌 의존성

Python 패키지:

• Flask==3.0.0
• SQLAlchemy==2.0.23
• pandas==2.1.3
• openpyxl==3.1.2
• xlrd==2.0.1
• Werkzeug (secure_filename)

시스템 도구:

• mysqldump (DB 백업)
• mysql (DB 복구)

Docker 이미지:

• python:3.11-slim-bullseye
• mariadb:11.2-jammy

---

최종 업데이트: 2025년 완성 상태: 프로덕션 준비 완료