MileTrek 設計書

Appearance

API 一覧 ​

ベースURL ​

http://localhost:3000/api/v1

エンドポイント一覧 ​

認証 ​

メソッドパス説明
POST/auth/registerユーザー登録
POST/auth/loginログイン
GET/auth/me現在のユーザー情報取得

マイル管理 ​

メソッドパス説明
GET/miles/balanceマイル残高取得
PUT/miles/balanceマイル残高更新
GET/miles/chartマイルチャート取得
GET/miles/chart/:airline航空会社別チャート

検索 ​

メソッドパス説明
GET/search/destinations目的地検索
GET/search/recommendレコメンド検索
GET/search/season-mapシーズン別マップ
GET/search/availabilityフライト空席カレンダー (origin, destination, year, month)

ホテル ​

メソッドパス説明
GET/hotels目的地のホテル一覧 (destination)

宿泊検索（レガシー） ​

メソッドパス説明
GET/accommodation/search宿泊横断検索
GET/accommodation/compare同一ホテル比較

グルメ ​

メソッドパス説明
GET/gourmetレストラン一覧 (region, cuisine オプション)
GET/gourmet/:idレストラン詳細 + 近隣レストラン
GET/gourmet/bookmarksログインユーザーのブックマーク一覧 🔒
POST/gourmet/bookmarks/:restaurantIdブックマーク追加 🔒
DELETE/gourmet/bookmarks/:restaurantIdブックマーク削除 🔒

キャンペーン ​

メソッドパス説明
GET/campaigns航空会社キャンペーン一覧 (airline, active オプション)

旅行プラン ​

メソッドパス説明
GET/tripsプラン一覧取得
POST/tripsプラン作成
GET/trips/:idプラン詳細取得
PUT/trips/:idプラン更新
DELETE/trips/:idプラン削除
POST/trips/:id/flightsフライト追加
POST/trips/:id/accommodations宿泊追加
POST/trips/:id/itinerary日程アイテム追加

マスタデータ ​

メソッドパス説明
GET/airports空港一覧
GET/airports/origins出発便がある空港のみ抽出（出発空港セレクタ用）
GET/airports/:code空港詳細
GET/seasons/:airlineシーズン定義

🔒 マークのエンドポイントは JWT 認証が必須です。

認証 ​

JWT Bearer トークンを Authorization ヘッダーに設定。

Authorization: Bearer <token>

レスポンス形式 ​

成功時 ​

json
{
  "success": true,
  "data": { ... }
}

エラー時 ​

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "出発空港を指定してください"
  }
}

エラーコード ​

コードHTTPステータス説明
UNAUTHORIZED401認証が必要
FORBIDDEN403権限なし
NOT_FOUND404リソースが見つからない
VALIDATION_ERROR400バリデーションエラー
EXTERNAL_API_ERROR502外部API呼び出し失敗
INTERNAL_ERROR500サーバー内部エラー