Shopee 2.0 매뉴얼

🚀 시작하기 01

Shopee 2.0은 8개국 셀러 운영 통합 시스템입니다. SG / TH / MY / VN / PH / TW / BR / MX 마켓을 단일 대시보드에서 관리합니다.

로그인

• /2.0/login 에 접속
• 이름 + 코드 입력 → POST /verify → 토큰 발급
• 토큰은 localStorage.shopee_2_token 저장 (30일 자동 유지)
• 로그인 성공 시 /2.0/dashboard 즉시 이동 (returnTo URL 우선)

네비게이션

• Sidebar: 좌측 72px → hover 240px overlap. 9 페이지 + 하단 Settings/Manual
• Mobile: 하단 tabbar 5 페이지 (Dashboard/Schedule/Orders/Chat/Publish) — Promo/Calc/Files/Office/Settings/Manual은 sidebar에서 접근
• 모든 페이지 진입 시 토큰 자동 검증. 401 응답 시 자동 /2.0/login redirect

📊 Dashboard 02

9 KPI 카드 + 매출/수익 차트 + 8국 마켓 헬스 + Top SKU.

KPI 9 카드 (행 1: 4개 / 행 2: 5개)

• 행 1 — 총 매출 / 정산 금액 / 순 수익 / 전월 대비
• 행 2 — Ship Order 성공률 / Global SKU / New Arrival / 미확인 채팅 / 현재 주문
• KPI 카드 클릭 → 국가별 breakdown 모달

매출/수익 차트

• 기간: 오늘 / 이번 주 / 이번 달 / 지난 달 / 직전 3개월
• 매출 (orange) + 수익 (green) 일별 grouped bar
• KRW / USD 토글

엔드포인트

• POST /dashboard/revenue-chart — 차트 데이터
• GET /dashboard/shop-stats — 8국 헬스
• GET /admin/internal-ship-order-stats — Ship rate 7일
• GET /dashboard/penalty-stats / /promo-stats / /shipping-stats

📅 Schedule 03

캘린더 + DTS 마감 + 주문 흐름 + 계획·기념일 + 월마감.

캘린더

• 7×6 셀, 한국 공휴일 + 음력 (lunar-javascript)
• 일별 마커: 🚨 DTS 마감 (today=red, D-1=orange, D-2=yellow) / 🛍 신규 주문 (mint) / 📝 계획 (violet) / 🎉 기념일
• 날짜 클릭 → 하단 상세 (DTS / 신규 주문 / 계획·기념일)

월마감

• "월마감" 버튼 → 7 컬럼 (date / orders / revenue / profit / margin / ship rate / 정확도)
• launchd sync (Mac mini → NAS)

🛍 Orders 04

Status-centric 7 카드 + 8국 sub-flags + 원가/수익/수익율 + 통합 송장 직송.

Status 카드 (좌 → 우)

• UNPAID / TO_RETURN / TO_CONFIRM_RECEIVE / IN_CANCEL / CANCELLED / READY_TO_SHIP / SHIPPED / COMPLETED
• 카드 클릭 → 해당 status 8국 동시 fetch + 표 렌더
• 국가 sub-flag 클릭 → 해당 국가만 필터

상세 패널

• 1열: 4 필드 (구매자 / DTS / 정확 시간 / 결제 방식)
• 2열: 상품 테이블 (이름 + 수량 + 가격 + KRW 원가 + 수익 + 수익율)
• 발주 + 송장 통합 버튼 (1 click → TSC DA220 직접 인쇄)

실시간 알림

• SSE /api/orders/stream 자동 연결 (_shell.js)
• 신규 주문 → 사운드 (new-order.mp3) + Notification + Toast
• 모바일은 Pushover OS push로 대체 (사운드 중복 방지)

💬 Chat 05

3-pane (sidebar + list + thread) + 8국 통합 + Gemma 자동 번역.

레이아웃

• 좌: 8국 sidebar (미확인 채팅 count + 국가 flag)
• 중: 대화 list (구매자 + 마지막 메시지 + 시각)
• 우: thread (수신 + 번역 + 송신)

Gemma 번역

• Mac Mini ollama gemma4:e4b-mlx-bf16
• LRU cache 1000개 + TTL 24h
• warm 1.6~1.8초, 8국 자동 매핑
• AbortController 10초 타임아웃

엔드포인트

• GET /chat/sessions/:country + /chat/messages/:sessionId
• POST /chat/send/:country — 메시지 송신
• POST /chat/translate — Gemma 번역
• 모든 호출 authFetch() 의무 (R7)

🧮 상품등록 (Calc) 06

상품가 + 배대지 + 배송비 + DTS + Stock 5-col 입력 → 8국 자동 계산 → AI Generate → 담아두기.

입력 (5 col 한 줄)

• 상품가 (KRW) / 배대지 / 배송비 / DTS / Stock
• 무게 hidden (글로벌 SKU 등록 후 Shopee API 진실원천)

8국 결과

• autoPrice (정가) + finalCost (최종 원가) + margin (마진율)
• 공식: autoPrice = (local × 2 + log) / (1 - sell - pg - svc)
• VN: feeSum에 ₫10,000 고정 추가

AI Generate (Vision 포함)

• Claude Sonnet 4.6 + 이미지 첨부 1568px resize
• 한글 입력 → 8국 영문/현지어 + 카테고리 + 마진 자동 적용
• banned 단어 STRICT 룰 적용

담아두기 → Publish

• "📋 보기/등록" 모달에서 항목 확인/삭제
• "🛍 Shopee" 버튼 → /2.0/publish queue로 navigate
• localStorage shopee_pending_calc_2.0 backup

🚀 Publish 07

2-col (1fr + 280px) — 메인 + 우측 요약/유의사항. 8국 Global SKU 등록 + retry + compliance.

Step 1 — Global SKU 등록

• queue 카드 렌더 + 체크박스 선택
• compliance 17 패턴 사전 검사 (banned 단어 / 카테고리 금지)
• needAttrs retry 모달 (필수 attribute 누락 시 추가 입력)
• rate limit retry: 15초 + 5×N (4회까지)
• SHOP CLOSURE confirm 모달 (특정 조건)

Step 2 — 8국 Publish + polling

• 등록 성공 카드 → 🚀 8국 publish 클릭
• progress bar + 8국 badge (pending → published → failed)
• polling backoff: 2 / 4 / 8 / 16초
• pending 0 도달까지 자동 갱신

📢 Promo 08

8 sub-tab 통합 — 할인 / 바우처 / AMS / 번들 / 타임세일 / 애드온 / 범프 / 쇼피 캠페인.

8 sub (단축키 1~8)

우측 사이드바 (280px)

• 요약 카드 — 진행 중 + 활성 마켓 + 데이터 출처
• 규칙 카드 — sub별 안전 장치 (AMS / 캠페인 = danger)
• 8국 매트릭스 — 4×2 grid

⚙️ Settings 09

7 섹션 — 계정 / 환율 / 수수료 / Partner / 샵 / 테마 / 알림.

진실원천 (Sprint 20-fix audit)

⌨️ 단축키 10

Promo 페이지 한정 단축키. 다른 페이지는 일반 브라우저 단축키 사용.

🔑 권한 매트릭스 11

3 등급 — 매니저 일반 / 캡틴 가격·발행 / admin 최고 권한. (코드 식별자는 captain/crew/intern 유지)

매니저 (일반, 코드: crew)

• 모든 조회 endpoint (GET 대부분)
• 주문 / 채팅 / 송장 인쇄
• 할인 / 바우처 / 번들 / 애드온 / 타임세일 생성·종료

캡틴 (가격·발행, 코드: captain)

• 환율 / 수수료 저장 (/config/rates / /config/fees)
• Bump 자동 설정 (/bump/settings)
• AMS captain endpoint (/ams/add-all / /batch-edit / /auto-add)

admin (최고, 코드: admin)

• Shopee Partner 인증 (/config POST)
• 샵 재인증 URL 생성 (/auth/url)
• 샵 삭제 (DELETE /shops/:shopId)
• Settings 전체 리셋 (DELETE /settings)
• config 직접 접근

❓ FAQ 12

Q. 로그인 후 placeholder 페이지가 나옵니다.

A. Sprint 19에서 /2.0/ 진입 시 토큰 보유 → /2.0/dashboard 즉시 redirect로 변경. 캐시 새로고침 (Ctrl+Shift+R) 후 진입.

Q. 환율 변경 후 다른 페이지에 반영이 안 됩니다.

A. 환율은 cfg.rates + localStorage 양쪽 sync. 페이지 새로고침으로 반영. 만약 가격 계산 페이지에서 0으로 표시되면 Settings에서 환율 9개 모두 양수 확인.

Q. AMS 추가가 진행되지 않습니다.

A. AMS는 SG 우선 dry-run. 다른 국가는 "AMS 미지원" 표시. captain 권한 필요. 광고비 0원이지만 7일 유예 적용 — 3중 confirm 모두 통과해야 진행.

Q. 모바일에서 알림 사운드가 들리지 않습니다.

A. 모바일은 Pushover OS push로 대체. _shell.js의 SSE handler에서 모바일 감지 (window.matchMedia('(max-width: 768px)')) 시 사운드 skip.

Q. 본사 캠페인 xlsx 양식이 다운로드되지 않습니다.

A. SheetJS CDN (https://cdn.sheetjs.com/...) 로드 확인. 브라우저 콘솔에서 window.XLSX undefined 시 네트워크 차단 가능성. VPN/방화벽 확인.

Q. Pending Queue가 자꾸 늘어납니다.

A. Discount 등록 실패 시 자동 큐 적재. Promo → 💸 할인 → "Pending 큐" 클릭 → list 확인 + 항목별 retry / 전체 retry.

🔧 트러블슈팅 13

401 자동 redirect 무한 루프

1. localStorage shopee_2_token 확인
2. 토큰 만료 시 자동 /2.0/login redirect
3. login 페이지에서 다시 토큰 있으면 returnTo redirect → 무한 루프 방지 위해 토큰 검증 후 진입

403 권한 부족

1. 현재 role 확인 (GET /me → user.role)
2. captain 또는 admin 필요한 endpoint 시도 시 발생
3. 관리자 (manager@geunju.kr) 에게 role 변경 요청

샵 토큰 만료

1. Settings → 샵 카드에서 "만료" badge 확인
2. "재인증 URL 생성" → 클립보드 복사 + 새 탭
3. Shopee Seller Center 로그인 → callback 자동 처리

SSE 끊김 (실시간 알림 안 옴)

1. 브라우저 콘솔에서 Shell.stopAlerts(); Shell.startAlerts(); 실행
2. 네트워크 차단 / proxy 확인
3. 5초 backoff 자동 재연결

가격 계산 0 으로 나옴

1. Settings → 환율 9개 모두 양수 확인
2. 수수료 fees {sell, pg, svc} 모두 0~1 사이 확인
3. localStorage shopee_settings_v1 검증

📝 변경 이력 14

Sprint 9 (2.0 Shell 인프라) → Sprint 21 (Manual). 출처: wiki/pages/meta/decisions-log.md