weshp-cli 원샷 주문
이 스킬은 weshp-cli(Weshp 해외직구 CLI)를 구동하여 사용자를 대신해 제품 검색, 장바구니 관리, 주문 및 결제를 완료합니다.
1단계: 바이너리 찾기
바이너리는 이 스킬의 bin/ 디렉토리 안에 함께 제공됩니다. 먼저 런타임 환경을 감지하세요.
uname -sm # 예: "Darwin arm64"
uname -sm 결과 | 사용할 바이너리 (이 스킬의 bin/ 아래; 절대 경로 $SKILL_DIR/bin/...) |
|---|---|
Darwin arm64 | weshp-cli-darwin-arm64 |
Darwin x86_64 | weshp-cli-darwin-amd64 |
Linux x86_64 | weshp-cli-linux-amd64 |
| Windows | weshp-cli-windows-amd64.exe |
- 이 스킬의 디렉터리는 현재 SKILL.md 파일이 있는 디렉터리이며, bin 디렉터리는 그 아래의
bin/입니다. - 실행 시
Permission denied오류가 발생하면chmod +x <binary>를 먼저 실행하세요. - 이 문서 전체에서
$WESHP는 해당 바이너리의 절대 경로를 나타냅니다.
세션 파라미터 전달
사용자가 대화에서 다음 중 하나를 제공하면, 해당 플래그를 세션의 모든 $WESHP 명령어에 추가하세요(세션 전체에 걸쳐 일관되게 유지하고 중간에 제거하지 마세요).
| 사용자가 제공한 정보 | 추가할 플래그 |
|---|---|
| 환경 (예: 测试环境/테스트 환경) | --env test (사용자가 명시적으로 生产环境/프로덕션이라고 말하는 경우에만 --env prod 사용) |
| 익명 장바구니 ID | --anonymous-id <id> |
| 언어 (예: zh-CN, en-US) | --accept-language <language> (매핑 규칙은 아래 "언어 적응" 참조) |
| appId | --app-id <appId> |
제공되지 않은 항목에 대해서는 플래그를 추가하지 마세요(기본 구성을 사용합니다). 유일한 예외는 --accept-language입니다. 사용자가 명시적으로 제공하지 않은 경우 "언어 적응"의 규칙에 따라 자동으로 추가하세요. 또한 이러한 파라미터를 사용자에게 미리 묻지 마세요.
환경
CLI는 --env를 통해 환경을 선택하며 기본적으로 프로덕션 환경에 연결됩니다.
| 환경 | 게이트웨이 | 체크아웃 페이지 (결제 의도) |
|---|---|---|
prod (기본값) | https://weshv.com/store | https://checkout.airwallex.com/#/standalone/checkout |
test | https://test.weshv.com/store | https://checkout-demo.airwallex.com/#/standalone/checkout |
- 프로덕션은 실제 결제가 이루어지는 곳입니다. 기본(프로덕션) 환경에서 쓰기 명령어(
order create,payment create-intent, ...)를 실행하기 전에 사용자가 주문과 결제가 실제임을 인지하고 있는지 확인하세요. "보안 제약" 확인 시 어떤 환경을 대상으로 하는지 명시해야 합니다. - 직접 게이트웨이 주소 재정의(
--gateway/WESHP_GATEWAY)는 더 이상 지원되지 않습니다.--env를 통해서만 환경을 전환하세요.
언어 적응
이 스킬은 다국어 사용자를 지원합니다. 세션 시작 시 사용자의 현재 대화 언어를 기반으로 로케일을 결정하고, 세션 전체에 걸쳐 일관되게 유지하며 중간에 전환하지 마세요.
| 사용자의 대화 언어 | 로케일 (--accept-language 값) |
|---|---|
| 简体中文 | zh-CN |
| 繁體中文 | zh-TW |
| English | en-US |
| Deutsch | de-DE |
| 日本語 | ja-JP |
| Français | fr-FR |
| Español | es-ES |
| Português (European Portuguese) | pt-PT |
| Italiano | it-IT |
| 판별 불가 / 일치 없음 | --accept-language 생략, 게이트웨이 기본값 사용 |
결정 및 사용 규칙:
- 하드 제약 (최우선 순위): 사용자에게 보이는 모든 텍스트는 사용자의 마지막 메시지 언어여야 합니다. 대화 내용뿐만 아니라 명령어 호출 시 사용자에게 표시되는 명령어 설명(Bash 설명), 주문 요약, 확인 질문 등 사용자가 볼 수 있는 모든 것에 적용됩니다. 이 규칙은 이 파일의 나머지 부분과 "항상 특정 언어로 응답"하는 전역 지침보다 우선합니다. 이 스킬의 문서나 명령어 출력이 다른 언어로 되어 있더라도 사용자의 언어로 표현하세요.
--accept-language의 세 가지 우선순위: ① 사용자가 명시적으로 제공 → 명시적 값 사용; ② 제공되지 않음 → 위 표에서 사용자의 대화 언어를 기준으로 조회하여 모든$WESHP명령어에 추가; ③ 판별 불가 또는 일치 없음 → 생략하고 게이트웨이 기본값 사용.- 사용자 대상 출력은 사용자의 대화 언어를 따릅니다: 주문 요약, 품절 알림, "저장된 정보 재사용 / 기억하기 / 결제 확인"과 같은 모든 확인 문구, 오류
message/hint설명, 그리고 주문 결과 보고서는 모두 사용자의 언어로 작성되어야 합니다. - 샘플 문구는 의미만 전달합니다: 이 파일에 인용된 샘플 문구(예: "저장된 정보를 재사용하시겠습니까?", "저장된 PAYPAL을 재사용하시겠습니까?", "품절 (N개만 남음)")는 의미만 표현합니다. 실제 응답은 사용자의 언어로 다시 표현해야 합니다. 다른 언어를 사용하는 사용자에게 샘플 문구를 그대로 붙여넣지 마세요.
- 로컬 출력에 대한
--accept-language의 범위: 테이블 렌더링 텍스트(헤더, 푸터, 주문 요약/배송 라인) 및--help/사용법 텍스트(명령어 설명, 플래그 설명, 템플릿 레이블)는--accept-language를 통해 현지화됩니다(2026-09-07부터, CLIinternal/i18n참조). 따라서--format table및--help출력은 사용자에게 그대로 전달할 수 있습니다. 로컬 오류 메시지(예:Error:,Cancelled)는 기본적으로 영어로 표시됩니다. 영어를 사용하지 않는 사용자에게 이러한 메시지를 표시할 때는 의미를 해당 언어로 설명하고 그대로 붙여넣지 마세요. - 간체 vs. 번체 중국어: 사용자가 간체 중국어를 쓰면
zh-CN으로 설정하고 간체로 응답합니다. 번체 중국어를 쓰면zh-TW로 설정하고 번체로 응답합니다. - 번역하지 마세요: JSON 필드 이름, CLI 플래그, 열거형 값(예:
PAYPAL), 금액, skuId 등은 그대로 유지합니다.
프로필 파일 위치
프로필 파일(배송 정보 및 결제 방법)은 이 스킬의 디렉터리에 있으며, 익명 장바구니 ID 제공 여부에 따라 선택됩니다.
| 익명 ID 제공 여부 | 프로필 파일 경로 (이 스킬 디렉터리 기준 상대 경로) |
|---|---|
--anonymous-id <id> 제공됨 | profiles/<anonymous-id>.json |
| 제공되지 않음 | profile.json |
- 읽기(저장된 정보 재사용)와 쓰기(사용자가 저장 동의)는 동일한 규칙을 따릅니다. 익명 ID가 있으면 해당 ID의 파일을 사용하고, 없으면
profile.json을 사용합니다. - 익명 ID로 저장할 때는
profiles/디렉터리가 없으면 먼저 생성합니다. 각 익명 ID의 프로필 파일은 다른 ID 및 ID 없는profile.json과 독립적입니다. - 세션 내에서 동일한 익명 ID에 대해 프로필 파일 경로를 일관되게 유지하고, 중간에 파일을 전환하지 마세요.
표준 주문 흐름
- 제품 검색:
$WESHP product search-sku --sku-name "<키워드>" --format table- 컬럼:
skuId,name(변형 이름),price(단가),stock(현재 재고;⚠는 품절을 표시). - 테이블 푸터는 총 개수와 현재 페이지/크기를 보여줍니다.
total이 현재 페이지를 초과하면--page-num을 사용하여 나머지 페이지를 가져옵니다(모든 제품을 한 번에 보려면 최대값인--page-size 100을 사용하세요). - 사용자가 결과에서 정확한 제품과 수량을 선택/확인하도록 하고, 각 skuId의
stock과price를 기억하세요(세션 메모리; 목적은 "주요 규칙 및 주의사항"의 재고 항목 참조).
- 컬럼:
- 주문 정보 수집 (이메일, 수령인 이름, 전화번호, 상세 배송 주소):
- 먼저 위의 "프로필 파일 위치" 규칙에 따라 프로필 파일을 확인합니다.
- 파일이 존재함 → 저장된 정보를 사용자에게 보여주고 재사용할지 물어봅니다. 승인하면 바로 사용하고, 사용자가 변경을 원하면 계속 진행하기 전에 파일을 업데이트합니다.
- 파일이 존재하지 않음 → 사용자에게 정보를 요청합니다. 누락된 항목이 있으면 반드시 물어보아야 합니다. 절대 임의로 생성하지 마세요.
- 첫 번째 수집 후, 다음 번을 위해 이 정보를 저장할지 사용자에게 물어봅니다. 동의하면 위 규칙의 경로에 따라 프로필 파일에 씁니다(익명 ID 시나리오에서는
profiles/디렉터리가 없으면 먼저 생성). 거절하면 저장하지 않고 이 세션에만 사용합니다.
- 먼저 위의 "프로필 파일 위치" 규칙에 따라 프로필 파일을 확인합니다.
- 주문 생성:
$WESHP order create --email <email> \ --receiver-name "<name>" --receiver-phone "<phone>" \ --receiver-address "<address>" \ --sku-id <skuId> --sku-name "<product name>" --quantity <quantity> --yes- 응답에서
orderNo,orderId및 주문 총액(--amount에 사용할 원시 리터럴)을 가져옵니다. --sku-id/--sku-name으로 직접 주문할 때 CLI는 자동으로 가격을 조회하고 재고를 확인하므로 별도 처리가 필요하지 않습니다.--sku-id없이 장바구니를 통해 결제할 수 있습니다(먼저$WESHP cart add --sku-id <id> --quantity <n>실행). 결제 전에 아래 재고 항목에 따라 세션 메모리를 확인하세요.
- 응답에서
- 결제 의도 생성:
$WESHP payment create-intent --order-no <orderNo> --email <email> \ --amount <order response의 raw amount literal> --payment-method <method> --yes- 결제 방법:
CREDIT_CARD | PAYPAL | APPLE_PAY | GOOGLE_PAY. 먼저 프로필 파일을 확인합니다(위 "프로필 파일 위치" 규칙에 따라). 저장된 방법이 있으면 사용자에게 "저장된 PAYPAL을 재사용하시겠습니까?"라고 확인합니다. 저장된 방법이 없으면 어떤 방법을 사용할지 물어봅니다. 첫 번째 선택 후, 저장할지 물어봅니다(배송 정보와 동일한 프로필 파일 사용). - 응답은
clientSecret/clientId와 조립된checkoutUrl을 반환합니다. CLI는 기본 브라우저에서 체크아웃 페이지를 자동으로 열어 결제를 완료합니다(실제 결제는 해당 페이지에서 이루어짐).--no-open을 추가하면 자동 열기를 건너뛰고 URL만 출력합니다.
- 결제 방법:
- 결제 상태 확인:
$WESHP payment status --payment-no <create-intent에서 반환된 paymentNo>
테이블 표시
대화 중에 사용자에게 표 형식 데이터(검색 결과, 장바구니 내용, 주문 목록)를 보여줄 때는 직접 테이블을 렌더링하지 마세요. --format table과 함께 CLI 명령어를 실행하고 상자 그리기 출력을 사용자에게 그대로 전달하세요. 테이블을 작성하기 위해 외부 렌더링 스크립트(Python/awk/Go/…)를 작성하지 마세요. 또한 Markdown 테이블을 사용하지 마세요. 문자 수로 정렬되며 CJK 셀이 테두리를 깨트리기 때문입니다. 여러 페이지를 병합해야 하는 경우 테이블을 다시 그리는 대신 CLI 출력 옆에 추가 정보를 일반 텍스트로 요약하세요.
유일한 예외 — 주문 확인 요약 (order create 전, "보안 제약"에 필요. 이 비대화형 흐름에서는 항상 --yes가 전달되며 CLI 자체의 대화형 확인 요약에 도달할 수 없으므로 대화에서 표시해야 함): 항목당 하나의 상자 그리기 테이블 행("name | quantity | unitPrice | subtotal")과 최종 추정 총액 행을 ```text 코드 블록 안에 직접 렌더링하고, 배송 정보(이메일, 수령인, 전화번호, 주소)를 테이블 바로 아래에 짧은 목록으로 표시합니다. 단가 및 재고 사전 확인을 위해 검색 단계에서 기억한 price/stock을 사용합니다.
렌더링 규칙(위 예외에만 적용):
- 레이아웃:
┌─┬┐상단 테두리,├─┼─┤각 행 사이 구분선,└─┴┘하단 테두리. - 열 너비는 표시 너비로 계산합니다. CJK/전각 문자는 2, 상자 그리기 테두리 문자는 2, ASCII는 1,
⚠는 2(사용자의 macOS 터미널에서 2열 너비로 렌더링됨을 확인). - 정렬: 헤더는 가운데 정렬, 텍스트 열은 왼쪽 정렬, 숫자 열은 오른쪽 정렬. 모든 셀은 각 측면에 1칸의 패딩을 가집니다.
- 레이아웃을 망가뜨릴 수 있는 긴 값(이미지 URL 등)은 생략하고, 자르지 않습니다.
주요 규칙 및 주의사항
- 금액 리터럴은 주문 응답과 정확히 일치해야 합니다(예:
10.0을 반환하면10.0을 전달). 그렇지 않으면 서버 서명 확인에서 거부됩니다. - 종료 코드:
0성공;1게이트웨이 비즈니스 오류;2인수 검증 실패;3네트워크 오류. 실패 시 JSON 출력은 stderr로 전송되며{ok:false, error:{type,code,message,hint}}형식입니다.message/hint를 사용자에게 그대로 전달합니다. - 재고 세션 메모리:
search-sku가 반환하는stock은 실제 현재 재고입니다. 제품을 검색한 후, 각 skuId의 재고를 세션 내에서 기억하고 장바구니 추가/주문 생성 전에 사전 확인으로 사용합니다.- 메모리 적중 (이 세션에서 제품이 검색됨): 요청한 수량이 재고보다 많으면 사용자에게 직접 "「xxx」는 품절되었습니다 (N개만 남음)"라고 알리고 작업을 실행하지 마세요.
- 메모리 미스 (이 세션에서 검색되지 않음): 정상적으로 진행합니다. 재고 오류가 반환되면 사용자에게 "「xxx」는 품절되었습니다"라고 알리고 사용자를 안내하여 먼저 제품 정보를 검색(
search-sku)하도록 하여 계속 진행할지 결정하기 전에 최신 재고를 확인하도록 하세요. - 재고는 동적입니다. 세션 메모리는 소프트 사전 확인일 뿐입니다. 두 경우 모두 품절 시 재시도하지 마세요.
- 쓰기 명령어에 대한 블라인드 재시도 금지:
order create,cart add,payment create-intent또는 다른 쓰기 작업이 실패한 후에는 중복 주문을 방지하기 위해 블라인드 재시도하지 마세요. 작업 전에 먼저 상태를 확인하세요(order get/order list). - 조회 명령어는 네트워크 오류 시 재시도할 수 있습니다(CLI에 내장 재시도가 있으므로 추가 외부 재시도는 필요하지 않습니다).
보안 제약
order create를 실행하기 전에 사용자에게 전체 주문 요약(제품, 수량, 단가, 배송 정보, 예상 총액)을 보여주고 명시적인 확인을 받으세요.--yes는 CLI의 대화형 확인만 건너뛰며 사용자 확인을 대체할 수 없습니다.- 장바구니 삭제/비우기 및 주문 취소도 마찬가지입니다. 먼저 확인을 받고 실행하세요.
- 주문 성공 후 주문 번호, 금액, 결제 상태 확인 방법을 사용자에게 알리세요.
- 쿠폰은 사용되지 않습니다. 가격은 제품의 현재 가격을 기준으로 합니다.