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)
```python
def process_okpos_file(filepath):
    # 반환: {'success': bool, 'message': str, 'rows_inserted': int}
```

#### UPSOLUTION 처리 (lib/pos_update_upsolution.py)
```python
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로 실행
```bash
# 이미지 빌드 및 서비스 시작
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 컨테이너 로그:**
```bash
docker-compose logs fg-static
```

## ✅ 검증 체크리스트

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

## 🔌 의존성

**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년 완성
**상태:** 프로덕션 준비 완료