구매대행에 붙이는 관리자 페이지 — 환경설정·통관검증·엑셀 병합 (4/4)

시리즈 목차 (4편 연재)
1/4. 구매대행 크롬 확장 — 프로그램 개념 잡기
2/4. 구매대행 크롬 확장 — Svelte 5·MV3 사이드패널 만들기
3/4. 구매대행 크롬 확장 — 1688 주문·상품 수집과 엑셀 자동화
4/4. 구매대행에 붙이는 관리자 페이지 — 환경설정·통관검증·엑셀 병합 (현재 글)

1~3편에서는 크롬 확장으로 1688 주문을 긁어 배송대행(타배)용 엑셀 골격을 만드는 쪽을 다뤘습니다.
그런데 구매대행 실무는 확장만으로 끝나지 않습니다. 국내 쇼핑몰(예: 쿠팡) 주문, 개인통관번호 검증, 상품별 HS·통관 매핑, 타배 업로드용 통합 엑셀까지 이어져야 합니다.

이 글은 그 “나머지 절반” — 개인·회사 홈페이지의 관리자 메뉴에 넣어 두면 좋은 기능 — 을 example.com 같은 사이트 기준으로 정리한 4편(부록) 입니다. 업무 파이프라인과 화면 역할에 초점을 두고, 시리즈에서 쓰는 확장 골격 chromeExtExample.zip 도 이 글에 첨부합니다.

개인적으로 쓰려고 만든 관리 도구인데, 같은 흐름을 홈페이지에 붙이려는 분께 참고가 되면 좋겠습니다.

예제 코드 첨부: 1~3편에서 인용한 확장 골격은 chromeExtExample.zip 입니다. (로그인·API·관심상품 제외)
구성·빌드 설명은 2편, 주문→엑셀은 3편을 참고하세요.

chromeExtExample/
├── package.json / svelte.config.js / README.md
├── samples/ventigoods.agency.sample.txt
├── scripts/fix-extension-csp.mjs
├── static/manifest.json · background.js · content.js(축약)
└── src/routes/+page.svelte

---

1. 왜 확장만으로는 부족한가

확장(3편)이 잘해 주는 일:

• 1688 주문 목록 → Shadow DOM 추출 → HS/통관/브랜드가 채워진 1688측 엑셀 다운로드

아직 비어 있는 일:

• 쿠팡(국내몰) 수취인·주소·PCCC·결제액을 같은 행에 붙이기
• 잘못된 개인통관번호를 타배 업로드 전에 걸러 내기
• 상품명별 매핑 JSON(ENV_VENTI_PRODUCT_INFO)을 브라우저/서버에서 편집·배포하기

그래서 관리자 쪽에 대략 이런 메뉴가 필요합니다. (예시 사이드바 라벨)

전체 파이프라인을 한 줄로 쓰면:

ENV 편집(관리자)
  → 1688 추출(크롬 확장 / 사이트 regExp) + 쿠팡 주문 엑셀
  → (선택) PCC 일괄 검증
  → 쿠팡+1688 병합
  → 타배(Tabae) 업로드 엑셀

---

2. 환경설정(구매대행 상품) — /admin/purchaseAgency

2.1. 하는 일

1688에서 뽑힌 중국어 상품명을 타배 양식에 맞게 바꿉니다.

• HS CODE, 통관품목번호
• 브랜드, 배송지(영문 등) 상품명
• 색상 한글 표기, 색상/SKU별 이미지 URL
• 부가서비스 코드

이 맵이 바로 3편·샘플의 ENV_VENTI_PRODUCT_INFO 입니다.
# Text 형식 샘플은 2편 zip의 chromeExtExample/samples/ventigoods.agency.sample.txt 를 보면 됩니다.

관리자 화면에서는 원문·섹션별로 편집할 수 있습니다.

2.2. 사용 흐름

1. 관리자 → 환경설정(구매대행 상품)
2. ENV_VENTI_PRODUCT_INFO JSON(또는 섹션 UI) 편집
3. 서버 저장(DB t_env)과 로컬스토리지 저장을 구분해서 이해

확장·파서는 보통 탭의 localStorage를 먼저 봅니다.
API에만 저장하고 로컬에 안 넣으면, 확장 쪽 매핑이 비는 경우가 있습니다. 로컬스토리지 저장이 실무 브릿지입니다. (# Encoded면 암호화본)

2.3. 홈페이지에 넣을 때 체크리스트

• ENV 키 하나(ventigoods.agency)로 # Text / # Encoded 텍스트 관리
• JSON 맵 키가 1688 추출 상품명과 문자열 일치해야 함
• 편집 UI는 단순 텍스트에어리어여도 되고, 섹션별 폼이어도 됨 (EnvManager 패턴)

---

3. 쿠팡주문 엑셀로 통관번호 검증 — /excelViewer?work=pccCheck

3.1. 하는 일

쿠팡에서보낸 주문 엑셀에서 이름 · 개인통관번호(PCCC) · 통관용 전화를 모아 일괄 검증합니다.
타배에 올리기 전에 통관 실패 후보를 화면에서 걸러 냅니다.

• 실패한 주문건에 대해서는 고객에게 확인하여 정보를 바로잡아 입력해야 합니다.
• 살제 쿠팡주문자와 제품수신자가 다른경우에 발생하는 경우가 많습니다. (대부분 주문자의 통관번호가 입력되는 경우가 많음)
• 개인통관고유부호는 상품 주문자가 아니라 상품 수신자(받는 사람)의 것을 기재해야 합니다.

3.2. 사용 흐름

1. 쿠팡 주문 엑셀 업로드
2. 검증할 행 선택 → 선택항목 통관번호 일괄검증
3. 정상/오류 요약 + 오류 건 상세를 UI에 표시

필수 컬럼 예:

백엔드에서는 예를 들어 check.pccc 같은 커맨드로 외부 검증(GSI Express 등)을 호출하는 식입니다.
결과 엑셀 다운로드가 필수는 아니고, 오류 목록을 보고 쿠팡/고객 데이터를 고친 뒤 병합 단계로 가면 됩니다. (고객 확인후 수정 필수)

3.3. 홈페이지에 넣을 때 체크리스트

• 엑셀 뷰어 + work=pccCheck 옵션 객체로 컬럼·버튼 분리
• 일괄 API는 레이트 리밋·타임아웃을 가정하고 UI에 진행/실패를 분명히
• 개인정보(이름·전화·PCCC)이므로 관리자 권한·로그 정책을 함께 설계

---

4. [쿠팡 + 1688 ⇒ 타배] 엑셀 병합 — /excelMerge?work=cupang_1688

4.1. 하는 일

• A: 쿠팡 주문 엑셀 — 수취인, 주소, PCCC, 주문번호, 결제액 …
• B: 1688 구매내역 엑셀 — 상품·HS·트래킹·통관품목 … (확장/3편 산출물)

둘을 조인해 타배 신청 시트 한 장으로 만듭니다. (예: 배송대행_신청.xlsx / sheet 신청)

4.2. 조인 키

업무적으로는 쿠팡 주문번호를 1688 엑셀의 국내몰 주문번호 칸에 맞춰 두는 것이 전제입니다.
(확장은 국내 주문번호를 자동으로 채우지 않는 경우가 많아, 수동·반자동으로 맞추는 단계가 남아 있습니다 — 1편에서도 언급.)

4.3. 결과 열은 누가 채우나

대략적인 역할 분담:

구현은 mergeConfig.outputColumns에 keyOwner: 'A'|'B' 와 고정 value를 나열하는 방식이 읽기 쉽습니다.

4.4. 사용 흐름

1. 좌: 쿠팡 엑셀 / 우: 1688 엑셀 업로드
2. 병합 → 미리보기
3. 다운로드 후 타배 사이트에 업로드

4.5. 홈페이지에 넣을 때 체크리스트

• 두 파일 업로더 + 조인 키 설정 + 출력 컬럼 매핑을 work 옵션으로 분리 (cupang_1688 등)
• 헤더명이 쿠팡/1688 내보내기 형식과 어긋나면 조인이 깨지므로, 샘플 엑셀을 문서에 고정
• 매칭 실패 행(한쪽만 있음)을 미리보기에 표시하면 운영이 편함

---

5. 확장(1~3편)과 관리자(4편)를 잇는 그림

┌────────────────────┐     ┌─────────────────────────────┐
│ 관리자 홈페이지     │     │ 크롬 확장 (1~3편)            │
│ purchaseAgency     │────▶│ localStorage ventigoods…    │
│  (ENV 편집)         │     │ 1688 → 타배용 1688 엑셀      │
└────────────────────┘     └──────────────┬──────────────┘
                                           │
┌────────────────────┐                     │
│ excelViewer        │  쿠팡 주문 엑셀       │
│  pccCheck          │◀─── 검증 ────────────┤
└─────────┬──────────┘                     │
          │                                │
          ▼                                ▼
┌────────────────────────────────────────────────────────┐
│ excelMerge?work=cupang_1688                             │
│  쿠팡 엑셀 + 1688 엑셀 → 타배 업로드 엑셀                │
└────────────────────────────────────────────────────────┘

정리: 확장은 “1688 페이지 위의 손”이고, 관리자 페이지는 “ENV·검증·병합 책상”입니다. 둘 다 있어야 쿠팡 구매대행 → 타배 업로드까지 한 사이클로 돌아갑니다.

---

6. 직접 붙일 때 최소 구성

개인/회사 사이트에 비슷하게 넣을 때 최소 세트:

1. ENV 관리자 페이지 — # Text 저장 + localStorage 브릿지
2. 엑셀 뷰어 + PCC work — 쿠팡 3컬럼 검증
3. 엑셀 병합 + cupang_1688 work — 조인 키·출력 컬럼 테이블

example.com 류 구현 참고 경로(개념용):

• /admin/purchaseAgency
• /excelViewer + pccCheck work 옵션
• /excelMerge + cupang_1688 work 옵션

이 글의 관리자 쪽은 “무엇을 왜 만드는지” 설계 노트에 가깝고, 공개용 확장 골격은 위 chromeExtExample.zip 을 첨부합니다. 관리자 완전체 소스는 별도로 첨부하지 않습니다.

---

7. 시리즈 다시 보기

👉 1편: 구매대행 크롬 확장 프로그램 개념 잡기
👉 2편: 구매대행 크롬 확장 — Svelte 5·MV3 사이드패널 만들기
👉 3편: 구매대행 크롬 확장 — 1688 주문·상품 수집과 엑셀 자동화

확장이 만든 1688 엑셀은 병합의 B 입력이 됩니다. 확장 골격 zip은 이 글 첨부를 확인하세요.