blue-ribbon-nearby

Blue Ribbon Nearby

このスキルでできること

ユーザーから伝えられた現在地を基準に、ブルーリボン・サーベイの公式ゾーンを特定し、k-skill-proxy 経由で近くのブルーリボン掲載店を表示します。

• 位置情報を自動で推測することはありません。
• 必ず最初に現在地を尋ねます。
• 位置情報の文字列を公式の zone 一覧と照合し、周辺の JSON エンドポイントで絞り込んで検索します。
• 座標を直接受け取ると、より正確な近隣検索ができます。
• 近隣検索は、基本的に k-skill-proxy（/v1/blue-ribbon/nearby）を経由します。プロキシに BLUE_RIBBON_SESSION_ID が設定されている必要があります。

使用する場面

• 「近くのお店を探して」
• 「この近くにブルーリボン掲載店はある？」
• 「光化門付近のおすすめレストランを教えて」
• 「近くのブルーリボン掲載店だけ見せて」

振り分けルール

• ユーザーがおいしいお店／近くの飲食店／近くのレストランを尋ねた場合は、基本的に最初にこのスキルを検討します。
• ただし、ユーザーがブルーリボン以外の基準（例：マンゴープレート、Naver Map のレビュー、特定の飲食店の予約）を明示した場合は、そのサービスを優先します。

前提条件

• インターネット接続
• node 18+
• このリポジトリの blue-ribbon-nearby package または同じロジック

最初に必ず尋ねること

位置情報を聞かずに検索を開始せず、必ず最初に尋ねます。

• 推奨する質問：現在地を教えてください。町名／駅名／ランドマーク／緯度・経度のうち、入力しやすい形式で送っていただければ、近くのブルーリボン掲載店を探します。
• 位置情報が曖昧な場合：最寄り駅名か町名をもう一度教えてください。
• 座標を受け取った場合は、そのまま近隣検索に使用します。

受け付ける位置情報

• 町名／商業エリア：聖水洞、光化門、板橋
• 駅名／ランドマーク：江南駅、ソウル駅、COEX
• 緯度・経度：37.573713, 126.978338

ランドマークは、内部のエイリアスを使って最も近い公式 Blue Ribbon ゾーン名に対応付けます。例：COEX → 三成洞/大峙洞

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 のバウンディングボックスを使用します。

ワークフロー

1. 最初に現在地を尋ねる

位置情報を尋ねていない状態で検索を開始しません。

2. 位置情報を特定する

• 町名／駅名／ランドマークを受け取ったら、まず公式の https://www.bluer.co.kr/search/zone 一覧と照合します。
• COEX のように公式ゾーン名ではない代表的なランドマークは、まず最も近い公式ゾーンのエイリアスに対応付けます。
• 緯度・経度を受け取った場合は、座標に基づく近隣検索に進みます。
• 有力なゾーン候補が複数ある場合は、2～3 件だけ提示して確認を求めます。

3. 近隣の Blue Ribbon エンドポイントに問い合わせる

基本的に k-skill-proxy 経由で近隣の検索結果を取得します。

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

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

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

内部ではゾーンを照合した後、プロキシの /v1/blue-ribbon/nearby に座標と距離を渡します。プロキシはプレミアムセッションを使って Blue Ribbon の upstream を呼び出します。

直接呼び出す必要がある場合は、useDirectApi: true オプションを使用できますが、プレミアムセッションがないと premium_required エラーが発生します。

4. 飲食店の概要を簡潔に回答する

通常は 3～5 件だけ簡潔にまとめます。

• 店名
• リボンの数
• 主な料理のカテゴリー
• 住所
• 距離

完了条件

• ユーザーの現在地を最初に確認している。
• 公式の Blue Ribbon 近隣検索結果を 1 件以上見つけている。または、プロキシが未設定などの理由で結果を取得できないことを説明し、次の質問を提示している。
• 結果を距離順に簡潔にまとめている。

ブラウザーによるフォールバック（ボットブロックの回避）

bluer.co.kr が自動化アクセスをブロック（403）した場合、rebrowser-playwright がインストールされていれば、実際の Chrome ブラウザーを使って自動的にフォールバックします。

条件

• rebrowser-playwright がインストールされていること：npm install rebrowser-playwright
• Google Chrome がシステムにインストールされていること
• headed モードで動作すること（ディスプレイ環境が必要）

動作の仕組み

1. 既存の fetch リクエストが 403 を返すと、自動的にブラウザーによるフォールバックを有効化
2. ステルスパッチを適用（webdriver の削除、plugins/languages のスプーフィングなど）
3. 実際の Chrome でゾーン一覧または近隣 API を呼び出す
4. 結果を既存のパイプラインにそのまま渡す

追加設定は不要で、rebrowser-playwright をインストールするだけで自動的に動作します。インストールされていない場合は、従来どおり 403 エラーをそのまま返します。

失敗する場合

• 位置情報の文字列を公式ゾーンとうまく照合できないことがあります。
• 同じキーワードが複数の商業エリアに該当する場合は、追加の確認が必要です。
• Blue Ribbon サイトの構造やパラメーターが変更されると、ゾーンの解析または近隣エンドポイントが動作しなくなることがあります。
• プロキシの BLUE_RIBBON_SESSION_ID の有効期限（30 日）が切れた場合は、更新が必要です。
• ブラウザーによるフォールバックは headed モード専用のため、サーバー（CI）環境では動作しません。

注意事項

• このスキルは情報を検索するためのスキルです。
• ユーザーの位置情報を自動追跡せず、会話中に受け取った値のみを使用します。
• 飲食店について尋ねられた場合は基本的に最初にこのスキルを使いますが、ブルーリボン以外の基準が明示されている場合は、その基準を優先します。