BFF だけを叩く。OpenAPI は openapi-app-mobile.json。 Talk only to the BFF. OpenAPI lives at openapi-app-mobile.json.

OpenAPI — 読むべきはこの 1 ファイル OpenAPI — this one file is enough

認証フロー（完結版） Authentication flow (end-to-end)

Parky は Supabase Auth によるメール + パスワード認証を採用します。 モバイル側は supabase_flutter SDK でトークン取得／更新のみ行い、 API 呼び出しには取得した JWT を Authorization: Bearer ヘッダに載せて Parky BFF に送ります。

Parky uses Supabase Auth (email + password). The mobile app uses supabase_flutter only to obtain / refresh the JWT; every BFF call then attaches that JWT as Authorization: Bearer.

① 起動時 — トークン復旧とセッション確認 1. On launch — restore session and verify

sequenceDiagram
  participant App as Flutter App
  participant Keystore as Secure Storage
(Keychain / Keystore)
  participant SbAuth as Supabase Auth
  participant BFF as Parky BFF (/v1/*)

  App->>Keystore: read refresh_token
  alt no token
    App->>App: show Sign in screen
  else has token
    App->>SbAuth: POST /token?grant_type=refresh_token
    SbAuth-->>App: { access_token, refresh_token, expires_in }
    App->>Keystore: save tokens
    App->>BFF: GET /v1/me
Authorization: Bearer 
    BFF-->>App: 200 OK { user }
    App->>App: navigate to Home
  end

② 401 受信時 — refresh → 自動再試行 2. On 401 — refresh, then retry once

sequenceDiagram
  participant App as Flutter App
  participant SbAuth as Supabase Auth
  participant BFF as Parky BFF

  App->>BFF: GET /v1/parking-lots?near=...
Authorization: Bearer 
  BFF-->>App: 401 { error.code: "unauthorized" }
  App->>SbAuth: POST /token?grant_type=refresh_token
  alt refresh OK
    SbAuth-->>App: { access_token }
    App->>BFF: retry GET /v1/parking-lots
Authorization: Bearer 
    BFF-->>App: 200 OK { items }
  else refresh failed
    SbAuth-->>App: 400 invalid_grant
    App->>App: clear session, navigate to Sign in
  end

③ ログアウト／退会 3. Logout / account deletion

• ログアウト：supabase.auth.signOut() → 端末側のトークン破棄 → Sign in 画面へ
• Logout: supabase.auth.signOut() → clear local tokens → navigate to Sign in
• 退会：POST /v1/me/withdraw を呼ぶ（BFF が匿名化 + app_users.deleted_at を立てる） → ログアウト処理
• Account deletion: call POST /v1/me/withdraw (the BFF anonymizes and sets app_users.deleted_at) → perform logout

強制アップデート契約 Forced-update contract

サーバ側の仕様変更に追従できないクライアントを安全に締め出すため、全 API コールに バージョンヘッダを付けて BFF が強制アップデートを返せるようにします。

To keep obsolete clients from breaking, every BFF call carries a version header, and the server can force an upgrade when the client is too old.

{
  "error": {
    "code": "upgrade_required",
    "message": "このバージョンはサポート対象外です",
    "request_id": "uuid"
  },
  "required_version": "1.3.0",
  "store_url": {
    "ios":     "https://apps.apple.com/app/idXXXXXXXX",
    "android": "https://play.google.com/store/apps/details?id=jp.co.parky.app"
  }
}

横断規約 — 日時・ページネーション・エラー Cross-cutting conventions

日時フォーマット Date/time format

• すべての日時は ISO 8601 文字列、UTC オフセット付き（例: 2026-04-14T23:00:00+09:00）。
• All datetimes are ISO 8601 strings with offset (e.g. 2026-04-14T23:00:00+09:00).
• 表示上の既定タイムゾーンは Asia/Tokyo。ユーザーの端末 TZ で表示しますが、BFF とのやり取りはオフセット付き ISO 8601 に統一します。
• Display defaults to Asia/Tokyo for Parky; the device TZ is used for rendering, but the wire format is always ISO 8601 with offset.
• Unix timestamp 不使用。日付のみの場合も 2026-04-14 形式。
• Unix timestamps are not used. Date-only fields use 2026-04-14 form.

ページネーション Pagination

現状の OpenAPI は page + limit + total 方式（offset pagination）です。 モバイル側で無限スクロールを実装する場合は、下記のクライアント規約に従ってください。

The current OpenAPI uses offset pagination (page + limit + total). For infinite scroll on mobile, follow the client-side convention below.

• 初回：?page=1&limit=20 を要求
• First call: ?page=1&limit=20
• 追加取得：ユーザーのスクロール末端で page を +1
• Next: increment page when the user reaches the list end
• 終了条件：items.length < limit または page * limit >= total
• Stop when items.length < limit or page * limit >= total
• limit は API 既定（多くは 20 件）を尊重、画面別のオーバーライドは不要
• Respect the API default for limit (usually 20); no screen-specific override

エラー形式（統一） Error shape (unified)

BFF の全エンドポイントは下記形式でエラーを返します。詳細カタログは bff/errors.html。

Every BFF endpoint returns errors in this shape. The full catalog lives at bff/errors.html.

{
  "error": {
    "code": "snake_case_code",
    "message": "human readable",
    "request_id": "uuid",
    "details": { ... }
  }
}

レート制限 Rate limits

• POST /v1/search/ai（AI 検索）: 10 req / 60 s / ユーザー
• POST /v1/search/ai (AI search): 10 req / 60 s / user
• その他の /v1/* は現在ゆるい制限（数百 req/min レベル）。429 を受けたら Retry-After ヘッダで待機
• Other /v1/* endpoints have loose limits (hundreds of req/min). On 429, wait per Retry-After

ヘッダ規約（全リクエスト共通） Header conventions (on every request)

OpenAPI への追補要望（既知の欠落） Known gaps in the OpenAPI

• examples: 現在 0 件。レスポンスの具体例はフィールド定義と本ドキュメントで補完
• examples: currently 0. Use field definitions plus this document to infer
• operationId: 未設定。生成クライアントは URL 由来のメソッド名になります（必要に応じて手動リネーム可）
• operationId: not set. Generated clients will derive method names from URLs (rename by hand if needed)
• ミューテーションの 4xx スキーマ: 一部未宣言（POST /v1/storage/upload-url など）。本ページのエラー形式表を適用
• 4xx schemas on some mutations (e.g. POST /v1/storage/upload-url) are not declared — use the error shape above