📦 물류 데이터 통합 시스템 v3.19

프로젝트 개요

이름: 물류 데이터 통합 시스템
목적: 물류 현장에서 발생하는 제각각인 엑셀/CSV 데이터를 하나로 통합하고, 3PL 배송 양식으로 자동 변환
기술 스택: Python, Streamlit, Pandas, OpenPyXL, XlsxWriter
GitHub: https://github.com/urimeee/LogiFlow-Auto

🌐 웹 애플리케이션 URL

실행 중인 서비스: https://3000-ip2l928h0vug305w91va9-d0b9e1e2.sandbox.novita.ai

위 URL로 접속하여 바로 사용하실 수 있습니다!

🚀 설치 및 실행

1. 저장소 클론

git clone https://github.com/urimeee/LogiFlow-Auto.git
cd LogiFlow-Auto

2. 가상환경 생성 및 활성화 (선택사항)

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 또는
venv\Scripts\activate  # Windows

3. 의존성 설치

pip install -r requirements.txt

4. 환경변수 설정

# .env.example 파일을 .env로 복사
cp .env.example .env

# .env 파일 편집 (필요한 경우)
# API_KEY=your_api_key_here

5. 애플리케이션 실행

streamlit run app.py

브라우저에서 http://localhost:8501로 접속하세요.

🔒 보안 및 환경변수

환경변수 파일 (.env)

• 절대 GitHub에 커밋하지 마세요!
• .env.example 템플릿을 참고하여 .env 파일 생성
• API 키, 비밀번호 등 민감한 정보는 .env에만 저장

지원하는 환경변수

# 애플리케이션 설정
APP_NAME=물류 데이터 통합 시스템
APP_VERSION=3.16
MAX_UPLOAD_SIZE=200
LOG_LEVEL=INFO

# 향후 확장 가능 (API 키 등)
# API_KEY=your_api_key_here
# SECRET_KEY=your_secret_key_here

📋 32개 표준 3PL 배송 컬럼 (v3.4+)

시스템은 다음 32개의 표준 3PL 배송 양식 컬럼을 출력합니다:

#	컬럼명	값 예시	설명
1	쇼핑몰 코드	ONLINE1	고정값
2	쇼핑몰 이름	카페24, 앱, 쿠팡, 네이버	플랫폼 자동 감지
3	쇼핑몰 묶음 배송 번호	(주문번호와 동일)	자동 복사
4	묶음배송유무	유	고정값
5	접수일시	2026-02-25	오늘 날짜 자동 입력
6	결제일시	2026-02-25	오늘 날짜 자동 입력
7	수취인 상세 주소	.	고정값
8	수취인 전화[안심 번호]	(수취인 핸드폰)	자동 복사
9	수취인 전화번호	(수취인 핸드폰)	자동 복사
10	수취인 건물 관리번호	(공백)	빈 값
11	주문자 명	(수취인 명)	자동 복사
12	주문자 이메일	AA@aa.com	고정값
13	수취인 우편번호	(공백)	빈 값
14	수취인 주소 유형	미확인	고정값
15	주문자 전화[안심 번호]	(수취인 핸드폰)	자동 복사
16	주문자 전화번호	(수취인 핸드폰)	자동 복사
17	주문자 핸드폰	(수취인 핸드폰)	자동 복사
18	추가 상품 여부	추가상품	고정값
19	택배 운임 지불 방식	신용	고정값
20	쇼핑몰 주문 라인번호	1, 2, 3...	순차 번호 (v3.4+)
21	결제금액	(공백)	빈 값
22	고객 참조번호	(공백)	빈 값
23	요청(희망)배송 일자	2026-02-25	오늘 날짜 (v3.4+)
24	쇼핑몰 주문번호	20260220-0000171	주문번호
25	수취인 명	홍길동	원본 데이터
26	수취인 핸드폰	010-1234-5678	원본 데이터
27	수취인 기본 주소	서울시 강남구...	원본 데이터
28	쇼핑몰 상품 코드	DA-DI-PW	매칭 결과
29	쇼핑몰 상품 이름	딥 페리윙클	매칭 결과
30	쇼핑몰 옵션 이름	DI-PW	매칭 결과
31	주문 수량	1 (앱), N (기타)	앱은 항상 1 (v3.7)
32	배송 메세지	벨x, 문자 (앱)	앱은 고정값 (v3.7)

추가 디버깅 컬럼 (33-34):

• 33: 매칭 방법 (코드 정확 매칭, 상품명 패턴 매칭 등)
• 34: 확인 필요 (True/False)

🎯 v3.7 주요 변경사항

• 앱 파일 특별 처리:
  • 주문 수량: 항상 1로 고정
  • 배송 메세지: 항상 **"벨x, 문자"**로 고정

🎯 v3.4-v3.5 주요 변경사항

• 쇼핑몰 주문 라인번호 (20번): 1부터 시작하는 순차 번호 자동 생성 (int64)
  • 다중 플랫폼 통합 시 중복 방지: 전체 데이터에 대해 1~N 순번 재할당
• 요청(희망)배송 일자 (23번): 오늘 날짜 자동 입력 (YYYY-MM-DD 형식)

---

🎯 v3.0 주요 업데이트

✨ 통합 다중 플랫폼 지원

• 단일 페이지에서 카페24, 앱, 쿠팡, 네이버 모든 파일 동시 업로드
• 자동 플랫폼 감지: 파일 업로드 시 자동으로 플랫폼 분류
• 플랫폼별 통계: 각 플랫폼의 매칭 결과를 한눈에 확인
• 10개 컬럼 출력: 플랫폼 컬럼 추가로 출처 명확화

🔍 플랫폼별 매칭 로직

• 카페24: 자체품목코드 → 마스터 판매 상품 코드 매칭 (100%)
• 쿠팡: 옵션ID → 마스터 판매 상품 코드 매칭 (100%)
• 앱: 주문상품 파싱 ([상품명] N개 (옵션)) → 마스터 판매 상품 코드 패턴 매칭 (100%)
  • 특별 처리: 주문 수량 항상 1, 배송 메세지 항상 "벨x, 문자"
• 네이버: 상품번호 → 마스터 판매 상품 코드 매칭

🐛 v3.0.3 버그 수정

• 플랫폼 이름 매핑 추가: 영문(cafe24) → 한글(카페24) 자동 변환
• KeyError 해결: 마스터 데이터 필터링 시 한글 판매처명 사용
• Arrow 타입 오류 수정: 모든 컬럼을 문자열로 변환하여 Streamlit 호환성 개선

---

주요 기능

✨ 핵심 기능

• 🎯 3PL 배송 양식 자동 변환 (NEW!)
• 🧠 지능형 상품 코드 매칭 (NEW!)
• 📊 매칭 결과 분석 및 통계 (NEW!)
• 📤 다중 파일 업로드: 여러 엑셀/CSV 파일을 동시에 업로드
• 🔄 자동 컬럼 표준화: 각기 다른 컬럼명을 표준 형식으로 자동 통합
• 🌐 한글 인코딩 처리: UTF-8, CP949, EUC-KR 등 자동 감지 및 처리
• 🔓 암호화 파일 지원: 암호로 보호된 엑셀 파일 자동 복호화 시도
• 📊 다양한 엑셀 형식: XLSX, XLS 구형 형식 모두 지원
• 📥 날짜별 다운로드: {오늘날짜}_3PL배송업무.xlsx 형식으로 자동 저장
• 👀 실시간 미리보기: 통합된 데이터를 즉시 확인

---

💼 통합 다중 플랫폼 모드

📤 단일 페이지 업로드

• 마스터 코드 파일 1개 + 모든 플랫폼 파일을 동시에 업로드
• 자동 플랫폼 감지 및 분류
• 실시간 파일 정보 표시

🎯 지원 플랫폼

1. 카페24: CSV 파일, 자체품목코드 기반 매칭
2. 앱: CSV 파일, 주문상품 파싱 후 매칭
3. 쿠팡: XLSX 파일, 옵션ID 기반 매칭
4. 네이버: CSV/XLSX 파일, 상품번호 기반 매칭

---

📋 3PL 표준 양식 컬럼 (v3.0)

컬럼명	설명	소스
플랫폼	주문 플랫폼	cafe24, app, coupang, naver
주문번호	주문 고유 번호	주문번호
수취인 명	받는 사람 이름	받는사람
수취인 핸드폰	받는 사람 연락처	수령인휴대폰
수취인 기본 주소	배송 주소	배송주소
쇼핑몰 상품 코드	상품 코드	자체품목코드 → 매칭
쇼핑몰 상품 이름	상품명	상품명 → 매칭
쇼핑몰 옵션 이름	옵션 정보	옵션 → 매칭
주문 수량	주문 개수	수량
배송 메세지	배송 요청사항	배송메세지
매칭 방법	매칭 알고리즘	코드 정확 매칭, 상품명 매칭 등
확인 필요	수동 확인 필요 여부	True/False

---

🔍 매칭 알고리즘 로직

✅ v3.0 업데이트: 플랫폼별 매칭 전략

플랫폼별 코드 추출:

• 카페24: 자체품목코드 → 마스터 판매 상품 코드
• 쿠팡: 옵션ID → 마스터 판매 상품 코드
• 앱: 주문상품 파싱 ([상품명] N개 (옵션)) → 상품명 추출
• 네이버: 상품번호 → 마스터 판매 상품 코드

3단계 지능형 매칭

1단계: 판매 상품 코드 정확 매칭 ⭐
    입력 파일의 코드 == 마스터 판매 상품 코드
    ✅ 100% 정확 매칭 (확인 필요 없음)
    예시:
      - 카페24: DA_DIP_PW → DA-DI-PW (딥 페리윙클)
      - 쿠팡: 9353006240 → C-AR-GRK-03 (극락 3개)

2단계: 상품명 + 옵션명 조합 매칭
    입력 상품명 포함 검사 → 마스터 쇼핑몰 상품 이름
    +
    입력 옵션명 포함 검사 → 마스터 쇼핑몰 옵션 이름
    ⚠️ 옵션 없을 시 확인 필요 표시

3단계: 유사도 기반 추천
    상품명 유사도 (70%) + 옵션명 유사도 (30%)
    유사도 50% 이상 → 자동 추천
    ⚠️ 확인 필요 표시

📊 실제 테스트 결과 (v3.0.3)

플랫폼	테스트 건수	매칭 성공률	비고
카페24	49건	49/49 (100%)	✅
쿠팡	26건	26/26 (100%)	✅
앱	1건	마스터 데이터 필요	⚠️
네이버	-	마스터 8건 준비	✅

---

사용 방법

🎯 통합 다중 플랫폼 모드 사용법

1단계: 마스터 코드 업로드

1. 사이드바에서 물류_코드명.xlsx 파일 업로드
2. "✅ 마스터 코드 데이터 로드 완료" 메시지 확인
3. 플랫폼별 상품 수 확인 (예: 카페24 65개, 쿠팡 4개, 네이버 8개, 앱 1개)

2단계: 모든 플랫폼 파일 동시 업로드

1. 메인 영역 파일 업로더에서 여러 파일 동시 선택
   • 카페24 CSV 파일
   • 앱 CSV 파일
   • 쿠팡 XLSX 파일
   • 네이버 CSV 파일
2. 자동으로 플랫폼 감지 및 분류
3. 각 플랫폼별 파일 개수 확인

3단계: 매칭 결과 확인

• 파일 정보 테이블: 플랫폼별 원본 행 수, 매칭 성공률, 확인 필요 항목 수
• 통합 결과 통계: 총 주문 수, 매칭 성공, 확인 필요, 처리 플랫폼 수
• 플랫폼별 통계: 각 플랫폼의 주문 수와 확인 필요 항목
• 매칭 방법별 분석: 코드 정확 매칭, 상품명 매칭 등 통계

4단계: 데이터 미리보기

• 전체 데이터 테이블 확인
• "확인 필요 항목만 보기" 필터 사용
• 노란색 강조 항목 수동 확인

5단계: 다운로드

• "📥 통합 파일 다운로드" 버튼 클릭
• YYYYMMDD_통합3PL배송업무.xlsx 파일 저장
• 확인 필요 항목은 수동으로 최종 확인

---

✏️ 수동 주문 입력 기능 (v3.19+)

시딩/CS 주문을 직접 입력하여 3PL 형식으로 추가

🎯 주요 기능:

• ✅ 다중 수취인 입력: 한 번에 여러 명의 수취인 정보 입력 가능
• ✅ 자동 주문번호 생성: {날짜}_{Seed/CS}_{a,b,c,...} 형식
• ✅ 자동 상품코드 생성: {날짜}_{Seed/CS}_{a,b,c,...} 형식
• ✅ 입력값 검증: 수취인, 전화번호, 주소 개수 일치 확인
• ✅ 실시간 목록 표시: 추가된 주문 목록 즉시 확인

사용 방법:

1. "✏️ 수동 입력" 탭 선택

2. 카테고리 선택: Seed 또는 CS

3. 다중 주문 정보 입력 (줄바꿈으로 구분):

   • 수취인 이름:

     김유림
     김종국
     이효리
     

   • 전화번호:

     010-1234-5678
     010-2345-6789
     010-3456-7890
     

   • 주소:

     서울시 강남구 테헤란로 123
     경기도 성남시 분당구 판교로 456
     부산시 해운대구 센텀대로 789
     

   • 상품명: 프리미엄 스킨케어 세트 (쇼핑몰 상품명/옵션명으로 사용)
   • 수량: 1
   • 배송 메시지 (선택사항)

4. "➕ 주문 추가" 버튼 클릭

5. 추가된 주문 확인:

   • 주문번호: 20260322_Seed_a, 20260322_Seed_b, 20260322_Seed_c
   • 쇼핑몰 상품 코드: 20260322_Seed_a, 20260322_Seed_b, 20260322_Seed_c

6. 3PL 변환에 자동 포함되어 처리

생성 예시:

카테고리: Seed
날짜: 2026-03-22

입력:
  - 수취인 3명 (김유림, 김종국, 이효리)
  - 상품명: 프리미엄 스킨케어 세트

생성 결과:
  1. 주문번호: 20260322_Seed_a
     쇼핑몰 상품 코드: 20260322_Seed_a
     쇼핑몰 상품명/옵션명: 프리미엄 스킨케어 세트
     
  2. 주문번호: 20260322_Seed_b
     쇼핑몰 상품 코드: 20260322_Seed_b
     쇼핑몰 상품명/옵션명: 프리미엄 스킨케어 세트
     
  3. 주문번호: 20260322_Seed_c
     쇼핑몰 상품 코드: 20260322_Seed_c
     쇼핑몰 상품명/옵션명: 프리미엄 스킨케어 세트

---

📊 물류_코드명 마스터 데이터 형식

필수 컬럼

컬럼명	설명	예시
판매처	판매 플랫폼 (한글)	카페24, 쿠팡, 네이버, 앱
판매 상품 코드	내부 상품 코드	DA_DIP_PW, 9353006240
쇼핑몰 상품 코드	외부 상품 코드	DA-DI-PW, C-AR-GRK-03
쇼핑몰 상품 이름	상품명	딥 페리윙클, 극락 3개
쇼핑몰 옵션 이름	옵션 정보	DI-PW, LFT4W
구성품	구성 품목	딥T, 극락T

⚠️ 중요 사항

• 판매처 컬럼: 반드시 한글로 입력 (카페24, 쿠팡, 네이버, 앱)
• 판매 상품 코드: 각 플랫폼의 고유 상품 코드와 정확히 일치해야 함
  • 카페24: 자체품목코드 값
  • 쿠팡: 옵션ID 값
  • 앱: 주문상품에서 파싱한 상품명
  • 네이버: 상품번호 값

---

지원 파일 형식

• ✅ Excel: .xlsx (최신 형식)
• ✅ Excel: .xls (구형 형식)
• ✅ CSV: .csv (UTF-8, CP949, EUC-KR 자동 감지)
• ✅ 암호 보호된 엑셀 파일 (빈 비밀번호 또는 VelvetSweatshop 알고리즘)

---

데이터 처리 흐름

일반 통합 모드

업로드 → 인코딩 감지 → 파일 읽기 → 컬럼 표준화 
    → 데이터 병합 → 엑셀 생성 → 다운로드

3PL 변환 모드

마스터 코드 로드
    ↓
카페24 CSV 업로드
    ↓
1단계: 코드 정확 매칭
    ↓ (실패)
2단계: 상품명+옵션명 매칭
    ↓ (실패)
3단계: 유사도 기반 추천
    ↓
확인 필요 항목 표시
    ↓
3PL 표준 양식 생성
    ↓
다운로드

---

프로젝트 구조

webapp/
├── app.py                    # 메인 Streamlit 애플리케이션
├── requirements.txt          # Python 패키지 의존성
├── ecosystem.config.cjs      # PM2 설정 파일
├── .gitignore               # Git 제외 파일 목록
└── README.md                # 프로젝트 문서

---

기술 세부사항

주요 라이브러리

• Streamlit: 웹 UI 프레임워크
• Pandas: 데이터 처리 및 분석
• OpenPyXL: 최신 XLSX 파일 읽기
• XLRD: 구형 XLS 파일 읽기
• XlsxWriter: 엑셀 파일 생성 및 스타일링
• Chardet: 파일 인코딩 자동 감지
• msoffcrypto-tool: 암호화된 Office 파일 복호화
• difflib: 문자열 유사도 분석

특별 처리 사항

• 3단계 지능형 코드 매칭 알고리즘
• 유사도 기반 자동 추천 (SequenceMatcher)
• 확인 필요 항목 시각적 강조 (노란색 배경)
• CSV 파일의 한글 깨짐 방지
• 암호로 보호된 엑셀 파일 자동 복호화
• 빈 행 자동 제거
• 열 너비 자동 조정

---

배포

PM2를 사용한 로컬 서버 운영

# PM2로 서비스 시작
pm2 start ecosystem.config.cjs

# PM2 상태 확인
pm2 list

# 로그 확인
pm2 logs logistics-app --nostream

# 재시작
fuser -k 3000/tcp 2>/dev/null || true
pm2 restart logistics-app

# 중지
pm2 stop logistics-app

# 삭제
pm2 delete logistics-app

---

트러블슈팅

매칭 정확도 향상 방법

1. 마스터 코드 데이터 정확성 확인

   • 쇼핑몰 상품 코드가 정확한지 확인
   • 상품명과 옵션명이 일관되게 입력되었는지 확인

2. 카페24 데이터 확인

   • 자체품목코드가 올바르게 입력되었는지 확인
   • 상품명과 옵션 정보가 명확한지 확인

3. 확인 필요 항목 처리

   • 다운로드한 파일에서 노란색 항목 확인
   • 수동으로 올바른 코드 입력 후 재업로드

일반 문제 해결

CSV 파일이 깨져서 보이는 경우

• 여러 인코딩을 자동으로 시도하므로 일반적으로 문제없음
• 그래도 안 되면 메모장에서 UTF-8로 저장 후 재시도

암호로 보호된 엑셀 파일 업로드 시

• 엑셀에서 파일 열기 → 다른 이름으로 저장
• 도구 → 일반 옵션 → 암호 제거

웹 사이트 접속 안 됨

• PM2 서비스 상태 확인: pm2 list
• 포트 3000 확인: fuser -k 3000/tcp
• 서비스 재시작: pm2 restart logistics-app

---

완료된 기능

v3.19 (2026-03-22) ✅ 최신 버전

✅ 수동 주문 입력 기능 추가 - 시딩/CS 주문 직접 입력

• 신규 기능:
  • "✏️ 수동 입력" 탭 추가
  • 시딩/CS 카테고리 선택 가능
  • 주문번호 자동 생성:
    • 시딩: {오늘날짜}_Seed_{고유번호} (예: 20260322_Seed_a)
    • CS: {오늘날짜}_CS_{고유번호} (예: 20260322_CS_a)
  • 주문 정보 입력 폼:
    • 주문자명, 전화번호, 주소 (필수)
    • 상품 코드 (마스터 코드에서 자동 불러옴)
    • 수량, 배송 메세지 (선택)
  • 마스터 코드 기반 상품 정보 자동 매칭
  • 실시간 주문 목록 확인 및 일괄 삭제
  • 파일 업로드 주문과 함께 통합 처리
• 기술 구현:
  • st.session_state로 수동 주문 목록 관리
  • 알파벳 고유번호 자동 생성 (a, b, c...)
  • 3PL 32개 표준 컬럼 자동 변환
  • 플랫폼별 통계에 "수동입력" 추가
• 버그 수정:
  • '확인 필요' 컬럼 타입 오류 수정 (문자열 → 불린 카운트)
  • 플랫폼별 통계 집계 오류 수정

v3.19 (2026-03-22)

✅ 수동 입력 UI 대폭 개선 - 다중 주문 입력 지원

• 핵심 변경사항:
  • 상품 코드 selectbox → text input으로 변경
  • 다중 수취인 입력 지원 (줄바꿈으로 구분)
  • 입력한 상품명이 쇼핑몰 상품명/옵션명으로 직접 사용
  • 카테고리를 "Seed"/"CS"로 변경 (기존 "시딩"/"CS")
• 자동 생성 형식:
  • 주문번호: {날짜}_{Seed/CS}_{a,b,c,...}
  • 쇼핑몰 상품 코드: {날짜}_{Seed/CS}_{a,b,c,...}
  • 예시: 20260322_Seed_a, 20260322_CS_b
• 다중 입력 방식:

  수취인 이름:       전화번호:           주소:
  김유림           010-1234-5678     서울시 강남구...
  김종국           010-2345-6789     경기도 성남시...
  이효리           010-3456-7890     부산시 해운대구...
  

• 입력값 검증:
  • 수취인, 전화번호, 주소 개수 일치 확인
  • 빈 줄 자동 제거
  • 오류 시 명확한 메시지 표시
• 테스트 결과:
  • ✅ Seed 주문 3개 생성 (20260322_Seed_a/b/c)
  • ✅ CS 주문 2개 생성 (20260322_CS_a/b)
  • ✅ 주문번호 및 상품코드 고유성 검증 통과
  • ✅ 형식 검증 통과
• 사용성 향상:
  • 마스터 파일 불필요 (수동 입력 시)
  • 한 번에 여러 주문 입력 가능
  • 실시간 주문 목록 확인
  • 3PL 변환에 자동 포함

v3.18 (2026-03-07)

✅ 공개 Google Sheets 연동으로 복귀 - 인증 불필요

• 변경 사항:
  • Service Account 인증 방식 제거 (복잡도 감소)
  • 공개 CSV Export URL 방식으로 복귀
  • 인증 불필요 - 링크 공유만으로 접근 가능
  • 탭 이름에 한글/괄호 포함 → urllib.parse.quote로 URL 인코딩 처리
• sheets_utils.py 복원:
  • CSV Export URL: https://docs.google.com/.../export?format=csv&sheet=상품 코드 최종(마스터 코드)
  • 탭 이름: 상품 코드 최종(마스터 코드) (한글/괄호 자동 인코딩)
  • gspread, google-auth 의존성 제거
  • 간단한 requests.get() 호출로 데이터 로드
• webhook_server.py 간소화:
  • Secret token 검증 제거 (공개 webhook)
  • 단순 POST 엔드포인트로 변경
• Google Apps Script 간소화:
  • google_apps_script.js (Service Account 버전 제거)
  • 공개 Sheets 전용 스크립트로 변경
  • B~F열 변경 감지 (onEdit 트리거)
  • 인증 불필요 - 단순 webhook POST
• 문서 정리:
  • Service Account 관련 문서 모두 제거
  • GOOGLE_SHEETS_SETUP.md - 공개 링크 버전으로 업데이트
  • 설정 시간: 20분 → 5분으로 단축
• 장점:
  • ✅ 설정 간단 (Google Cloud Console 불필요)
  • ✅ 인증 불필요 (링크 공유만 필요)
  • ✅ 코드 간결 (의존성 감소)
  • ✅ 유지보수 용이

v3.17 (2026-03-07)

✅ Google Service Account 인증으로 전환 - 비공개 Sheets 실시간 연동

• 구현 내용:
  • Google Service Account 인증 방식으로 전환 (gspread + google-auth)
  • 비공개 Google Sheets 접근 가능 (Service Account JSON 키)
  • st.secrets로 인증 정보 안전하게 관리
  • B~F열 전체 데이터 읽기 (gid 기반)
  • Webhook Secret Token 검증 추가 (무단 호출 방지)
• sheets_utils.py 업데이트:
  • CSV export 방식 → Service Account 인증 방식
  • gspread로 직접 Sheets API 호출
  • 앱 최초 실행 시 자동으로 Sheets에서 마스터 코드 로드
• webhook_server.py 업데이트:
  • Secret token 검증 로직 추가
  • 인증 실패 시 401 Unauthorized 응답
  • Token 설정 상태를 /health 엔드포인트에 포함
• Google Apps Script 코드 추가:
  • google_apps_script_service_account.js
  • B~F열 변경 감지 (onEdit 트리거)
  • Webhook POST 요청 (secret token 포함)
  • 설정 및 테스트 함수 포함 (setupTrigger, testWebhook, checkConfiguration)
• 설정 가이드 문서 작성:
  • GOOGLE_SERVICE_ACCOUNT_SETUP.md - Service Account 발급 가이드
  • SETUP_GUIDE.md - 전체 설정 단계별 가이드
  • .streamlit/secrets.toml.example - Secrets 템플릿
  • SERVICE_ACCOUNT_SUMMARY.md - 완료 요약 문서
• 보안 강화:
  • .gitignore에 Service Account JSON 파일 추가
  • secrets.toml은 절대 커밋 안 됨
  • 모든 인증 정보는 st.secrets 또는 환경변수로만 관리
• 요구사항 충족:
  • ✅ 비공개 Google Sheets 접근 (Service Account)
  • ✅ 앱 최초 실행 시 Sheets에서 마스터 코드 가져오기
  • ✅ Sheets B~F열 변경 시 즉시 Streamlit 앱에 반영 (webhook)
  • ✅ Polling 방식 사용하지 않음
  • ✅ Secret token으로 webhook 보안
  • ✅ 인증 정보는 코드에 하드코딩 금지

v3.16 (2026-03-07)

✅ 쇼핑몰 묶음 배송 번호 동기화 이슈 완전 해결

• 문제: 쇼핑몰 주문번호에는 접미사(a, b, c...)가 정상 추가되었지만, 쇼핑몰 묶음 배송 번호에는 적용되지 않음
• 원인: 쇼핑몰 묶음 배송 번호를 초기에 원본 주문번호로 설정하고, 접미사 추가 후 업데이트하지 않음
• 해결: 쇼핑몰 묶음 배송 번호를 접미사 추가 후에만 설정하여 항상 쇼핑몰 주문번호와 동일하게 유지
• 검증 결과:
  • ✅ 쇼핑몰 주문번호 == 쇼핑몰 묶음 배송 번호 (100% 일치)
  • ✅ 쇼핑몰 주문번호 고유성 보장 (접미사: a, b, c...)
  • ✅ 조건 1, 2, 3 모두 충족
• 테스트 케이스:

  원본: 20260225-83316T835 (3개 중복)
  결과: 
    - 20260225-83316T835  (첫 번째)
    - 20260225-83316T835a (두 번째, 접미사 a)
    - 20260225-83316T835b (세 번째, 접미사 b)
  묶음 배송 번호: 각각 동일하게 적용됨 ✅
  

v3.15 (2026-03-07)

✅ 네이버(스마트스토어) 파일 처리 완전 지원

• 네이버 파일 skiprows=1 자동 처리 (헤더 행 건너뛰기)
• 네이버 파일 특화 매핑:
  • 주문번호 → 쇼핑몰 주문번호
  • 수취인명 → 수취인 명
  • 구매자명 → 주문자 명 (네이버만 구분)
  • 수취인연락처1 → 수취인 전화번호
  • 통합배송지 → 수취인 기본 주소
  • 배송메세지 → 배송 메세지
• 상품번호로 마스터 데이터 매칭 (100% 성공)
• 암호화된 스마트스토어 파일 자동 복호화
• 테스트 결과: 2건 모두 100% 매칭 성공 ✅

v3.14 (2026-03-07)

✅ 네이버 파일 암호 입력 기능

• 네이버 탭에 파일 암호 입력 필드 추가
• 암호로 보호된 엑셀 파일 자동 복호화
• 복호화 우선순위: ① 사용자 제공 비밀번호 → ② 빈 비밀번호 → ③ VelvetSweatshop 알고리즘
• 암호 오류 시 명확한 에러 메시지 표시
• 사용법: 네이버 탭에서 암호 입력 → 파일 업로드
• 암호화된 네이버 파일 100% 지원 ✅

v3.13 (2026-03-07)

✅ 쇼핑몰 묶음 배송 번호 동기화

• 조건 1: 쇼핑몰 묶음 배송 번호는 쇼핑몰 주문번호와 항상 동일
• 조건 2: 쇼핑몰 주문번호는 고유성 보장 (접미사 자동 추가)
• 조건 3: 둘 다 같은 접미사 적용
• 문제: 주문번호에 접미사가 붙어도 묶음 배송 번호는 원본 유지됨
• 해결: ensure_unique_order_numbers() 실행 후 묶음 배송 번호를 주문번호와 동기화
• 예시: 20260301-0000277 → 20260301-0000277a (둘 다 같은 접미사)
• 100% 동기화 달성 ✅

v3.12 (2026-03-02)

✅ 주문번호 중복 방지 - 자동 접미사 추가

• 동일한 주문번호가 여러 개 있을 경우 자동으로 접미사 추가 (a, b, c...)
• 예시: 20260225-83316T835 → 20260225-83316T835, 20260225-83316T835a, 20260225-83316T835b
• ensure_unique_order_numbers() 함수로 모든 주문번호의 고유성 보장
• convert_to_3pl_format() 함수에서 자동 호출
• 중복 0개, 100% 고유한 주문번호 생성 ✅

v3.11 (2026-03-02)

✅ 앱 매칭 오류 수정 - 황윤정 & 김예은 케이스

• 황윤정: "[Dip] 1개 (딥 페리윙클 1개)" → 딥 플럼이 아닌 딥 페리윙클 정확히 매칭 ✅
• 김예은: "[(앱특가) 아크 극락 번들] 1개 (아이스 1개)" → PL이 아닌 IC 버전 정확히 매칭 ✅
• 4단계 지능형 필터링: 원본 문자열 → 옵션명 → IC/PL 키워드 → 최단 매칭
• IC/PL 키워드 자동 감지: 모든 괄호 내용 분석하여 "아이스" → IC, "플럼" → PL 구분
• 띄어쓰기 보존: "딥 페리윙클" vs "딥 플럼" 정확히 구분 (이전에는 "딥페리윙클"로 합쳐서 매칭 실패)
• 정규식 → 단순 문자열 검색: 괄호 특수문자 문제 해결
• 매칭 성공률 100% 달성 (황윤정 1/1, 김예은 1/1)

v3.7 (2026-02-25)

✅ 앱 파일 특별 처리 추가

• 앱 플랫폼 업로드 시 주문 수량 무조건 1로 고정
• 앱 플랫폼 업로드 시 배송 메세지 무조건 "벨x, 문자"로 고정
• 다른 플랫폼(카페24, 쿠팡, 네이버)은 원본 데이터 유지

v3.6 (2026-02-25)

✅ 앱 파일 매칭 로직 완전 구현

• 파일 인코딩 문제 해결: CP949 디코딩 + 수동 컬럼명 설정
• parse_app_product() 함수 추가: [상품명] N개 (옵션) 형식 파싱
• 패턴 매칭으로 마스터 데이터에서 상품 정보 자동 추출
• 테스트 결과: 4건 모두 100% 매칭 성공 ✅

v3.5 (2026-02-24)

✅ 쇼핑몰 주문 라인번호 중복 방지

• 다중 플랫폼 통합 시 전체 데이터에 1부터 순번 재할당
• int64 타입 유지 (문자열 변환에서 제외)
• 테스트: 98개 행에서 1~98 연속 번호, 중복 0개 확인

v3.4 (2026-02-24)

✅ 쇼핑몰 주문 라인번호 추가: 1부터 시작하는 순차 번호 자동 생성
✅ 요청(희망)배송 일자 추가: 오늘 날짜 YYYY-MM-DD 형식으로 자동 입력

v3.0.3 (2026-02-22)

✅ 플랫폼 이름 매핑 추가

• 영문 플랫폼 이름(cafe24, coupang, naver, app) → 한글(카페24, 쿠팡, 네이버, 앱) 자동 변환
• PLATFORM_NAME_MAP 딕셔너리 추가로 마스터 데이터 필터링 문제 해결

✅ KeyError 완전 해결

• 마스터 데이터 필터링 시 한글 판매처명 사용으로 빈 DataFrame 문제 해결
• ['쇼핑몰 상품 이름'] not in index 오류 완전 제거

✅ Arrow 타입 변환 오류 수정

• 모든 컬럼을 문자열로 변환하여 Streamlit st.dataframe() 호환성 개선
• 우편번호, 수량 등 정수형 컬럼의 Arrow 변환 오류 해결

v3.0.2 (2026-02-22)

✅ 데이터 타입 정규화
✅ Arrow 변환 오류 해결

v3.0.1 (2026-02-22)

✅ 빈 DataFrame 체크 추가
✅ 마스터 데이터 없을 때 매칭 실패 즉시 반환

v3.0 (2026-02-22)

✅ 통합 다중 플랫폼 지원 - 단일 페이지에서 카페24, 앱, 쿠팡, 네이버 모든 파일 동시 처리
✅ 자동 플랫폼 감지 - 컬럼명 기반 지능형 플랫폼 분류
✅ 플랫폼별 매칭 로직 - 각 플랫폼의 특성에 맞는 코드 추출 및 매칭
✅ 10개 컬럼 출력 - 플랫폼, 주문번호, 수취인명, 핸드폰, 주소, 상품코드, 상품명, 옵션, 수량, 배송메시지, 매칭방법, 확인필요
✅ 플랫폼별 통계 - 각 플랫폼의 매칭 결과 및 확인 필요 항목 통계

v2.2 (2026-02-22)

✅ 3PL 출력 양식 완전 수정
✅ 쇼핑몰 상품 코드, 상품 이름, 옵션 이름 모두 마스터 파일에서 추출
✅ 표준 9개 컬럼 출력
✅ 100% 매칭 성공 (49/49건)

v2.1 (2026-02-22)

✅ 매칭 로직 수정: 카페24 자체품목코드 → 마스터 판매 상품 코드 매칭
✅ 100% 매칭률 달성

v2.0 (2026-01-31)

✅ 3PL 배송 양식 자동 변환 시스템
✅ 물류_코드명 마스터 데이터 로드
✅ 3단계 지능형 코드 매칭 알고리즘
✅ 유사도 기반 자동 추천 (50% 이상)
✅ 확인 필요 항목 시각적 강조
✅ 매칭 결과 분석 및 통계

v1.1 (2026-01-31)

✅ 다중 파일 업로드 기능
✅ 8가지 표준 컬럼 자동 매핑
✅ 한글 인코딩 자동 감지 (UTF-8, CP949, EUC-KR)
✅ 암호화된 엑셀 파일 자동 복호화 시도
✅ 구형 XLS 형식 지원
✅ 최신 XLSX 형식 지원
✅ 실시간 데이터 미리보기
✅ 웹 인터페이스 구축

---

업데이트 내역

v3.15 (2026-03-07) - 네이버(스마트스토어) 파일 처리 완전 지원 🟢

• 🎉 네이버 파일 자동 감지 및 처리
  • 파일명에 '스마트스토어' 포함 시 자동으로 skiprows=1 적용
  • 헤더 행(설명문) 자동 건너뛰기
  • 72개 컬럼 중 필요한 컬럼만 자동 추출
• 🔍 네이버 특화 컬럼 매핑
  • 수취인명: '수취인명' 컬럼 (다른 플랫폼과 별도)
  • 구매자명: '구매자명' 컬럼 → 주문자 명 (네이버만 구분)
  • 수취인 전화: '수취인연락처1' 컬럼
  • 수취인 주소: '통합배송지' 컬럼
  • 배송메세지: '배송메세지' 컬럼
• 📊 상품번호 매칭
  • 상품번호 (11자리 숫자) → 마스터 판매 상품 코드
  • 타입 자동 변환 (int → str) 으로 100% 매칭
• 🔐 암호화 파일 지원
  • 사용자가 입력한 비밀번호로 자동 복호화
  • 복호화 성공 시 skiprows=1 자동 적용
• 📊 테스트 결과
  • 2건 네이버 주문 모두 100% 매칭 성공
  • 상품번호 11574588816 → N-AR-GRK-10 / GRS, LFT4W

v3.14 (2026-03-07) - 네이버 파일 암호 입력 기능 🔐

• 🔒 암호화된 네이버 파일 지원
  • 네이버 탭에 파일 암호 입력 필드 추가
  • st.text_input(type="password") 사용으로 보안 강화
  • 암호 입력 후 파일 업로드 시 자동으로 복호화
• 🔧 read_file() 함수 개선
  • password 파라미터 추가: read_file(uploaded_file, password=None)
  • 네이버 파일 읽기 시 세션 스테이트에서 비밀번호 자동 전달
• 🔐 복호화 우선순위 최적화
  1. 사용자 제공 비밀번호 (우선 시도) ✅
  2. 빈 비밀번호 ('') (빈 암호 파일)
  3. VelvetSweatshop 알고리즘 (기본 암호)
• 💬 명확한 피드백
  • 암호 설정 시: "🔐 파일 암호가 설정되었습니다"
  • 복호화 성공: "🔓 제공된 암호로 파일 복호화 성공"
  • 복호화 실패: "복호화 실패: 올바른 비밀번호를 입력해주세요"
• 📊 사용 방법
  1. 네이버 탭에서 파일 암호 입력 (암호가 있는 경우)
  2. 네이버 파일 업로드
  3. 자동으로 복호화 및 처리

v3.13 (2026-03-07) - 쇼핑몰 묶음 배송 번호 동기화 🔗

• 🐛 묶음 배송 번호 불일치 해결
  • 문제: 주문번호에 접미사(a, b, c...)가 붙어도 묶음 배송 번호는 원본 유지
  • 원인: 쇼핑몰 묶음 배송 번호는 원본 result_df['주문번호']를 사용, ensure_unique_order_numbers() 실행 후 업데이트 안 됨
  • 해결: 함수 실행 후 output_df['쇼핑몰 묶음 배송 번호'] = output_df['쇼핑몰 주문번호']로 동기화
• 🔧 3가지 조건 완벽 준수
  1. 쇼핑몰 묶음 배송 번호는 쇼핑몰 주문번호와 항상 같음 ✅
  2. 쇼핑몰 주문번호는 고유성 보장 (접미사 자동 추가) ✅
  3. 둘 다 같은 접미사 적용 (예: 20260301-0000277a) ✅
• 📊 테스트 결과
  • 원본 2건 중복: 20260301-0000277, 20260227-0000288
  • 변환 후: 20260301-0000277a, 20260227-0000288a (묶음 배송 번호도 동일)
  • 192건 중 190건 일치, 2건 동기화 완료 → 100% 일치 ✅

v3.12 (2026-03-02) - 주문번호 중복 방지 기능 추가 🔢

• ✨ 주문번호 고유성 보장
  • ensure_unique_order_numbers() 함수 추가
  • 동일 주문번호가 여러 개 있을 경우 두 번째부터 a, b, c... 접미사 자동 추가
  • 알파벳 소문자 26개 지원 (최대 27개 중복까지 처리 가능)
• 🔧 자동 적용
  • convert_to_3pl_format() 함수에서 자동 호출
  • 플랫폼 통합 후 최종 DataFrame에 적용
  • 사용자 개입 없이 자동으로 중복 제거
• 📊 적용 예시

  원본:
  - 20260225-83316T835
  - 20260225-83316T835
  - 20260225-83316T835
  
  변환 후:
  - 20260225-83316T835
  - 20260225-83316T835a
  - 20260225-83316T835b
  

• 📊 테스트 결과: 6건 중복 → 0건 중복, 100% 고유 주문번호 생성 ✅

v3.11 (2026-03-02) - 앱 매칭 오류 수정 (황윤정 & 김예은) 🔧✨

• 🐛 황윤정 딥 페리윙클 매칭 실패 해결
  • 문제: "[Dip] 1개 (딥 페리윙클 1개)" → 딥 플럼으로 잘못 매칭
  • 원인: 옵션명에서 띄어쓰기 제거하여 "딥페리윙클"로 변환 → 마스터 "딥 페리윙클 1개"와 불일치
  • 해결: 띄어쓰기 보존, 원본 문자열 우선 매칭
• 🐛 김예은 아크 극락 IC/PL 구분 실패 해결
  • 문제: "[(앱특가) 아크 극락 번들] 1개 (아이스 1개)" → PL 버전으로 잘못 매칭
  • 원인: 첫 번째 괄호 "(앱특가)"만 추출 → IC/PL 구분 불가
  • 해결: 모든 괄호 내용 분석, IC/PL 키워드 자동 감지
• ✨ parse_app_product 개선
  • 모든 괄호 내용 추출 및 IC/PL 키워드 검색
  • 옵션_원본 필드 추가 (띄어쓰기 포함)
  • IC/PL_키워드 필드 추가 (IC, PL, PW 등)
• 🔍 4단계 지능형 필터링
  1. 원본 문자열 정확 매칭 (예: "딥 페리윙클 1개")
  2. 옵션명 (띄어쓰기 포함) 매칭
  3. IC/PL 키워드로 버전 구분
  4. 최단 문자열 선택 (가장 정확한 매칭)
• 🔧 정규식 → 단순 문자열 검색
  • 괄호 () 특수문자 문제 해결
  • regex=True → regex=False 변경
• 📊 테스트 결과: 황윤정 & 김예은 100% 정확 매칭 성공 ✅

v3.7 (2026-02-25) - 앱 파일 특별 처리 추가 ⚙️

• ✨ 앱 전용 고정값 설정
  • 주문 수량: 항상 1로 고정 (다른 플랫폼은 원본 데이터 사용)
  • 배송 메세지: 항상 "벨x, 문자"로 고정 (다른 플랫폼은 원본 데이터 사용)
• 🔧 조건부 로직 추가
  • if platform == 'app': 조건으로 앱 파일만 특별 처리
  • 카페24, 쿠팡, 네이버는 기존 로직 유지
• 📊 테스트 완료: 앱 파일 4건 모두 고정값 적용 확인

v3.6 (2026-02-25) - 앱 파일 매칭 로직 완전 구현 🎉

• 🔧 인코딩 문제 해결
  • CP949 디코딩으로 파일 읽기 성공
  • 수동 컬럼명 설정으로 깨진 헤더 문제 해결
• ✨ 주문상품 파싱 함수 추가
  • parse_app_product(): [상품명] N개 (옵션) 형식에서 상품명, 수량, 옵션 추출
  • 예시: [Zee] 1개 (페리윙클 PERIWINKLE 1개) → 상품명: Zee, 수량: 1, 옵션: 페리윙클 PERIWINKLE 1개
• 🔍 패턴 매칭 구현
  • 정규표현식으로 마스터 데이터의 판매 상품 코드에서 [상품명] 패턴 검색
  • 100% 매칭 성공률 달성 (4/4건)
• 📊 테스트 결과
  • 4건의 앱 주문 모두 성공적으로 매칭
  • 쇼핑몰 상품 코드, 상품 이름, 옵션 이름 정확히 추출

v3.5 (2026-02-24) - 쇼핑몰 주문 라인번호 중복 방지 🔢

• 🔧 통합 시 순번 재할당
  • 다중 플랫폼 통합 후 merged_df['쇼핑몰 주문 라인번호'] = list(range(1, len(merged_df)+1))
  • 각 플랫폼의 1N 번호가 통합 후 1전체행수로 재할당
• 🔢 int64 타입 유지
  • 문자열 변환 시 쇼핑몰 주문 라인번호 제외
  • if col != '쇼핑몰 주문 라인번호': 조건 추가
• 📊 테스트 결과
  • 49건 + 49건 = 98건 통합 시 1~98 연속 번호
  • 중복 0개, 순차 증가 확인

v3.4 (2026-02-24) - 32개 표준 컬럼 완성 📋

• ✨ 쇼핑몰 주문 라인번호 추가 (20번 컬럼)
  • 1부터 시작하는 순차 번호 자동 생성
  • 데이터 타입: int64
  • 구현: output_df['쇼핑몰 주문 라인번호'] = list(range(1, n_rows + 1))
• ✨ 요청(희망)배송 일자 추가 (23번 컬럼)
  • 오늘 날짜 YYYY-MM-DD 형식 자동 입력
  • 데이터 타입: object (날짜 문자열)
  • 구현: output_df['요청(희망)배송 일자'] = [today] * n_rows (today = datetime.now().strftime('%Y-%m-%d'))
• 📊 총 34개 컬럼 출력: 32개 표준 + 2개 디버깅

v3.0.3 (2026-02-22) - 플랫폼 매핑 및 타입 오류 수정 🐛

• 🔧 플랫폼 이름 매핑 추가
  • PLATFORM_NAME_MAP 딕셔너리 추가: {'cafe24': '카페24', 'app': '앱', 'coupang': '쿠팡', 'naver': '네이버'}
  • 마스터 데이터 필터링 시 영문 → 한글 자동 변환
• ✅ KeyError 완전 해결
  • platform_master = master_df[master_df['판매처'] == PLATFORM_NAME_MAP.get(platform)]
  • 빈 DataFrame 문제 완전 제거
• ✅ Arrow 타입 변환 오류 수정
  • 모든 컬럼을 문자열로 변환: merged_df[col].astype(str)
  • 'nan', 'None', '' → 빈 문자열 정리
• 📊 테스트 결과: 카페24 49건, 쿠팡 26건 모두 100% 매칭 성공

v3.0.2 (2026-02-22) - Arrow 변환 오류 수정

• 🔧 데이터 타입 정규화
  • 우편번호, 수량 등 정수형 컬럼을 문자열로 변환
  • Streamlit Arrow 테이블 변환 호환성 개선

v3.0.1 (2026-02-22) - 빈 DataFrame 체크 추가

• 🔧 마스터 데이터 검증 강화
  • if platform_master.empty: 체크 추가
  • 마스터 데이터 없을 때 즉시 매칭 실패 반환

v3.0 (2026-02-22) - 통합 다중 플랫폼 지원 🎉

• 🎉 단일 페이지 통합 UI
  • 모든 플랫폼 파일을 동시에 업로드하고 처리
  • 모드 토글 제거, 단순화된 워크플로우
• 🧠 자동 플랫폼 감지
  • 컬럼명 기반 지능형 플랫폼 분류
  • detect_platform() 함수로 자동 판별
• 📊 플랫폼별 매칭 로직
  • 카페24: 자체품목코드 매칭
  • 쿠팡: 옵션ID 매칭
  • 앱: 주문상품 파싱 후 매칭
  • 네이버: 상품번호 매칭
• 📈 플랫폼별 통계 및 분석
  • 파일 정보 테이블
  • 플랫폼별 주문 수 및 확인 필요 항목
  • 매칭 방법별 통계
• 🎨 개선된 UI/UX
  • 업로드된 파일 자동 분류 표시
  • 플랫폼별 카드 형태 정보 표시
  • 실시간 통계 메트릭

v1.1 (2026-01-31)

• ✨ 암호화된 엑셀 파일 지원 추가
• ✨ 구형 XLS 파일 형식 지원
• 🔧 오류 처리 개선

v1.0 (2026-01-31)

• 🎉 초기 버전 릴리스
• 다중 파일 업로드 기능
• 자동 컬럼 매핑
• 웹 인터페이스 구축

---

추천 다음 단계

1. 다중 플랫폼 지원: 쿠팡, 네이버 스마트스토어 등 추가 ✅ v3.0 완료
2. 앱 마스터 데이터 추가: 물류_코드명.xlsx에 앱 상품 데이터 추가
3. 커스텀 매핑 규칙: 웹에서 직접 매핑 규칙 수정
4. AI 기반 매칭: GPT 모델을 활용한 고도화된 매칭
5. 배치 처리: 대용량 파일 처리 최적화
6. API 연동: 3PL 시스템과 직접 연동

---

라이선스

MIT License

개발자

Arooo Operator 김유림

---

🎯 v3.0 핵심 가치: 모든 쇼핑몰 플랫폼(카페24, 앱, 쿠팡, 네이버)의 주문 데이터를 물류_코드명 마스터 데이터와 지능적으로 매칭하여 통합 3PL 배송 양식으로 자동 변환, 물류 업무 효율성을 극대화합니다!