# 근처 블루리본 맛집 가이드

## 이 기능으로 할 수 있는 일

- 유저가 알려준 현재 위치를 공식 Blue Ribbon zone 으로 매칭
- 공식 Blue Ribbon zone 목록으로 동네/역명 매칭
- k-skill-proxy 경유 nearby 블루리본 맛집 검색
- 거리순 상위 결과 정리

> [!NOTE]
> Blue Ribbon의 `/restaurants/map` 은 프리미엄 전용입니다. 이 기능은 k-skill-proxy 에 설정된 프리미엄 세션(`BLUE_RIBBON_SESSION_ID`)을 경유해 nearby 검색을 수행합니다.

## 먼저 필요한 것

- 인터넷 연결
- `node` 18+
- `blue-ribbon-nearby` package 또는 이 저장소 전체 설치

## 가장 먼저 할 일

이 기능은 **반드시 현재 위치를 먼저 물어본 뒤** 실행합니다.

권장 질문 예시:

```text
현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 블루리본 맛집을 찾아볼게요.
```

## 입력값

- 동네/상권: `광화문`, `성수동`, `판교`
- 역명/랜드마크: `강남역`, `서울역`, `코엑스`
- 좌표: `37.573713, 126.978338`

랜드마크는 내부 alias 로 가장 가까운 공식 Blue Ribbon zone 이름에 매칭합니다. 예: `코엑스` → `삼성동/대치동`

맛집 문의는 기본적으로 `blue-ribbon-nearby` 스킬부터 검토합니다.

## 공식 Blue Ribbon 표면

- 지역/상권 목록: `https://www.bluer.co.kr/search/zone`
- 주변 맛집 JSON: `https://www.bluer.co.kr/restaurants/map`
- 검색 페이지: `https://www.bluer.co.kr/search`

주변 검색의 핵심 파라미터:

- `zone1`
- `zone2`
- `zone2Lat`
- `zone2Lng`
- `isAround=true`
- `ribbon=true`
- `ribbonType=RIBBON_THREE,RIBBON_TWO,RIBBON_ONE`
- `distance=500|1000|2000|5000`

좌표만 있을 때는 `latitude1`, `latitude2`, `longitude1`, `longitude2` bounding box 로 nearby 범위를 만든다.

## 기본 흐름

1. 유저에게 반드시 현재 위치를 묻습니다.
2. 동네/역명/랜드마크를 받으면 공식 `search/zone` 목록에서 가장 가까운 zone 후보를 찾습니다.
   - 공식 zone 이름이 아닌 대표 랜드마크는 먼저 nearest zone alias 로 확장합니다. 예: `코엑스` → `삼성동/대치동`
3. 좌표를 받으면 nearby bounding box 를 계산합니다.
4. k-skill-proxy 의 `/v1/blue-ribbon/nearby` 에 좌표와 거리를 넘겨 nearby 검색을 수행합니다. 프록시가 프리미엄 세션으로 `/restaurants/map` 을 호출합니다.
5. 거리순 상위 결과를 3~5개 정리합니다.

## Node.js 예시

```js
const { searchNearbyByLocationQuery } = require("blue-ribbon-nearby");

async function main() {
  const result = await searchNearbyByLocationQuery("광화문", {
    distanceMeters: 1000,
    limit: 5
  });

  console.log(result.anchor);
  console.log(result.items);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

기본적으로 k-skill-proxy 를 경유합니다. 직접 호출이 필요하면 `useDirectApi: true` 옵션을 사용하세요 (프리미엄 세션 없이는 `premium_required` 에러).

## Live smoke 예시

아래 값은 **2026-03-27** 에 `광화문`, `distanceMeters=1000`, `limit=5` 로 실제 호출해 확인한 결과 일부입니다.

```json
{
  "anchor": {
    "zone1": "서울 강북",
    "zone2": "광화문/종로2가"
  },
  "items": [
    {
      "name": "미치루스시",
      "ribbonType": "RIBBON_ONE",
      "ribbonCount": 1,
      "distanceMeters": 61
    },
    {
      "name": "한성옥",
      "ribbonType": "RIBBON_ONE",
      "ribbonCount": 1,
      "distanceMeters": 170
    },
    {
      "name": "청진옥",
      "ribbonType": "RIBBON_TWO",
      "ribbonCount": 2,
      "distanceMeters": 242
    }
  ]
}
```

## 운영 팁

- 위치 문자열이 애매하면 동네보다 **가까운 역명** 또는 **위도/경도** 를 한 번 더 받는 편이 정확합니다.
- zone 후보가 여러 개면 바로 검색하지 말고 2~3개만 다시 확인합니다.
- 결과를 길게 나열하기보다 거리순 상위 3~5개만 먼저 보여주는 편이 좋습니다.

## 주의할 점

- Blue Ribbon `/restaurants/map` 은 프리미엄 전용입니다. k-skill-proxy 에 `BLUE_RIBBON_SESSION_ID` 가 설정되어 있어야 합니다 (30일마다 갱신).
- 검색 페이지의 zone 목록이 바뀌면 매칭 결과도 바뀔 수 있습니다.
- 좌표 없이 너무 넓은 지역명만 받으면 상권 후보가 많아질 수 있습니다.