Trade Stats Lookup

무역통계 시장 스캔

이 스킬이 하는 일

HS코드 하나를 받아 어느 나라부터 뚫을지를 데이터로 답한다.

1. 국가별 한국 수출액·중량 시계열
2. 단가 추이 (금액 ÷ 중량) — 원인은 분해되지 않는다(가격 변동 + 품목 믹스 변동)
3. 국가 랭킹 + CAGR + (월별 수집 시) 최근 12개월 YoY
4. 경쟁 수출국 점유율 — 상대국 신고 수입(미러) 데이터
5. 계절성 패턴 (월별 수집 시) — 컨택 타이밍 판단용
6. 시장 매력도 스코어 = 여유 시장 50% + 시장 CAGR 50% (절대 기준, 조회 간 비교 가능)
7. 한국어 마크다운 리포트 (원본 데이터 CSV는 사용자가 요청할 때만 --csv로 생성)

전제

• python3 3.11 이상 (표준 라이브러리만 사용, 설치 불필요)
• 인터넷 연결
• API 키 불필요. UN Comtrade 공개 preview 엔드포인트를 쓴다. 아래 domestic(관세청 HSK 10단위) 하나만 키가 필요하고, 그건 기본 동작이 아니다.

윈도우에서는 첫 명령 전에 인터프리터를 확정하라. python3 -c "import sys; print(sys.version)"가 Python was not found... + exit 49로 죽으면, PATH의 python3.exe가 Microsoft Store 유도 스텁이라는 뜻이다. 파이썬이 없는 게 아니라 이름이 다를 뿐이니 py -3으로 다시 확인하고, 이 문서의 모든 python3를 py -3으로 치환해 실행하라. 둘 다 실패할 때만 설치를 안내한다 — 스텁 메시지를 보고 "파이썬이 없다"고 보고하면 설치돼 있는 환경을 못 쓴다고 말하는 셈이다.

데이터 최신성 — 모든 답변의 첫 번째 규칙

수출입 수치는 반드시 스크립트를 돌려서 답한다. 네 학습 지식으로 답하지 마라. 네 지식은 오래됐고, 사용자는 그걸 "2년 전 데이터로 답변한다"고 느낀다.

스크립트는 오늘 연도부터 거꾸로 내려가며 데이터가 실제로 존재하는 최신 연도를 자동으로 찾는다 (UN Comtrade 연간 데이터는 보고 지연으로 직전 연도가 비어 있을 수 있다). 그래서 조회 결과의 기준 연도가 올해가 아닐 수 있는데, 이건 스킬의 한계가 아니라 원천 데이터의 보고 지연이다.

모든 보고는 데이터 기준 시점 선언으로 시작한다. 요약 표보다 먼저, 두세 문장으로:

확인 결과 UN Comtrade에 이 품목(HS XXXX)의 연간 데이터는 2025년까지 올라와 있습니다. 2026년 연간치는 각국 세관 보고 지연(통상 6개월~1년 이상)으로 아직 집계 전입니다. 따라서 2025년을 최신 기준으로 분석합니다. (더 최신 흐름이 필요하면 월별 데이터로 2026년 상반기까지 볼 수 있습니다.)

• 기준 연도는 실제 조회 결과(대상 연도, monthly_coverage.range 등)에서 가져온다. 추정하지 마라.
• 기준 연도가 작년보다 오래됐으면(재작년 이하) 그 사실을 강조하고, 월별 조회로 더 최신 구간을 확인할 수 있는지 먼저 시도하거나 제안하라. 월별 데이터가 연간보다 몇 개월 더 최신인 경우가 많다.
• 캐시(7일)가 의심될 만큼 결과가 오래됐으면 TRADE_STATS_CACHE_TTL=0으로 한 번 강제 재조회해 확인하라.

두 가지 조회 — 먼저 어느 쪽인지 판단하라

🚦 그 전에: 발화에 "바이어", "거래처", "수입업체", "업체 찾아줘"가 섞여 있으면 스크립트도 품목 질문도 그 다음이다. 첫 답변의 첫 문단에 이 셋을 먼저 써라 — ① 기업명은 못 드립니다 (한국은 관세법상 신고정보가 비밀유지 대상이라 기업명×품목×금액이 어디에도 공개되지 않는다) ② 기업 단위가 필요하면 B/L 공개국(미국·인도)의 유료 데이터(Panjiva·ImportYeti·Volza) ③ 대신 어느 나라로 갈지는 지금 정할 수 있습니다 — 그러고 나서 품목과 명령을 묻는다. 빼먹고 조회부터 돌리면 사용자는 원한 걸 못 받은 채 10분을 기다린다. 말이 먼저, 조회가 나중이다.

market의 기본 대상은 한국 교역 상위 10개국이다. 그 10개국은 정의상 이미 팔고 있는 나라라서 거기서는 신규 시장이 나오지 않는다. "새로 뚫을 데", "안 가본 시장", "유망한 나라" 같은 질문에 market을 돌리면 이미 아는 답만 나온다 — 그때는 discover를 써라.

⏱ 첫 조회 1~2분(실측 HS3304 96초, 9콜). 두 연도를 전량 훑는데도 이 정도인 건 집계 시리즈만 요청해 배치 하나에 50개국이 들어가기 때문이다. timeout은 300000으로 준다.

python3 analyze.py discover --hs 3304   # timeout: 300000

두 연도 모두 전량 훑는다 — 최신 연도는 전 보고국, 과거 연도는 여유 시장 하한을 넘긴 나라 전부다. 결과의 method_note에 이 범위가 담겨 있으니 그대로 전달하라. JSON 요약과 함께 ~/trade-stats-out/hs<코드>_discover.md가 남는다. 경로를 알려줘라.

결과에는 국가별로 태그가 붙는다 — 미개척(한국 점유율 1% 미만), 초기진입(5% 미만), 고성장(시장 CAGR 10% 이상), 시장축소(CAGR 음수), 집계주의.

⚠️ 집계주의 태그가 붙은 나라는 그 숫자를 단독으로 인용하지 마라. 그 나라가 집계행 없이 내역행만 신고해서 총수입이 과대·과소집계일 수 있다는 뜻이다. 보고할 때 "이 나라는 통계 신고 형식 때문에 총액이 정확하지 않을 수 있다"고 덧붙이고, 후보로 살릴 거면 market --countries <그 나라>로 다시 확인하라.

discover는 경쟁 구도를 모른다. 1위 공급국·과점 여부·한국 수출 추이는 이 스캔에 없다. 후보가 2~5개국으로 좁혀지면 반드시 market --hs <코드> --countries <국가들>로 넘어가라 — 그게 이 스킬의 본 워크플로다.

기본 동작 — 이대로 하면 된다

사용자가 품목/HS코드를 말하면:

cd <스킬 경로>/scripts
python3 analyze.py market --hs 3907

기본값이 한국 전체 교역 상위 10개국(중국·미국·베트남·대만·홍콩·일본·싱가포르·인도·호주·말레이시아)이다. 사용자가 특정 국가를 지목하지 않았으면 이 기본값으로 먼저 돌린다.

⏱ 캐시가 비어 있으면 3~5분 걸린다 (10개국 = 약 35콜, 콜당 2초 + 429 발생 시 자동 감속). Bash 기본 타임아웃(120초)으로는 반드시 죽는다 — timeout을 600000(10분)으로 지정해 실행하라. 같은 조회 재실행은 캐시로 1초 안에 끝난다. 조회 전에 사용자에게 소요 시간을 말해둬라.

stdout으로 JSON 요약이, ~/trade-stats-out/hs<코드>_report.md에 리포트가 나온다. JSON 요약만 읽고 사용자에게 설명하라.

CSV는 사용자가 원본 데이터·엑셀 파일을 요청할 때만 만든다. 그때 --csv를 붙여 같은 명령을 다시 돌리면 캐시 덕에 즉시 끝나고 CSV가 생성된다. 요청 없이 미리 만들거나 경로를 안내하지 마라. 재실행 시 1회차와 완전히 동일한 옵션 전체(--countries, --top, --monthly, --years)를 그대로 반복하고 --csv만 추가하라. 하나라도 빠뜨리면 대상국·월별 데이터가 달라진 리포트가 기존 리포트를 조용히 덮어쓴다.

CSV에는 수치만이 아니라 근거 컬럼이 함께 들어간다 — 각 수치의 기준 연도, 성장률 계산 구간, 상대국 통계가 최신이 아니면 그 사실(partner_import_lagged), 비고, 출처, 조회일. 컬럼 뜻을 설명하는 hs<코드>_columns.md도 같이 생성된다. CSV를 건넬 때 답변에 이걸 명시하라: 근거 컬럼이 포함돼 있다는 것, 설명 파일이 있다는 것, 그리고 특히 기준 연도가 다른 컬럼이 섞여 있으면(예: 한국 수출은 2025년인데 상대국 수입 통계는 2024년) 그 사실을 실무자 언어로. "미러", "stale", "후퇴 조회" 같은 내부 용어를 답변에 쓰지 마라 — "그 나라가 아직 최신 연도 통계를 안 올려서 한 해 전 기준입니다"처럼 풀어 써라.

⚠️ 백그라운드로 돌리지 마라. 몇 분이 길어 보여 run_in_background를 쓰고 싶겠지만, 셸이 중간에 종료되면서 출력 폴더가 만들어지지 않는 사례가 반복 확인됐다. 포그라운드로 기다려라. 출력은 기본이 ~/trade-stats-out이다. 스킬 폴더 안에 쓰지 마라 — 플러그인을 업데이트하면 날아가고 사용자가 찾지도 못한다. 조회를 여러 번 겹쳐 돌릴 때만 --outdir로 갈라라.

국가를 지정할 때

python3 analyze.py market --hs 3304 --countries KZ,UZ,KG --years 3

--countries는 한글명도 받는다: --countries 카자흐스탄,우즈베키스탄

월별 시계열·계절성이 필요할 때

python3 analyze.py market --hs 3304 --countries VN --monthly 24

--monthly N은 국가당 N콜 + 최신월 탐색 몇 콜이라 느리다(콜당 약 2초). 24개월 × 3개국 = 약 3분. 국가를 2~3개로 좁힌 뒤에만 쓴다. 전체 상위 10개국에 붙이지 마라 — 10분 넘게 걸린다.

• --monthly 24 미만을 쓰지 마라. YoY는 24개월, 계절성은 각 달 2회 이상 관측이 필요하다. 모자라면 스크립트가 계산하지 않고 이유를 yoy_note/seasonality에 담아준다. 그대로 전달하라.
• 월별 보고는 2~6개월 지연된다. 스크립트가 데이터가 실제로 있는 최신 월을 먼저 찾고 거기서부터 N개월을 뒤로 잡는다. 그래서 "최근 24개월"은 오늘 기준이 아니라 보고 기준이다. monthly_coverage.range에 실제 구간이 들어 있으니 사용자에게 이 구간을 말해줘라.

국가는 정했는데 품목을 모를 때 — 역방향 조회

"싱가포르에 뭘 팔면 좋을까", "유망 품목이 뭐야" 같은 질문이면 HS코드를 묻지 말고 이걸 돌려라:

python3 analyze.py products --to 싱가포르

한국이 그 나라에 이미 팔고 있는 전 품목을 챕터(HS2)·품목(HS4) 단위로 훑어 규모 상위와 성장 상위(기본: 최신연도 vs 2년 전, 수출액 $1M 이상)를 JSON으로 준다. 한국 수출 실적은 "수요가 검증됐다"의 근거이지, 그 물량을 신규 진입자가 가져올 수 있다는 뜻이 아니다 — 이 구분을 답변에 항상 포함하라.

보고할 때:

• 사용자의 체급에 맞춰 걸러라. 1인 상사·중소기업이면 반도체(85)·석유(27)·선박(89)· 기계(84)·귀금속(71) 같은 대기업 영역 챕터는 표에서 빼고 그 사실을 한 줄로 밝힌다. 소비재·경량 품목(화장품 33, 식품 16–22, 생활화학 34, 과일 07–08 등) 위주로 추린다.
• 성장 상위 목록에는 급성장했지만 절대액이 작은 품목이 섞인다. 규모 표와 성장 표를 분리해서 보여주고, hs4_declining의 감소세 품목도 "피할 품목" 표로 알려준다.
• HS4 상세(규모·성장·감소 표)는 수출액 상위 챕터만 조회한 것이다. hs4_coverage.note에 커버리지 %가 들어 있으니 보고에 그대로 전달하라. 챕터(HS2) 표만 전 품목 기준이다 — 관심 챕터가 커버 목록에 없으면 그 챕터를 지목해 다시 조회하면 된다.
• 후보 품목이 1~2개로 좁혀지면 그 HS코드로 market을 돌려 경쟁 구도·주변국 비교로 넘어간다 — 그게 이 스킬의 본 워크플로다.

주요 옵션

관세청 정밀 조회 (domestic) — 기본이 아니다, 먼저 꺼내지 마라

이 스킬은 키 없이 쓰는 도구다. market, discover, products, hs-search, 관세율은 전부 키 없이 돈다. domestic 하나만 관세청 인증키가 필요하고, 먼저 권하지 마라.

사용자가 아래를 직접 물었을 때만 꺼낸다. 그때 references/customs-hsk.md를 읽고 따른다.

• HS 6단위로 우리 제품이 특정되지 않을 때 ("우리는 그 코드 안에서 OO만 만든다")
• 단가가 오르내린 원인을 물을 때 (HS6는 분해 불가, HSK 10단위는 가능)
• 더 최신 숫자를 요구할 때 ("올해 것 없어?") — 관세청은 익월 공표다
• HSK, 10단위, 관세청을 사용자가 직접 언급할 때

시장 규모, 경쟁국 점유율, 매력도, "어느 나라부터"는 이걸로 답할 수 없다. 상대국 신고 통계라서 관세청에 아예 없다. 그런 질문에 domestic을 꺼내지 마라.

키가 없으면 명령이 발급 안내를 그대로 뱉는다. 그 안내문을 전달하되, 키 없이 지금 답할 수 있는 부분을 먼저 답하라. 사용자가 "됐고"라고 하면 다시 권하지 않는다.

발굴 조회 옵션

보조 명령

HS코드를 모를 때 — 한국어 품목명을 그대로 넣어라. 번역하지 마라.

python3 fetch_comtrade.py hs-search "화장품"
python3 fetch_comtrade.py hs-search "이차전지"
python3 fetch_comtrade.py hs-search "자동차부품" --level 4

한국어 색인(챕터 96개 + 주요 품목 123개)이 내장돼 있다. 결과의 matched 필드가 ko면 한국어 색인이 잡은 것이고 ko_keyword에 걸린 단어가 담긴다 — 사용자에게 이걸 보여주고 확인받아라.

한국어로 안 잡히면 그때 영어로 재검색한다. 번역 힌트는 references/hs-codes.md.

python3 fetch_comtrade.py hs-search "polyethylene terephthalate"

국가 코드 확인:

python3 fetch_comtrade.py country-search 카자흐

단발 조회 (리포트 없이):

python3 fetch_comtrade.py rank --hs 3907 --year 2025          # 전체 상대국 랭킹, 1콜
python3 fetch_comtrade.py mirror --hs 3907 --importer VN --year 2024
python3 fetch_comtrade.py series --hs 3907 --partner US --from 2024-01 --to 2025-12

관세율 조회 — 상대국이 한국산에 무는 세율

"베트남 관세 몇 %야", "FTA 혜택 있어?", "중국보다 유리해?" 같은 질문이면 references/tariff.md를 읽고 따른다. World Bank WITS 데이터라 인증키는 필요 없다. 한국 관세청 세율(한국이 수입할 때)이 아니라 상대국이 한국산에 적용한 세율이고, 느리다 — 단독 25분, --compare 3개국이면 510분이라 timeout 600000이 필요하다. 기준 연도 고지와 TradeNavi 재확인 안내를 포함해 상세 규칙은 참조 파일에 있다. 시장 보고의 ③ 다음 단계에서 제안하기 좋다 — 점유율 격차의 원인이 관세인 경우가 많다.

워크플로

1. 사용자가 품목명만 말했으면 hs-search에 한국어 그대로 넣어 후보를 찾고, 어느 코드로 볼지 먼저 확인받는다. 잘못된 코드로 만든 리포트는 숫자가 그럴듯해서 더 위험하다. 기본은 HS 4단위, 제품이 특정되면 6단위를 쓴다. 갈리는 코드면 스크립트가 멈춘다(종료코드 3). 후보를 보여줄 때는 코드·설명·걸린 한국어 키워드를 같이 보여준다.
2. 사용자가 HS 8/10단위를 줬으면 앞 6자리로 자른다고 명시적으로 말하고 진행한다. (UN Comtrade는 6단위까지만 있다.)
3. 국가 지정이 없으면: "새로 뚫을 데"를 묻는 질문이면 discover, 아니면 상위 10개국 기본값으로 analyze.py market을 돌린다. 판단이 애매하면 사용자에게 한 줄로 물어라 — "이미 거래 중인 나라들 중에서 볼까요, 안 가본 나라까지 찾아볼까요?"
4. JSON 요약을 읽고 아래 "보고 형식"대로 한국어로 보고한다. 줄글로 풀어쓰지 마라.
5. 관심 국가가 2~3개로 좁혀지면 --monthly 24로 다시 돌려 계절성·YoY를 본다.
6. 사용자가 원본 데이터·엑셀 파일을 원하면 그때 --csv로 재실행해(캐시라 즉시 끝난다) 경로를 알려준다. 엑셀에서 바로 열린다(UTF-8 BOM). 근거 컬럼·설명 파일이 포함됐음을 답변에 명시한다(위 "기본 동작"의 CSV 규칙 참조).

보고 형식 — 표 먼저, 근거는 그 다음

결과 보고는 반드시 이 순서다. 그 외의 서론·배경 설명으로 시작하지 마라.

⓪ 데이터 기준 시점 (두세 문장). 위 "데이터 최신성" 규칙대로 — 어느 시점까지의 데이터가 확보됐고, 왜 그게 최신이며, 이걸 기준으로 분석한다는 선언. 이것만 표보다 앞에 온다.

① 요약 표. 조회된 전 국가를 한 표에 담는다. 열 구성:

• 금액은 $1.2B, $340M처럼 축약하고 연도를 열 머리에 명시한다 (예: "한국 수출액(2025)").
• 순위 제외 국가도 표에서 빼지 말고 매력도 칸에 제외(데이터 부족)처럼 세 단어 이내로 넣는다. score_note 전문은 표 한 칸에 안 들어가니 표 아래 각주로 옮겨라. 측정 불가 ≠ 나쁜 시장.
• 값이 없는 칸은 -로 두고 추정으로 채우지 않는다.
• 표 바로 아래에 결론 한두 문장: 어느 나라부터, 왜.

② 표 근거 — 정량 데이터는 전부 표로. 표의 판단이 어떤 숫자에서 나왔는지를 보여준다. 수치가 2개 이상 나열되는 항목은 줄글·불릿이 아니라 표로 만든다. 불릿은 표 아래 한 줄 해석에만 쓴다. 형용사("빠르게 성장", "점유율이 높다")만 쓰지 말고 반드시 수치를 병기하라.

• 경쟁 구도 표: 국가별 상위 공급국과 점유율 %, 한국 순위·%를 표로. dominated가 true면 과점 시장이라고 표 아래에 명시.
• CAGR 격차 표: 국가별로 시장 CAGR | 한국 수출 CAGR | 격차(%p)를 표로. 격차가 음수면 점유율을 잃는 중이라고 해석을 붙인다.
• 단가 표 (여러 국가·연도가 있으면): 변화폭 %만 제시하고 원인은 단정하지 않는다 ("프리미엄화" 금지 — 품목 믹스 변동일 수 있다).
• 상위 3개국 해석: 어느 축(규모/성장/여유) 때문에 올라왔는지를 축별 수치로 한 줄씩. 예: "베트남 — 시장규모 $2.1B(조회국 중 1위), 시장 CAGR +14%, 한국 점유율 8% → 여유 축 상위"
• 실측 가중치: 명목 가중치(40/35/25)가 아니라 리포트가 출력한 실측 비중으로 어느 축이 순위를 갈랐는지.
• 데이터 공백: 비어 있는 국가·연도는 비어 있다고 명시. stale, score_basis, 각종 *_note의 내용은 빠짐없이 전달하되, 필드명·영문 키 자체는 노출하지 말고 실무자 언어로 풀어 쓴다(위 "기본 동작"의 용어 규칙과 같은 원칙).

③ 다음 단계 제안 (짧게). 월별 추이·계절성까지 볼 후보 국가 제안, 상위 후보국 시장 동향 브리핑 제안(아래 "시장 브리핑" 참조). 원본 데이터가 필요하면 엑셀용 CSV로 뽑아줄 수 있다고 한 줄만 언급한다 — 경로는 실제 요청받아 생성한 뒤에 알려준다.

월별 조회 결과도 같은 원칙: YoY·계절성을 월별 수치 표로 먼저, 해석은 그 아래.

명령어·플래그를 답변에 노출하지 마라. 사용자는 해외영업 실무자이지 개발자가 아니다. --monthly 24, analyze.py market 같은 것은 네가 내부에서 쓰는 도구일 뿐이다. "월별 추이를 이어서 볼까요? 베트남·인도 2개국이면 3분쯤 걸립니다"처럼 자연어로 제안하고, 사용자가 하겠다고 하면 네가 알아서 돌려라. 옵션 선택이 필요하면 옵션명이 아니라 그 옵션이 답하는 질문("최근 2년 월별로 볼까요, 연간 추이만 볼까요?")으로 물어라.

시장 브리핑 — 통계 다음의 옵트인 단계

통계 표를 받은 사용자의 다음 질문은 "그래서 그 나라 시장이 지금 어떤데?"다. Comtrade 숫자에 없는 것(규제·관세 변화, 현지 수요 트렌드, 최근 업계 동향)은 웹 검색으로 보완할 수 있다.

기본은 끈다. 자동으로 붙이지 마라. 통계 보고의 ③ 다음 단계에서 "1~2위 국가의 시장 동향 브리핑을 이어서 볼까요?"처럼 제안만 하고, 사용자가 원할 때만 진행한다. 매 조회마다 자동으로 붙이면 응답이 길고 느려진다.

진행할 때는 상위 1~2개국으로 좁혀 WebSearch로 조사한다. 조사 축: ① 해당 품목 관련 규제·관세· 인증 변화 ② 현지 수요·트렌드 ③ 주요 경쟁사·업계 최근 동향. 오래된 기사보다 최근 1년 내 출처를 우선하고, 언제 시점의 정보인지 밝힌다.

정량과 정성을 절대 섞지 마라.

• 브리핑은 통계 보고와 별도 섹션("○○ 시장 브리핑 — 웹 검색 기반")으로 분리한다. Comtrade 수치는 검증 가능한 데이터고 웹 브리핑은 출처 신뢰도가 제각각이다. 섞으면 리포트 전체의 신뢰성이 가장 약한 출처 수준으로 떨어진다.
• 브리핑의 모든 주장에는 출처 링크를 단다. 출처를 못 찾은 내용은 쓰지 않는다.
• 브리핑 내용으로 매력도 순위나 표의 수치를 수정하지 않는다. 순위는 통계만으로 산출된 것이다. 브리핑이 순위와 다른 방향을 가리키면(예: 통계상 1위인데 규제 강화 소식) 둘 다 제시하고 판단 재료로 넘긴다.

"바이어 찾아줘"라는 요청을 받으면

이 스킬은 바이어 실명을 줄 수 없다. 그런데 사용자는 결국 이걸 묻는다. 얼버무리지 말고 먼저 못 한다고 말한 다음, 할 수 있는 걸로 연결하라. 순서를 바꾸면 안 된다.

1. 왜 없는지 한 문장으로. "한국은 관세법상 신고정보가 비밀유지 대상이라 기업명×품목×금액이 어디에도 공개되지 않습니다. 관세청도 무역협회도 마찬가지입니다." — 도구의 한계가 아니라 법적 제약이라는 점이 중요하다. 그래야 다른 무료 도구를 더 찾아 헤매지 않는다.
2. 유료 경로. B/L 공개국만 기업 단위가 나온다 — 미국·인도 등. Panjiva / ImportYeti / Volza.
3. 질문을 뒤집어 제안한다. "대신 어느 나라에 바이어를 찾으러 갈지는 지금 정할 수 있습니다." 바이어 발굴의 앞 단계다. 품목을 물어보고 진행하라. 사과는 한 번이면 된다.

데이터가 부실할 때 스크립트가 하는 일

자동으로 처리되므로 네가 재시도할 필요 없다. 다만 결과에 담긴 사유는 사용자에게 그대로 전달하라.

순위에서 제외된 국가는 "그 시장이 나쁘다"는 뜻이 아니다. 측정이 안 됐다는 뜻이다. 사용자에게 이 구분을 반드시 말하라. 이런 국가는 한국 수출 실적만 별도로 보여준다.

--no-competitors를 쓰면 시장 규모를 모르게 되므로 전 국가가 순위 제외된다. 점수가 필요하면 이 옵션을 쓰지 마라.

매력도 스코어를 설명할 때

점수 = 여유 시장 50% + 시장 CAGR 50%.

여유 시장 = 그 나라 총수입 × (1 − 한국 점유율). 아직 한국 몫이 아닌 수입액이다. "시장이 큰가"와 "들어갈 자리가 있는가"를 한 개의 달러 금액으로 합친 값이고, 실무 언어로는 지금 테이블에 남아 있는 돈이다. 사용자에게 점수를 설명할 때는 이 금액을 먼저 말하라 — "베트남은 남은 파이가 $1.8억이고 그게 연 15%씩 크고 있습니다"가 "75.3점"보다 훨씬 낫다.

두 축 모두 절대 기준이다.

• 여유 시장: $1천만 이하 0점, $100억 이상 만점 (그 사이는 로그)
• 시장 성장률: 연 −10% 이하 0점, +20% 이상 만점

그래서 어느 나라를 함께 조회하든 같은 나라는 같은 점수가 나오고, 다른 조회에서 나온 점수와도 비교할 수 있다. 비교군을 바꿔 여러 번 돌릴 필요가 없다 — 예전 버전은 상대 점수여서 그렇게 안내했지만 지금은 아니다. 국가 하나만 조회해도 점수가 나온다.

상한을 두는 이유를 물으면: 상한이 없으면 규모가 순위를 지배해서 점수가 그냥 "수입액 큰 나라 순"이 된다(실측 Spearman +0.89). $75억 시장과 $130억 시장의 차이는 중소 수출기업이 어느 쪽을 먼저 갈지를 바꾸지 않는다.

성장 축은 그 나라의 총수입 성장률이다. 한국 수출 성장률이 아니다. 둘은 다른 질문에 답한다 — 리포트가 두 열을 나란히 보여주니 격차를 읽어라. 시장은 크는데 한국 수출이 줄면 점유율을 잃는 중이고, 시장이 죽는데 한국 수출만 늘면 중계무역 경유일 가능성이 있다.

명목 가중치(50/50)와 실제로 순위를 움직인 비중은 다르다. 여러 나라가 여유 시장 상한에 걸려 나란히 만점이면 그 축은 순위를 못 가른다. 리포트가 실측 비중을 같이 출력하니 그걸 근거로 설명하라.

순위에서 빠진 국가는 두 종류이고 뜻이 정반대다. 절대 뭉뚱그리지 마라.

규모 미달 기준이 사업 규모에 안 맞으면(1인 무역상, 고단가 소량 품목) --min-market을 낮춰 다시 돌려라. 사용자가 "이렇게 작은 시장도 우리한테는 크다"고 하면 이걸 제안하라.

"여유 시장"은 아직 안 뚫린 몫이라는 뜻이지 뚫기 쉽다는 뜻이 아니다. 1위 공급국이 60% 이상 쥔 과점 시장이면 여유 금액이 커도 그 자리는 이미 남이 앉아 있다 — 리포트의 ⚠️ 표시를 같이 전달하라. 반대로 한국 점유율이 이미 높은 시장은 여유 금액이 작아도 제품 적합성이 이미 입증된 시장이다.

반드시 지킬 데이터 한계

사용자가 물으면 얼버무리지 말고 이대로 답한다. 자세한 내용은 references/data-notes.md.

• 점유율은 "수입 중 점유율"이지 "시장 점유율"이 아니다. 미러 데이터에는 현지 제조사가 통째로 빠져 있다. "베트남 라면 한국 점유율 53%"는 수입되는 라면 중 53%라는 뜻이고, 현지 Acecook·Masan이 가져가는 내수는 안 잡힌다. 사업적으로 완전히 다른 결론이므로 점유율을 말할 때마다 "수입 기준"임을 명시하라. 식품·자동차·철강·화장품처럼 현지 생산이 강한 조합에서 특히 위험하다. 같은 이유로 "현지 총수입"은 그 나라의 시장 규모가 아니다.
• 기업 단위 데이터는 없다. 한국은 관세법상 신고정보가 비밀유지 대상이라 기업명 × 품목 × 금액이 공개되지 않는다. 관세청도 무역협회도 제공하지 않는다. "어느 회사가 수출하는지"는 이 스킬로 답할 수 없다. 바이어 실명이 필요하면 B/L을 공개하는 나라(미국·인도 등)의 유료 데이터(Panjiva/ImportYeti/Volza)가 필요하다.
• HS 6단위까지만. 10단위는 관세청 오픈API가 필요하다(인증키 발급 필요, 이 스킬 범위 밖).
• 한국 수출액은 FOB, 상대국 수입액은 CIF 기준이라 같은 거래도 금액이 다르게 잡힌다. 점유율은 미러 데이터 안에서만 비교하고 두 소스를 섞어 계산하지 마라.
• 미러 데이터는 UN Comtrade 보고국만 나온다. 미보고국은 경쟁국 점유율이 비어 있다.
• 최신 데이터는 보고 지연으로 2~6개월 비어 있을 수 있다. 스크립트가 자동으로 뒤로 물러나 조회한다.
• 대만은 Comtrade에서 Other Asia, nes(코드 490)로 잡힌다. 리포트에는 "대만"으로 표시된다.

캐시와 레이트리밋

• 응답은 ~/.cache/trade-stats-lookup/에 7일 캐시된다. 같은 조회를 다시 돌리면 즉시 끝난다.
• 무료 공개 티어라 스크립트가 요청 간격을 두고 호출한다. 429가 오면 서버가 지정한 대기 시간을 따르고 남은 조회의 간격을 자동으로 올린다(최대 15초). 그래서 뒤로 갈수록 느려질 수 있는데 정상이다. 직접 재시도하지 마라.
• 그래도 429로 실패하면 TRADE_STATS_MIN_INTERVAL=6을 주고 다시 돌려라. 국가 수 × 연도 수가 크면(예: 5개국 × 4년) 기본 간격으로 부족할 수 있다. 캐시 덕에 이미 성공한 콜은 재사용된다.
• 환경변수: TRADE_STATS_MIN_INTERVAL(기본 2.0초, 1초 미만 불가 — 늘리는 용도), TRADE_STATS_CACHE_TTL(기본 604800), TRADE_STATS_CACHE_DIR.
• 여러 명이 같은 IP를 쓰는 사내 환경이면 간격을 늘려 쓰기를 권한다.

실패 대응

참조 파일

필요할 때만 읽어라.

• references/hs-codes.md — 한국어 품목명 → 영어 검색어 힌트, 주요 수출품 HS코드
• references/country-codes.md — 국가 코드·별칭 규칙, Comtrade 표기 함정
• references/data-notes.md — 데이터 출처·한계·다음 단계(Phase 0/2/3) 상세
• references/customs-hsk.md — 관세청 HSK 10단위 조회(domestic). 키가 필요할 때만 읽어라
• references/tariff.md — 관세율 조회 상세 규칙. 관세 질문을 받았을 때만 읽어라

완료 기준

• 보고가 데이터 기준 시점 선언으로 시작했다 — 어느 시점까지의 데이터인지, 왜 그게 최신인지.
• 이어서 요약 표가 나오고, 표 아래에 정량 근거가 붙어 있다. 수치 2개 이상인 근거는 표로 제시했다.
• 사용자가 "어느 나라부터"에 대한 답을 순위와 근거로 받았다.
• 매력도를 점수가 아니라 여유 시장 금액과 성장률로 먼저 설명했다.
• 측정불가와 규모 미달을 구분해 전달했다.
• 경쟁 구도(1위 공급국·한국 순위)를 알았다.
• 데이터가 없는 부분은 없다고 명시했다. 추정으로 채우지 않았다.
• CSV는 사용자가 요청한 경우에만 생성해 경로를 안내했다.