@nomadamas/k-skill 0.1.0

package/skills/naver-news-search/instruction.md

@@ -0,0 +1,103 @@
+# Naver News Search
+
+## What this skill does
+
+`k-skill-proxy`가 네이버 검색 Open API 뉴스 검색(`openapi.naver.com/v1/search/news.json`)을 호출해 최근 뉴스 기사 후보를 정규화된 JSON 으로 돌려준다.
+
+- 검색어 기반 최신 뉴스 후보 목록을 정리한다.
+- 기사 제목, 본문 요약(description), 발행 시각(`pub_date`/`pub_date_iso`), 네이버 뉴스 링크(`link`), 원문 링크(`original_link`)를 제공한다.
+- Naver 가 응답에 섞어주는 `<b>` 하이라이트 태그와 HTML entity(`&amp;`, `&quot;`, `&lt;` 등)는 proxy 쪽에서 미리 제거한다.
+- 사용자 로그인·개인화·회원 전용 뉴스는 지원하지 않는다.
+
+## When to use
+
+- "오늘 삼성전자 관련 뉴스 찾아줘"
+- "최근 AI 규제 관련 기사 최신순으로 5개만"
+- "네이버 뉴스에서 금리 인상 기사 요약해줘"
+- "이 사건 기사 링크 정리해줘"
+
+## When not to use
+
+- 특정 언론사 내부 유료 기사, 로그인 뒤에만 보이는 기사
+- 기사 본문 전체가 필요한 경우 (API 는 요약 description 만 제공)
+- 주식/환율/부동산 실시간 시세 (뉴스 API 는 기사만 다룬다)
+- 차단/CAPTCHA 우회가 필요한 경로
+
+## Required inputs
+
+검색어(`q` / `query`)가 없으면 먼저 물어본다.
+
+권장 질문:
+
+> 찾을 네이버 뉴스 검색어를 알려주세요. 예: "삼성전자 실적", "인공지능 규제", "금리 인상"
+
+단어 2글자 미만이면 의미가 불분명하므로 되묻는다.
+
+## Proxy endpoint
+
+기본값은 public/read-only/no-auth 프록시다. 사용자는 **네이버 개발자 센터 Client ID/Secret 을 발급받지 않아도 된다**. upstream key(`NAVER_SEARCH_CLIENT_ID` / `NAVER_SEARCH_CLIENT_SECRET`)는 프록시 서버에서만 주입한다.
+
+```bash
+curl -fsS --get "${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/v1/naver-news/search" \
+  --data-urlencode 'q=삼성전자 실적' \
+  --data-urlencode 'display=10' \
+  --data-urlencode 'sort=date'
+```
+
+쿼리 파라미터:
+
+- `q` 또는 `query` — 검색어. 2글자 이상.
+- `display` — 반환 건수. 기본 10, 범위 1~100.
+- `start` — 검색 시작 위치(1-indexed). 기본 1, 최대 1000. **`start + display - 1` 은 1000 을 넘을 수 없다**: 예를 들어 `start=1000 & display=100` 은 `1099`번째 아이템을 요구하므로 proxy가 업스트림 호출 전에 `400 bad_request`("start + display exceeds Naver's 1000-item search window")로 거절한다. 아주 오래된 기사를 찾으려면 검색어를 좁히는 것이 낫다.
+- `sort` — `sim`(유사도 순, 기본값) 또는 `date`(최신순). 그 외 값은 `sim` 으로 fallback.
+
+응답 주요 필드:
+
+- `items[].title` — `<b>` 태그·HTML entity 가 제거된 기사 제목
+- `items[].description` — `<b>` 태그·HTML entity 가 제거된 기사 요약
+- `items[].link` — 네이버 뉴스 redirect 링크
+- `items[].original_link` — 원문 뉴스 링크(빈 문자열이면 `null`)
+- `items[].pub_date` — 원본 RFC822 형식 발행 시각
+- `items[].pub_date_iso` — 파싱된 ISO-8601(UTC) 발행 시각. 파싱 실패시 `null`
+- `meta.extraction` — 항상 `naver-openapi`
+- `meta.total`, `meta.start`, `meta.display`, `meta.last_build_date`, `meta.sort`
+
+## Workflow
+
+1. 검색어를 확인한다. (없거나 2글자 미만이면 먼저 물어본다)
+2. 사용자가 "최신순"을 원하면 `sort=date`, 그 외에는 `sort=sim` 으로 호출한다.
+3. `GET /v1/naver-news/search` 를 호출한다.
+4. `items` 가 있으면 상위 3~5건을 제목, 발행 시각(KST 기준으로 재포맷해도 좋다), 요약, 링크로 짧게 정리한다.
+5. 발행 시각은 `pub_date_iso` 기준으로 오늘/어제 표기를 붙여도 된다. (KST = UTC+9)
+6. `items` 가 비었거나 `upstream_error` 가 나면 재시도하지 말고 검색어를 좁혀 다시 물어본다.
+
+## Response style
+
+- 기사 제목/요약은 API 가 돌려준 원문만 인용한다. 원문에 없는 해설은 덧붙이지 않는다.
+- 기사 발행 시각은 "KST 기준 {YYYY-MM-DD HH:mm}" 또는 "{n}시간 전" 정도로 짧게 표시한다.
+- 원문 링크(`original_link`)가 있으면 우선 노출하고, 없으면 `link`(네이버 뉴스 redirect)를 안내한다.
+- 서로 다른 언론사가 같은 사건을 다루면 링크 2~3개를 병렬로 제시해 사용자가 비교할 수 있게 한다.
+- `description` 은 요약이므로, 팩트로 단정하지 말고 "기사 요약에 따르면"이라고 전한다.
+
+## Failure modes
+
+- `400 bad_request` — 검색어 누락, 2글자 미만, 허용되지 않는 파라미터, 혹은 `start + display - 1 > 1000` 조합(네이버 1000-item search window 초과). 에러 메시지를 그대로 사용자에게 노출한다.
+- `503 upstream_not_configured` — 프록시 서버에 `NAVER_SEARCH_CLIENT_ID`/`NAVER_SEARCH_CLIENT_SECRET` 가 없는 경우. 운영자가 키를 등록해야 한다. 사용자에게는 "잠시 후 다시 시도해 주세요" 정도로 안내한다.
+- `401 upstream_error` — 프록시 서버의 Client ID/Secret 이 잘못된 경우(`errorCode: 024`). 운영자가 재발급해야 한다.
+- `429 upstream_error` — 네이버 검색 API 일일 쿼터(25,000 호출/일) 초과(`errorCode: 010`). 재시도 루프는 금지. 잠시 후 다시 시도하도록 안내한다.
+- `502 upstream_error` — 네이버 API 5xx 또는 응답 JSON 파싱 실패.
+- upstream 차단이나 장애 발생 시 재시도하지 않는다. cache + rate limit 만으로 대응하고, 사용자에게는 현재 조회 불가능함을 분명히 말한다.
+
+## Privacy
+
+- 검색어/결과를 영구 저장하지 않는다.
+- 기사 본문은 요청하지 않는다. description(API 가 주는 요약)만 사용한다.
+- 특정 인물·사건을 비방·추측하는 서술은 하지 않는다. 기사 원문만 전달한다.
+
+## Done when
+
+- 검색어를 확인했다.
+- 최소 1건 이상의 기사를 제목·요약·발행 시각·링크로 정리해서 돌려주거나, 왜 결과가 없는지 설명했다.
+- 발행 시각은 KST 기준으로 표시했다.
+- 네이버 API 쿼터 상태·차단 발생 여부·재시도 금지 원칙을 지켰다.
+- 로그인/개인화/차단 우회 범위를 벗어나지 않았다.

package/skills/naver-news-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "naver-news-search",
+  "description": "네이버 검색 Open API 뉴스 검색(news.json)을 k-skill-proxy 경유로 조회해 최신 뉴스 기사 제목·발행시각·링크·요약을 보수적으로 정리한다. 사용자는 별도 API 키 발급 없이 호출한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: naver-news-search\ndescription: 네이버 검색 Open API 뉴스 검색(news.json)을 k-skill-proxy 경유로 조회해 최신 뉴스 기사 제목·발행시각·링크·요약을 보수적으로 정리한다. 사용자는 별도 API 키 발급 없이 호출한다.\nlicense: MIT\nmetadata:\n  category: information\n  locale: ko-KR\n  phase: v1"
+}

package/skills/naver-shopping-search/instruction.md

@@ -0,0 +1,94 @@
+# Naver Shopping Search
+
+## What this skill does
+
+`k-skill-proxy`가 네이버 검색 Open API 쇼핑 검색(`shop.json`)을 우선 사용하고, 키가 없을 때만 네이버 쇼핑/검색의 로그인 없는 공개 BFF JSON endpoint를 **단일 검색 요청**으로 가져와 상품 후보를 정규화한다.
+
+- 상품명/검색어로 네이버 쇼핑 후보를 찾는다.
+- 현재 노출 가격, 판매처, 링크, 이미지, 리뷰/구매 수(노출될 때만)를 정리한다.
+- 가격이 낮은 후보와 공식몰/브랜드몰 후보를 분리해서 비교할 수 있다.
+- 주문, 장바구니, 찜, 로그인 세션 접근은 하지 않는다.
+
+## When to use
+
+- "네이버 쇼핑에서 에어팟 가격 비교해줘"
+- "네이버 최저가로 커피머신 찾아줘"
+- "네이버 쇼핑 링크랑 판매처별 가격을 비교해줘"
+- "이 상품 네이버 쇼핑에서 얼마쯤 해?"
+
+## When not to use
+
+- 회원 전용가, 쿠폰 적용가, 네이버페이 개인화 혜택을 확정해야 하는 경우
+- 주문/장바구니/찜/로그인이 필요한 액션
+- 차단 우회, CAPTCHA 우회, fingerprint spoofing 등 접근 통제를 우회해야 하는 경우
+
+## Required inputs
+
+상품명 또는 검색어가 없으면 먼저 물어본다.
+
+권장 질문:
+
+> 찾을 네이버 쇼핑 상품명이나 검색어를 알려주세요. 예: 에어팟 프로 2세대, 아이폰 15 케이스
+
+검색어가 너무 넓으면 브랜드/용량/모델명을 추가로 물어본다.
+
+## Proxy endpoint
+
+기본값은 public/read-only/no-auth 프록시다. 프록시 서버에 `NAVER_SEARCH_CLIENT_ID`와 `NAVER_SEARCH_CLIENT_SECRET`이 있으면 공식 Search API를 우선 사용한다.
+
+```bash
+curl -fsS --get "${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/v1/naver-shopping/search" \
+  --data-urlencode 'q=에어팟 프로 2세대' \
+  --data-urlencode 'limit=10' \
+  --data-urlencode 'sort=rel'
+```
+
+쿼리 파라미터:
+
+- `q` 또는 `query` — 검색어. 2글자 이상.
+- `limit` — 반환 개수. 기본 10, 최대 40으로 clamp.
+- `page` — 페이지. 기본 1. no-key BFF fallback에서는 BFF의 `page`를 요청하고 해당 페이지 카드만 정규화한다.
+- `sort` — `rel`, `date`, `price_asc`, `price_dsc`, `review` 중 하나. 알 수 없는 값은 `rel`.
+  - 공식 Search API 경로는 네이버 API sort를 사용한다. 단, 공식 API가 `review` 정렬을 지원하지 않아 `review` 요청은 upstream `sort=sim`으로 조회하고 `meta.sort_applied: "unsupported"`, `meta.upstream_sort: "sim"`으로 표시한다.
+  - no-key BFF fallback은 `rel`은 BFF 노출 순서를 유지하고, `price_asc`/`price_dsc`/`review`는 선택된 BFF 페이지 카드 안에서 로컬 정렬한다. BFF 카드에 날짜 필드가 없어 `date`는 `meta.sort_applied: "unsupported"`로 표시하고 BFF 노출 순서를 유지한다.
+
+응답 주요 필드:
+
+- `items[].title`
+- `items[].price` / `items[].price_text`
+- `items[].mall_name`
+- `items[].url`
+- `items[].image_url`
+- `items[].review_count`, `purchase_count`, `score` (노출될 때만)
+- `meta.extraction` — `naver-openapi`, `bff-json`, `embedded-json`, `html-card`, `none`
+- `meta.sort_applied` — `upstream`, `local`, `unsupported` 중 하나
+
+## Workflow
+
+1. 검색어를 확인한다.
+2. `GET /v1/naver-shopping/search` 를 호출한다.
+3. `items`가 있으면 요청 sort와 `meta.sort_applied`를 확인한 뒤 가격 낮은 순, 공식/브랜드몰 여부, 리뷰 수 등을 기준으로 3~5개 후보를 짧게 비교한다.
+4. `meta.extraction`과 조회 시각 기준임을 함께 말한다.
+5. `items`가 비었거나 upstream 차단/오류가 나면 우회 시도를 반복하지 말고, 검색어를 좁히거나 브라우저 수동 확인을 안내한다.
+
+## Response style
+
+- 가격은 "조회 시점 네이버 쇼핑 노출가"라고 표현한다.
+- 배송비, 쿠폰, 옵션 추가금, 회원 혜택은 비로그인 공개 검색만으로 확정하지 않는다.
+- 판매처 신뢰도는 노출된 판매처명/리뷰 수만 근거로 보수적으로 말한다.
+- 최저가만 단정하지 말고 동률/옵션 차이를 조심한다.
+
+## Failure modes
+
+- 공식 Search API 키가 없어서 BFF fallback을 사용할 때는 네이버가 특정 IP/환경에 418/403 등 bot-block 응답을 줄 수 있다.
+- no-key fallback은 `ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui` 공개 JSON path를 사용한다.
+- 검색 결과 BFF JSON 스키마는 비공식 프론트엔드 표면이라 바뀔 수 있다.
+- 가격/품절/배송 정보는 실시간으로 바뀐다.
+- 프록시는 접근 통제 우회를 하지 않는다. 공식 Search API 또는 단일 공개 검색 요청 + 캐시 + rate limit만 사용한다.
+
+## Done when
+
+- 검색어를 확인했다.
+- 네이버 쇼핑 후보를 최소 1개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.
+- 가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.
+- 로그인/주문/차단 우회 범위를 벗어나지 않았다.

package/skills/naver-shopping-search/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "naver-shopping-search",
+  "description": "네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "browser",
+    "action:commerce"
+  ],
+  "frontmatter": "name: naver-shopping-search\ndescription: 네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v1"
+}

package/skills/nhis-care-checkup-search/instruction.md

@@ -0,0 +1,116 @@
+# NHIS Care And Checkup Search
+
+## What this skill does
+
+국민건강보험공단 장기요양기관 검색서비스(data.go.kr `15059029`)와 검진기관 찾기 조회(data.go.kr `15154419`)를 `k-skill-proxy` 경유로 호출해 공개 기관 후보를 조회한다.
+
+## When to use
+
+- "서울 강남 장기요양기관 찾아줘"
+- "요양원 후보와 주소/전화번호 확인해줘"
+- "서울 강남 건강검진기관 찾아줘"
+- "주말 검진 가능한 검진기관 찾아줘"
+
+## When not to use
+
+- 의료 판단, 장기요양 등급 판정, 특정 기관 추천 보증
+- 예약·신청·민감 의료정보 조회 자동화
+
+## Prerequisites
+
+- 인터넷 연결
+- hosted/self-host `k-skill-proxy`의 `/v1/nhis/long-term-care`, `/v1/nhis/checkup/*` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 필요한 서비스의 활용신청이 승인돼 있어야 한다.
+
+키 발급:
+
+- 장기요양기관 검색 서비스: <https://www.data.go.kr/data/15059029/openapi.do>
+- 건강검진기관 검색 서비스: <https://www.data.go.kr/data/15154419/openapi.do>
+- 공공데이터포털 이용 가이드: <https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do>
+
+## Inputs
+
+장기요양기관 route:
+
+- `q`, `query`, `name`, 또는 `adminNm`: 기관명 검색어
+- `sido` 또는 `siDoCd`: 시도 코드
+- `sigungu` 또는 `siGunGuCd`: 시군구 코드
+- `service_kind` 또는 `serviceKind`: 급여/서비스 종류 코드
+- `page` 또는 `pageNo`: 기본 1
+- `limit` 또는 `numOfRows`: 기본 10, 최대 100
+
+건강검진기관 route:
+
+- route operation: `list`, `by-region`, `by-checkup-type`, `holiday`
+- `q`, `query`, `name`, 또는 `hmcNm`: 검진기관명 검색어
+- `sido` 또는 `siDoCd`: 시도 코드
+- `sigungu` 또는 `siGunGuCd`: 시군구 코드
+- `hchk_type`, `checkup_type`, 또는 `hchkTypeCd`: 검진 유형 코드
+- `page` 또는 `pageNo`: 기본 1
+- `limit` 또는 `numOfRows`: 기본 10, 최대 100
+
+## Workflow
+
+### 1. Decide the surface
+
+장기요양기관이면 `/v1/nhis/long-term-care`를 사용한다. 건강검진기관이면 검색 목적에 맞춰 `/v1/nhis/checkup/list`, `/v1/nhis/checkup/by-region`, `/v1/nhis/checkup/by-checkup-type`, `/v1/nhis/checkup/holiday` 중 하나를 사용한다.
+
+### 2. Query long-term care institutions through the proxy
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/nhis/long-term-care" \
+  --data-urlencode "q=강남" \
+  --data-urlencode "sido=11" \
+  --data-urlencode "limit=10"
+```
+
+### 3. Query health checkup institutions through the proxy
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/nhis/checkup/by-region" \
+  --data-urlencode "q=검진" \
+  --data-urlencode "sido=11" \
+  --data-urlencode "limit=10"
+```
+
+### 4. Summarize source fields
+
+응답 XML의 `item` 필드에서 기관명, 주소, 전화번호, 급여종류, 검진유형, 운영일처럼 upstream이 제공한 공개 항목만 요약한다. 사용자가 실제 이용·입소·검진 예약을 하려면 NHIS 또는 기관에 직접 확인하라고 안내한다.
+
+## Failure modes
+
+- `400 bad_request`: 검색어/지역/서비스 종류 중 하나도 없거나 코드/페이지 값이 잘못됨.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 가 없음.
+- `502 upstream_forbidden`: data.go.kr gateway가 키를 거부함.
+- 빈 결과: 지역 코드나 기관명 표기를 완화해서 재검색한다.
+- 특정 서비스만 실패: 같은 `DATA_GO_KR_API_KEY`라도 data.go.kr 서비스별 활용신청이 별도라서 `15059029` 또는 `15154419` 승인 상태를 확인한다.
+
+## Done when
+
+- 장기요양기관 조회는 `k-skill-proxy` route로 수행했고 사용자에게 API key를 요구하지 않았다.
+- 건강검진기관 조회는 `k-skill-proxy` route로 수행했고 사용자에게 API key를 요구하지 않았다.
+- 결과에는 기관명, 위치, 연락처, 원천 서비스와 조회 조건을 함께 적었다.
+
+## Maintainer review notes
+
+키 없이 가능한 검증:
+
+- `./scripts/validate-skills.sh`
+- `node --test packages/k-skill-proxy/test/server.test.js`
+- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/nhis/long-term-care" --data-urlencode "q=강남"` (키 미설정이면 503 확인)
+- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/nhis/checkup/by-region" --data-urlencode "q=검진" --data-urlencode "sido=11"` (키 미설정이면 503 확인)
+
+Live smoke는 hosted/self-host proxy에 `DATA_GO_KR_API_KEY`가 설정되고 `15059029` 또는 `15154419` 활용신청이 승인된 뒤 수행한다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 의료 판단, 장기요양 등급 판정, 예약/신청 자동화는 하지 않는다.
+- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.

package/skills/nhis-care-checkup-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "nhis-care-checkup-search",
+  "description": "국민건강보험공단 장기요양기관·건강검진기관을 조회하고, 돌쇠에서는 공식 연락·예약 가능 표면까지 이어간다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:booking"
+  ],
+  "frontmatter": "name: nhis-care-checkup-search\ndescription: 국민건강보험공단 장기요양기관·건강검진기관을 조회하고, 돌쇠에서는 공식 연락·예약 가능 표면까지 이어간다.\nlicense: MIT\nmetadata:\n  category: healthcare\n  locale: ko-KR\n  phase: v1"
+}

package/skills/nts-business-registration/instruction.md

@@ -0,0 +1,115 @@
+# 국세청 사업자등록정보 진위확인 및 상태조회
+
+## What this skill does
+
+공공데이터포털의 **국세청_사업자등록정보 진위확인 및 상태조회 서비스**를 `k-skill-proxy` 경유로 호출해 다음을 확인한다.
+
+- `status`: 사업자등록번호 기준 상태조회 (`계속사업자`, `휴업자`, `폐업자`, 과세유형 등 upstream 응답 그대로 포함)
+- `validate`: 사업자등록번호 + 개업일자 + 대표자명(및 선택 필드) 기준 진위확인
+
+## When to use
+
+- "이 사업자등록번호가 계속사업자인지 확인해줘"
+- "사업자등록번호 상태조회해줘"
+- "사업자등록번호, 개업일, 대표자명으로 진위확인해줘"
+- 거래처 등록 전 공식 NTS/공공데이터포털 기준 확인이 필요할 때
+
+## Prerequisites
+
+- 인터넷 연결
+- `python3`
+- 설치된 skill payload 안에 `scripts/nts_business_registration.py` helper 포함
+- hosted/self-host `k-skill-proxy`의 `/v1/nts-business/status`, `/v1/nts-business/validate` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 `국세청_사업자등록정보 진위확인 및 상태조회 서비스` 활용신청이 되어 있어야 한다.
+
+## Validate privacy boundary
+
+- `validate`는 대표자명(`p_nm`), 개업일자(`start_dt`), 주소·상호 같은 선택 메타데이터를 hosted proxy와 공공데이터포털 upstream으로 전송한다.
+- hosted proxy는 `validate` 성공 응답을 캐시하지 않고, 프록시 `query` echo를 붙이지 않으며, upstream이 요청값을 되돌려도 민감 입력 필드를 응답에서 제거한다.
+- 프록시의 기본 Fastify request logging은 꺼져 있다. 운영자가 별도 로그를 켠 self-host 환경에서는 요청 본문 로깅 정책을 직접 점검해야 한다.
+- hosted proxy 경유가 부담스러운 진위확인 업무는 `KSKILL_PROXY_BASE_URL`로 직접 운영하는 self-host proxy를 지정한다.
+
+## Official surfaces
+
+- 공공데이터포털 문서: `https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do?publicDataPk=15081808`
+- 상태조회 upstream: `POST https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=...`
+- 진위확인 upstream: `POST https://api.odcloud.kr/api/nts-businessman/v1/validate?serviceKey=...`
+- 프록시 route: `POST /v1/nts-business/status`, `POST /v1/nts-business/validate`
+
+## Inputs
+
+### 상태조회
+
+- `b_no`: 사업자등록번호 10자리. 하이픈은 허용되며 helper/proxy가 숫자만 남긴다.
+- 한 요청은 최대 100개까지 보낸다.
+
+### 진위확인
+
+필수:
+
+- `b_no`: 사업자등록번호 10자리
+- `start_dt`: 개업일자 `YYYYMMDD` (하이픈/점 허용)
+- `p_nm`: 대표자 성명
+
+선택:
+
+- `p_nm2`: 대표자 성명2
+- `b_nm`: 상호
+- `corp_no`: 법인등록번호
+- `b_sector`: 주업태명
+- `b_type`: 주종목명
+- `b_adr`: 사업장주소
+
+텍스트 필드는 NTS 입력 규격에 맞춰 보수적으로 길이를 제한한다(`p_nm`/`p_nm2` 30자, `b_nm` 200자, `b_sector`/`b_type` 100자, `b_adr` 500자). `corp_no`는 제공할 경우 숫자 13자리여야 한다.
+
+## Workflow
+
+1. 사용자 입력에서 사업자등록번호는 숫자 10자리인지 확인한다.
+2. 상태조회만 필요하면 `status`를 호출한다.
+3. 진위확인은 최소 `b_no`, `start_dt`, `p_nm`이 있을 때만 호출한다.
+4. 개인정보/거래처 정보는 필요한 필드만 보내고, 프록시 응답을 그대로 보존하되 핵심 상태/진위 결과를 짧게 요약한다.
+5. upstream이 `upstream_not_configured`, 활용신청 미승인, 인증키 오류 등을 반환하면 설정/승인 문제로 안내한다.
+
+## CLI examples
+
+```bash
+python3 scripts/nts_business_registration.py status \
+  --b-no 123-45-67890
+```
+
+```bash
+python3 scripts/nts_business_registration.py validate \
+  --business-json '{"b_no":"123-45-67890","start_dt":"2020-01-31","p_nm":"홍길동","b_nm":"테스트상사"}'
+```
+
+## Direct proxy examples
+
+```bash
+curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/status" \
+  -H 'content-type: application/json' \
+  -d '{"b_no":["123-45-67890"]}'
+```
+
+```bash
+curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/validate" \
+  -H 'content-type: application/json' \
+  -d '{"businesses":[{"b_no":"123-45-67890","start_dt":"20200131","p_nm":"홍길동"}]}'
+```
+
+## Failure modes
+
+- `400 bad_request`: 사업자등록번호가 10자리가 아니거나 진위확인 필수 필드가 빠짐.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY`가 없음.
+- upstream 인증/활용신청 오류: API 키가 해당 서비스에 승인되지 않았거나 만료/오류 상태.
+- 빈 결과 또는 진위불일치: 공식 응답의 `valid`, `valid_msg`, `b_stt` 값을 그대로 근거로 설명한다.
+
+## Done when
+
+- 상태조회는 공식 응답의 `b_stt`, `b_stt_cd`, `tax_type` 등 핵심 필드를 확인했다.
+- 진위확인은 `valid`, `valid_msg` 결과를 확인했다.
+- API 키는 사용자에게 요구하지 않고 프록시 서버에만 둔다는 점을 지켰다.