dash-db

월별 기성/출하 실적 분석 대시보드

Python과 Streamlit을 이용한 월별 기성/출하 실적 분석 대시보드입니다.

GitHub Pages와 Streamlit

GitHub Pages로 배포된 주소는 문서용 정적 사이트(Jekyll이 Markdown 등을 HTML로 변환한 결과)입니다. Streamlit 앱(app.py)은 Pages 환경에서 실행되지 않습니다. Python 서버가 필요한 대시보드는 아래 중 하나로 실행하세요.

1. 로컬: 저장소를 받은 뒤 pip install -r requirements.txt 후 streamlit run app.py (기본 http://localhost:8501).
2. 웹 공개: Streamlit Community Cloud에서 이 GitHub 저장소를 연결하고 메인 파일을 app.py로 지정해 배포합니다.

Actions에 표시되는 Node.js 20 관련 메시지는 러너 버전 안내이며, 위와 같은 Streamlit 미구동 현상의 원인이 아닙니다.

Vercel (안내 페이지)

Streamlit 앱 본체는 Vercel 서버리스에 맞지 않아, public/에는 안내용 정적 페이지만 두고 CLI로 배포합니다.

npx vercel deploy public --prod --yes --scope eureka0124s-projects

(팀 스코프는 Vercel 대시보드의 팀 슬러그에 맞게 바꾸세요. 비대화형이면 --scope가 필요할 수 있습니다.)

? 프로젝트 구조

dashdb/
├── app.py                    # 메인 대시보드 애플리케이션
├── data_loader.py            # CSV/Google Sheets 데이터 로드
├── data_processor.py         # 데이터 정제 및 가공
├── visualizations.py         # Plotly 차트 생성
├── config.py                 # 설정 관리
├── requirements.txt          # Python 의존성
├── .env                      # 환경 변수
├── README.md                 # 이 파일
├── 기성실적DB.csv            # 기성실적 데이터 (11개 컬럼, ~3,000행)
├── 출하실적DB.csv            # 출하실적 데이터 (24개 컬럼, ~9,000행)
└── 기성목표DB.csv            # 기성목표 데이터 (11개 컬럼, ~700행)

? 설치 및 실행

1. 필수 요구사항

• Python 3.10 이상
• pip (Python 패키지 관리자)

2. 의존성 설치

pip install -r requirements.txt

3. 대시보드 실행

Windows: 프로젝트 폴더에서 run_local.bat을 더블클릭하면 의존성 설치 후 브라우저로 대시보드가 열립니다.
(명령은 명령 프롬프트(cmd) 또는 PowerShell에서 실행하세요. python만 치면 뜨는 대화형 창(»> ) 안에서는 pip / streamlit 명령이 동작하지 않습니다.)

py -m pip install -r requirements.txt
py -m streamlit run app.py

py 명령이 없으면 python으로 바꿉니다. 대시보드는 기본적으로 http://localhost:8501에서 실행됩니다.

? 의존성

패키지	버전	용도
streamlit	1.28.1	웹 대시보드 UI
pandas	2.0.3	데이터 처리 및 분석
plotly	5.17.0	인터랙티브 차트 시각화
python-dotenv	1.0.0	환경 변수 관리
gspread	5.10.0	Google Sheets API
oauth2client	4.1.3	Google API 인증
openpyxl	3.10.10	Excel 파일 처리
pytz	2023.3	타임존 처리

? 주요 기능

1. 기성 실적 분석 (?)

• 월별 기성액 추이 분석
• 기성 실적 데이터 조회
• 총 기성액 통계

2. 출하 실적 분석 (?)

• 월별 출하액 추이 분석
• 출하 실적 데이터 조회
• 총 출하액 통계

3. 기성 목표 달성률 (?)

• 목표 대비 실적 달성률
• 월별 달성률 추이
• 목표 달성 현황

4. 종합 비교 (?)

• 기성/출하/목표 데이터 통합 분석
• 다중 지표 비교

? 설정

config.py

• DATA_DIR: 데이터 파일 위치
• DATA_FILES: 각 데이터 파일 경로
• STREAMLIT_CONFIG: Streamlit 페이지 설정
• DATE_FORMAT: 날짜 포맷

.env

GOOGLE_SHEETS_CREDENTIALS_PATH=credentials.json

Google Sheets 연동을 원하면 Google API 인증 파일(credentials.json)을 설정하세요.

? 데이터 형식

각 CSV 파일의 예상 포맷:

기성실적DB.csv

• 11개 컬럼
• 약 3,000행
• 기성 실적 관련 정보 (금액, 날짜 등)

출하실적DB.csv

• 24개 컬럼
• 약 9,000행
• 출하 실적 관련 정보 (금액, 날짜, 상품정보 등)
• 매일 자동 업데이트

기성목표DB.csv

• 11개 컬럼
• 약 700행
• 기성 목표 관련 정보 (목표액, 시기 등)

? Google Sheets 연동 (선택사항)

Google Sheets에서 직접 데이터를 로드하려면:

1. Google Cloud Console에서 Service Account 생성
2. JSON 인증 파일 다운로드
3. credentials.json으로 프로젝트 디렉토리에 저장
4. .env 파일에 경로 설정

from data_loader import connect_google_sheets
client = connect_google_sheets('credentials.json')

? 향후 개선 사항

• 월별 데이터 자동 집계 기능
• 동적 차트 필터링
• 데이터 다운로드 기능
• 예측 분석 모델 추가
• 알림 및 이상탐지
• 사용자 정의 리포트 생성
• API 엔드포인트 추가

? 문제 해결

CSV 파일 인코딩 오류

CSV 파일이 UTF-8 인코딩으로 저장되어 있는지 확인하세요.

Streamlit 포트 충돌

다른 포트에서 실행하려면:

streamlit run app.py --server.port 8502

데이터 로드 실패

1. CSV 파일이 올바른 경로에 있는지 확인
2. 파일 이름이 정확한지 확인 (대소문자 구분)
3. 파일 권한 확인

? 문의

문제가 발생하면 각 모듈의 오류 메시지를 확인하세요.

? 라이선스

내부 사용 전용