구매대행 크롬 확장 프로그램 개념 잡기

시리즈 목차 (3편 연재)
1/3. 구매대행 크롬 확장 프로그램 개념 잡기 (현재 글)
2/3. 구매대행 크롬 확장 — Svelte 5·MV3 사이드패널 만들기
3/3. 구매대행 크롬 확장 — 1688 주문·상품 수집과 엑셀 자동화

이 시리즈는 1688 구매대행 업무를 위한 크롬 확장(ventiChromeExt)을 예제로, 주문·상품 데이터를 모아 배송대행(타배)용 엑셀까지 만드는 과정을 정리합니다. 기술 스택은 Svelte 5 + Manifest V3 사이드패널입니다. 개인적으로 쓰려고 만든 확장 프로그램인데, 같은 고민을 하는 분께 조금이나마 도움이 되면 좋겠습니다.

1편에서는 코드를 깊게 파기보다 **「구매대행 확장이 무엇을 어디서 하는지」**를 먼저 잡습니다.

---

1. 먼저 결과물부터 보기

확장을 켜면 브라우저 오른쪽에 사이드패널이 붙습니다. 지금 보고 있는 페이지가 1688 구매내역이면 주문 추출·엑셀 버튼이 활성화되고, 그렇지 않으면 “대상 페이지가 아님”에 가깝게 도구가 비활성(또는 안내) 상태가 됩니다.

1688 구매정보 페이지에 접속했을 때

구매정보 페이지가 아닐 때

추출·정규화가 끝나면 이런 형태의 배송대행사이트용 엑셀이 만들어집니다.

흐름을 한 줄로 말하면 다음과 같습니다.

1688 페이지(DOM) → Content Script(추출) → Side Panel(상태·필터) → Excel / API
                      ↑ Background(탭·다운로드 등 권한 대행)

---

2. 왜 Chrome 확장인가?

웹 자동화에는 서버 크롤러, Playwright 같은 헤드리스 브라우저도 있습니다. 그런데 로그인한 사용자의 세션, 지금 보고 있는 탭, Shadow DOM이 붙은 실페이지를 그대로 쓰려면 브라우저 안쪽이 유리합니다.

확장 프로그램이 특히 잘 맞는 지점:

• 반복 작업 자동화: 주문 목록을 눈으로 훑고 엑셀에 옮기던 일을 버튼 몇 번으로 줄인다.
• 비정형 → 정형: HTML·Shadow DOM 텍스트를 HS CODE·통관번호가 채워진 엑셀 행으로 바꾼다.
• 업무 UI 통합: 사이드패널에 도구를 두면 탭을 바꿔도 패널이 유지된다(팝업보다 업무에 유리).

Chrome은 현재 Manifest V3(MV3) 를 표준으로 씁니다. 예전처럼 백그라운드 페이지를 상시 켜 두지 않고, 필요할 때만 깨어나는 Service Worker를 쓰도록 강제합니다. 2편에서 빌드·권한·CSP를 다루고, 여기서는 “왜 세 조각으로 나누는지”만 기억하면 됩니다.

---

3. 확장의 세 기둥 (Side Panel · Content Script · Background)

크롬 확장은 서로 다른 실행 환경(Context) 이 메시지를 주고받으며 동작합니다. 한 파일에 다 넣으면 권한·보안·생명주기에서 바로 막힙니다.

Side Panel — 관제탑

사용자가 누르는 버튼, 날짜 필터, 로그인, 환경설정 편집이 여기 있습니다. 예제에서는 Svelte 5($state)로 활성 탭 URL을 보고, 구매 목록이면 PurchaseTools, 상품 상세면 ProductTools를 보여 줍니다.

Content Script — 추출

실제 1688 페이지 안으로 주입되어 <order-item> 같은 노드를 읽고, 정규식으로 필드를 자릅니다. 페이지 DOM에 손이 닿는 유일한 계층입니다.

Background — 권한 대행

Content Script는 웹페이지 밖의 세상(파일 다운로드, 숨은 탭 열기 등)에 손이 짧습니다. 운송장 번호가 목록에 없으면 Background가 비활성 탭으로 상세 페이지를 열어 运单号码를 보완하는 식의 일을 맡습니다.

한 줄 요약: Panel이 명령을 내리고, Content가 데이터를 긁고, Background가 권한 작업을 대리한다.

---

4. 메시지 통신 — 격리된 세계가 대화하는 법

세 계층은 메모리를 공유하지 않습니다. 그래서 chrome.tabs.sendMessage / chrome.runtime.onMessage 같은 메시지로만 이야기합니다.

전형적인 한 사이클:

1. Side Panel이 활성 탭에 PARSE_1688_PURCHASES 같은 명령을 보낸다.
2. Content Script가 DOM을 순회해 행 배열을 만든다.
3. 결과를 Panel에 돌려주고, Panel이 엑셀 다운로드를 트리거한다.

실무에서 자주 막히는 지점 하나: 확장을 방금 설치·업데이트했는데 예전에 열어 둔 탭에는 Content Script가 아직 없을 수 있습니다. 이때 Receiving end does not exist가 납니다. 시니어 패턴은 실패를 감지하면 chrome.scripting.executeScript로 재주입 후 재시도하는 것입니다. 구현은 2편에서 다룹니다.

---

5. 최신 웹에서 스크래핑이 어려워진 이유

예전처럼 “HTML 소스에서 태그 찾기”만으로는 1688 같은 사이트에서 거의 실패합니다.

Shadow DOM

<order-item> 안 데이터는 메인 DOM과 분리된 shadowRoot에 있습니다. 그래서 queryAllDeep처럼 TreeWalker + 재귀 visit(shadowRoot) 로 깊게 들어가야 합니다. 상세 코드와 예시는 3편에 있습니다.

접힌 주문 (데이터 무결성의 왕초보 함정)

주문이 많으면 1688은 상품 행을 접어 둡니다. 접힌 상태에서는 상세 라인(색상·수량 등)이 DOM에 없거나 불완전해서, 아무리 Shadow DOM을 잘 순회해도 빈 엑셀이 나옵니다.

사이드패널의 Active 버턴확인 → Active 버턴실행으로 「주문정보 모두 보이기」를 먼저 처리하는 것이 추출의 필수 선행 작업입니다. (위 구매정보 화면의 Active 버튼 영역을 참고하세요.)

Lazy Loading

이미지는 스크롤해야 src / data-src 등이 채워지는 경우가 많습니다. 관심상품·상세 이미지 수집은 3편에서 scrollToLoadImages 패턴과 함께 설명합니다.

---

6. 데이터가 엑셀이 되기까지 (큰 그림)

개념만 잡아 두면 2·3편이 한결 읽기 쉽습니다.

1. 펼치기: Active 버튼으로 DOM을 완전히 연다.
2. 추출: Content Script가 Shadow DOM·정규식으로 주문/상품 필드를 모은다.
3. 보완: 트래킹이 비면 Background가 상세 탭에서 운송장을 채운다.
4. 정규화: ventigoods.agency / ENV_VENTI_PRODUCT_INFO로 HS CODE·통관번호·브랜드 등을 상품명에 매핑한다.
5. 출력: ExcelJS로 타배용 엑셀을 받거나, 관심상품은 API로 저장한다.

국내 쇼핑몰 주문번호 칼럼은 엑셀에 자리를 만들어 두되, 확장이 쇼핑몰 엑셀을 자동으로 읽어 합치지는 않습니다.(1688에는 국내 쇼핑몰 정보가 없음) 1688 → 타배 엑셀 자동화가 핵심이고, 국내 주문번호는 업무에서 맞춰 넣는 경우가 많습니다.(순서가 맞아 있다면 주문량이 많지 않은 경우 엑셀에서 칼럼을 선택하여 복사하면 몇번의 복사 붙여넣기로 해결됩니다.)

---

7. 이 시리즈를 읽는 순서

1. 1편(현재): 구매대행 확장의 세 기둥·메시지·Shadow DOM·접힌 주문 — 지도 읽기
2. 2편 구매대행 크롬 확장 — Svelte 5·MV3 사이드패널 만들기: 빌드·통신·골격
3. 3편 구매대행 크롬 확장 — 1688 주문·상품 수집과 엑셀 자동화: 스크래핑·엑셀·API

로컬에서 확장을 미리 붙여 보고 싶다면:

1. 프로젝트에서 npm run build → build/ 생성
2. chrome://extensions → 개발자 모드
3. 압축 해제된 확장 프로그램 로드 → build/ 선택
4. 확장 아이콘으로 사이드패널을 연 뒤, 1688 구매자 주문 목록으로 이동

세부 설정과 코드는 2편부터 이어집니다.
위 개념을 잘 파악하고 있다면 AI의 도움을 받아 코드를 쉽게 작성하고 테스트 해 볼 수 있습니다. 다만 본인이 모르면 아무리 AI가 있어도 무용지물입니다.

---

해시태그