留学カウンセリングAI チャットボット

留学を検討している日本語ユーザー向けの、AIカウンセリング・チャットボットです。 単なるFAQボットではなく、対話を通じてユーザーの目的・潜在ニーズを引き出し、構造化された「カルテ」を裏で自動生成します。

• 中立性を重視: 留学を勧めることをゴールにせず、「今は行かない」という選択も一緒に検討します。
• お金は預かりません: 学費等の決済・預かりは行いません。
• HPへの埋め込みを前提に設計されています（詳細は後述）。

詳細仕様は docs/SPEC.md を参照してください。

---

技術スタック

• Next.js（App Router）+ TypeScript
• Tailwind CSS
• Anthropic API（@anthropic-ai/sdk）

---

セットアップ

1. 依存パッケージのインストール

npm install

2. 環境変数の設定

.env.example を .env.local にコピーし、Anthropic Console で発行したAPIキーを設定してください。

cp .env.example .env.local

# .env.local
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx

# 使用モデル（任意。未指定なら既定で claude-opus-4-8 を使用）
ANTHROPIC_MODEL=

.env.local は .gitignore 対象です。本物のAPIキーは .env.local にのみ書き、.env.example には絶対に書かないでください。

3. 開発サーバーの起動

npm run dev

• チャット単体の画面: http://localhost:3000/widget
• トップページ（/）は現時点ではプレースホルダーです。

開発モード（NODE_ENV !== "production"）では、チャット画面内に「開発用: カルテを表示」という折りたたみパネルが表示され、裏で更新されているカルテ（構造化データ）の中身をリアルタイムに確認できます。

---

ディレクトリ構成

/app
  page.tsx                … トップページ（プレースホルダー、規約リンクあり）
  /widget/page.tsx         … 埋め込み用チャット画面（本体）
  /terms/page.tsx          … 利用規約
  /privacy/page.tsx        … プライバシーポリシー
  /api/chat/route.ts       … Anthropicへのストリーミング応答
  /api/karte/route.ts      … カルテ（構造化データ）の差分抽出
  /api/places/details/route.ts … Place Details (New) のサーバー側プロキシ（結果は保存しない）
  /api/places/nearby/route.ts  … Nearby Search (New) のサーバー側プロキシ（結果は保存しない）
  /api/places/photo/route.ts   … Place Photo (New) のサーバー側プロキシ（画像は保存しない）
/components
  Chat.tsx                 … チャット本体（ストリーミング表示・送信中表示・エラー処理）
  Message.tsx              … 発言バブル
  KarteSummary.tsx          … 会話の区切りで表示するカルテ要約・確認UI
  KarteDebugPanel.tsx        … 開発用のカルテ生データ表示パネル
  EmbedCloseButton.tsx       … 埋め込み（iframe）時のみ表示される閉じるボタン
  GoogleAttribution.tsx      … Google Places/Maps 利用時の帰属表示（共通）
  PlaceRatingBadge.tsx       … 評価点+件数+Googleマップへのリンクのみの口コミ表示
  SchoolMap.tsx              … Maps JavaScript APIでの地図表示
  AddressAutocomplete.tsx    … Autocomplete (New) を使った住所入力補完
/lib
  anthropic.ts             … Anthropicクライアント初期化・モデル設定
  prompt.ts                … システムプロンプト・update_karteツール定義
  karte.ts                 … カルテの型・差分マージ
  chat.ts                  … チャットメッセージの型・共通バリデーション
  knowledge.ts              … 知識ベース本文の生成（data/cities.ts から文章を組み立てる。数値は直書きしない）
  googlePlaces.ts            … サーバー側 Places API 共有ヘルパー（サーバー専用キーのみ使用）
  googleMapsBrowserLoader.ts … ブラウザ側 Maps JS API 共有ローダー（ブラウザ用キーのみ使用）
  data/cities.ts             … 都市別 生活費データ（構造化データの唯一の出所）
  data/schools.ts             … 学校データ（country/city/name/address + placeId等。Places本文は持たない）
/scripts
  resolve-place-ids.ts       … 【開発時ローカル実行専用】schools.ts の name+address から
                                 placeId/lat/lngを解決し書き戻す。DB・Admin APIは無い。
/public
  embed.js                … HP設置用ローダースクリプト
/embed-test
  index.html               … 埋め込み動作確認用の簡易HTML（別ドメイン想定）

---

知識ベースの生活費データ（運用ルール）

システムプロンプトに埋め込まれる都市別の生活費（家賃・食費・交通費など）は、lib/data/cities.ts が唯一の数値の出所です。lib/knowledge.ts はこのデータから説明文を生成するだけで、数値を直書きしません。

数値を更新するとき

1. lib/data/cities.ts の該当レコード（AUSTRALIA_CITIES の1要素）を編集する。
2. source / sourceUrl を実際に数値を取得した出所に更新する。
3. fetchedAt（取得日）を更新する。
4. 一次情報（政府・州政府・大学等の公式サイト）から直接取得できた場合は confidence: "official"、そこに到達できず二次情報源に頼った場合は confidence: "secondary" とし、notes にその旨を書く。secondary のレコードは次回更新時に一次情報での再確認を優先すること。

DBは使わず、このファイルへの直接編集のみで完結する（このリポジトリにDBは無い）。

データソースに関する制約（必ず守ること）

Numbeo のデータは、スクレイピングはもちろん、手入力で転記した数値であっても使用しないこと。 Numbeo は利用規約上、データの商用利用をデータライセンス契約者に限定しており、この制限は「手入力かどうか」とは関係なく、値そのものに対してかかる。このボットは商用サービスであるため、Numbeo由来の数値を使うと利用規約違反になる。

数値を入力してよい出所は次のいずれかのみ：

• (a) 公的統計・公式サイトの自前監修データ: 各国政府・州政府・大学等が公開している数値（例: オーストラリア内務省の学生ビザ資金要件、州政府の留学生向け公式サイト、大学公式サイトの生活費ガイド、各国統計局の賃金統計など）。
• (b) Numbeo の API / Data License を契約して得た数値: 契約範囲内であれば使用可能。契約していない場合は (a) のみを使うこと。

これはコードでは強制できないため、データを追加・更新する人が上記ルールを守る運用上の約束事とする。

例外は開発・検証専用の snapshot だけ: 上記の禁止は「ユーザーに届くデータ」に対するもの。回答品質の確認のために、人間がブラウザで一度確認した数値を開発環境でのみ参照する経路だけは、下記「開発・検証専用の都市指数 snapshot」の条件下で認める。production で使うには (b) のライセンス確認が必要で、「一度手入力したから production でも使える」とは扱わない。

---

都市リファレンス（治安・生活費・交通）の運用ルール

Chat が「シドニーって安全？」「メルボルンの生活費は高い？」のように都市について聞かれたときだけ参照する、人間が出典を確認して蓄積する都市情報のレイヤー。将来の I'm ready! Guide / City Guide でも同じデータを使う。

• DB: city_reference_data（1都市 × 1カテゴリ = 1行）＋ city_reference_sources（1行に複数の出典）。カテゴリは safety / housing / food / transport / utilities / everyday。
• 独自スコアを作らない。「Safety Index」「生活費指数」のような合成指標は持たず、カテゴリごとの短い要約＋出典として持つ。
• 自動取得しない。クローラー・スクレイピング・外部 API 連携は持たない。第三者サイトの無断スクレイピングもしない。
• 使ってよい出典は、公的統計（ABS 等）・州警察・州の犯罪統計機関・政府の留学情報（Study Australia 等）・公共交通機関の公式情報・大学公式の生活費ガイドのみ。出典不明のブログ・SEO 記事・Reddit・個人 SNS・Numbeo・利用規約が不明な第三者 DB は使わない。
• reviewed_at（こちらが最後に人間で確認した日）は必須。出典側の更新日が分からなければ null のままにする（不明な日付を作らない）。
• 出典が1件も無い要約は登録しない。金額は出典ごとに details.estimates へ分けて持ち、複数の出典を平均しない。
• 州をまたぐ犯罪統計は集計機関・罪種の定義・公表期間が違うため、Chat には「単純比較はできない」と伝えさせる（判定は lib/cityReference.ts の isSafetyComparable）。

データを追加・更新するとき

1. data/cities/australia/_template.json をコピーして data/cities/australia/<city>.json を作る（_ 始まりのファイルは取り込み対象外）。
2. 公的な出典を実際に開いて確認し、要約・補足・estimates・sources・reviewed_at を記入する。未確認のまま推測で埋めない（確認できていない都市は未登録のままでよい）。
3. npx tsx scripts/import-city-reference-data.ts を実行する。検証に通った entry だけの SQL が supabase/seed/city_reference_data.generated.sql に出る（テンプレートの未記入文・出典なしの entry は自動で除外される）。
4. 生成された SQL を目で確認し、Supabase の SQL エディタで適用する。スクリプトは DB へ直接書き込まない（このプロジェクトは service role key を使わないため）。

読み取りは sanitized view（city_reference_public / city_reference_sources_public）だけを公開経路にしている。base table は anon / authenticated から一切読めず、内部メモ（review_note）は view に含めない。

---

ビザ・手続き情報の運用ルール

Chat が「学生ビザで何時間働ける？」「セカンドってどう取るの？」のように聞かれたときだけ参照する、人間が公式情報を確認して蓄積するビザ情報のレイヤー。

This is the beginning of the README. Read the rest at the original. Read the full README ↗