API アーキテクチャ方針 — BFF 一本化 + SDUI Level 3 API architecture — BFF-first + Server-Driven UI Level 3

2026-04-23 に確定した Parky の API アーキテクチャ方針のまとめ。 全クライアント（モバイル / Web / 管理者・オーナー・マーケティングの各ポータル）は Cloudflare Workers 上の BFF (/v1/*) だけを叩く。 モバイルは SDUI Level 3 に固定し、 OpenAPI 契約（OAS）はチャネル別に完全分離する。

The Parky API architecture locked on 2026-04-23. Every client (mobile / web / admin / owner / marketing portals) talks only to the Cloudflare Workers BFF (/v1/*). Mobile is pinned at SDUI Level 3, and the OpenAPI contracts (OAS) are split per channel.

1. システム全景 (flow)1. System flow

Realtime 購読のみ、ROI の都合でモバイル Flutter から Supabase client 直接接続を許容する （BFF 経由 WebSocket 中継はコストに見合わない）。それ以外の読み書きはすべて BFF を経由する。

Realtime subscriptions are the single exception: mobile Flutter may open them directly via the Supabase client (proxying WebSockets through the BFF is not ROI-positive). Every other read/write goes through the BFF.

2. なぜ BFF 一本化か2. Why BFF-first

• セキュリティ境界が 1 箇所: Service Role Key / FCM 秘密 / X API Secret / Resend token の露出面を BFF に閉じ込められる。クライアントにシークレットを持たせない運用が機械的に成立する。
• Single security boundary: Service Role Key / FCM secret / X API secret / Resend token exposure is confined to the BFF. Clients simply never hold secrets.
• DB を直接触らせない: RLS を頼りにしたスキーマ晒しをやめ、BFF が必要な形に aggregate してから返す。RLS は二重防御として残す（穴が開いても DB レベルで止まる）。
• Clients never touch the DB: No more relying on RLS to safely expose raw tables — the BFF aggregates first. RLS stays as defence-in-depth (a bug at the BFF still hits a DB-level stop).
• 契約変更がサーバに閉じる: 画面/テーブル変更を BFF で吸収。旧モバイル端末向けに互換レイヤーを BFF 側で維持できる。
• Contract change stays server-side: Schema/screen changes are absorbed inside the BFF; legacy-mobile compat layers can live there too.
• Edge runtime でレイテンシ最小: Cloudflare Workers で低レイテンシ + キャッシュ + Cron + R2 が 1 プラットフォームに揃う。
• Low latency at the edge: Cloudflare Workers give us low-latency routing, caching, cron, and R2 in one platform.

3. SDUI レベル定義と L3 採用理由3. SDUI level definitions and why L3

なぜ L3: サーバー主導で振る舞い（ルール・文言・遷移・フラグ）を動的に変えたい。 ただし UI の見た目は Flutter Material / React の強みを殺したくない。L4/L5 だと自前のレンダリングエンジンを持つ羽目になり、 アニメーション・ジェスチャー・Mapbox のようなネイティブコンポーネントと噛み合わない。L3 はその中間の「運用の機動力と描画の自由度が両立する」落としどころ。

Why L3: we want the server to drive behaviour (rules, copy, navigation, flags) without losing Flutter Material / React's native-widget advantage. L4/L5 forces us to maintain a custom render engine that fights animations, gestures, and Mapbox. L3 is the midpoint where operational agility coexists with native rendering freedom.

4. ViewEnvelope の構造4. ViewEnvelope structure

/v1/mobile/views/* はすべて以下のエンベロープを返す。data / meta / fallback_behavior は必須、 その他は画面の性質に応じて任意。

Every /v1/mobile/views/* endpoint returns this envelope. data, meta, and fallback_behavior are required; the rest are optional depending on the screen.

{
  "data":              { /* screen-specific primary payload */ },
  "ui_config":         { /* messages / feature_flags / experiment_id / theme_hint */ },
  "navigation":        { "target": "...", "params": {...}, "strategy": "push|replace|pop_to_root" },
  "validation":        [ { "field": "...", "rule": "...", "param": ..., "message_code": "..." } ],
  "states":            { "error": [...], "empty": {...}, "skeleton": {...} },
  "fallback_behavior": { "on_network_error": "...", "on_auth_error": "...", "on_version_mismatch": "...", "cache_ttl_seconds": 60 },
  "meta":              { "server_time": "...", "cache_key": "...", "min_app_version": "1.4.0", "sunset_date": null, "realtime": {...} }
}

実装ヘルパーは lib/view-envelope.ts の buildViewEnvelope() / buildErrorStatesFromCodes() / resolveClientFeatureFlags()。 states.error は ERROR_CATALOG + ERROR_MESSAGE_KEYS から自動派生させること（手書き禁止）。

The implementation lives in lib/view-envelope.ts: buildViewEnvelope(), buildErrorStatesFromCodes(), resolveClientFeatureFlags(). Never hand-write states.error; always derive it from ERROR_CATALOG + ERROR_MESSAGE_KEYS.

5. ActionEnvelope の構造5. ActionEnvelope structure

mutation endpoint（/v1/mobile/actions/*）が返すレスポンス契約。α 型: 成功時に「次に描画すべき View の data」を同梱することで、クライアントは再 fetch せずに即描画する。

Mutation endpoint (/v1/mobile/actions/*) response contract. α variant: the response already carries the next view's data so the client can re-render without an extra fetch.

{
  "result":      { /* 操作結果 / next-view data */ },
  "navigation":  { "target": "parking_detail|none", "params": {...}, "strategy": "push|replace|pop_to_root" },
  "toast":       { "kind": "success|error", "message_code": "..." },
  "meta":        { "request_id": "...", "server_time": "...", "mutation_id": "uuid" }
}

• navigation は必須。同画面再描画は NAVIGATION_REFRESH_CURRENT（{target:"none", strategy:"replace"}）。
• navigation is required. Re-rendering the current screen uses NAVIGATION_REFRESH_CURRENT ({target:"none", strategy:"replace"}).
• Idempotency: routes-manifest の idempotent: true で Idempotency-Key ヘッダを必須化。meta.mutation_id はサーバー採番の ack key。
• Idempotency: set idempotent: true in routes-manifest to require the Idempotency-Key header. meta.mutation_id is a server-issued ack key.

6. TelemetryAck の構造6. TelemetryAck structure

画面に紐付かない fire-and-forget 記録系（geofence 進入 / 位置テレメトリ / push 受信記録）のレスポンス契約。UI に影響しないので軽量 ack のみ。

Response contract for fire-and-forget telemetry endpoints (geofence entries / location telemetry / push receipt logs). UI-independent, so we ship only a lightweight ack.

{
  "ack":  true,
  "meta": { "request_id": "...", "received_at": "...", "event_id": "uuid" }
}

クライアントは ack を待たず処理継続してよい。Idempotency-Key は必須（重複記録防止）。

The client may proceed without awaiting the ack. Idempotency-Key is mandatory to prevent duplicate records.

7. チャネル別 OAS と API surface 境界7. Per-channel OAS and API surface boundaries

OpenAPI はチャネル別に完全分離して 5 ファイルで運用する。1 本の巨大 OAS は誰のためにもならない。

OAS is fully split per channel into 5 files. One giant OAS serves nobody.

モバイルは resource API を叩かない。/v1/mobile/{views,actions,telemetry}/* の 3 surface だけで完結させる。 旧 /v1/mobile/boot / /v1/mobile/home-feed / /v1/mobile/lots/<id> 等の thin wrapper は Sunset ヘッダ付きで 2026-07-31 まで並走、その後 410 Gone。

Mobile does not hit resource APIs. It is closed under the 3 surfaces /v1/mobile/{views,actions,telemetry}/*. Legacy paths (/v1/mobile/boot, /v1/mobile/home-feed, /v1/mobile/lots/<id>, …) run alongside with Sunset headers until 2026-07-31, then return 410 Gone.

8. 責任分界点8. Responsibility boundaries

9. 契約バージョニング9. Contract versioning

• X-App-Version ヘッダはすべての /v1/* で必須。セマンティックバージョン（MAJOR.MINOR.PATCH）。
• X-App-Version is required on every /v1/* call. Semantic version (MAJOR.MINOR.PATCH).
• BFF は meta.min_app_version と照合し、古ければ fallback_behavior.on_version_mismatch で挙動指示: force_update / degrade / ignore。
• The BFF compares against meta.min_app_version and directs behaviour via fallback_behavior.on_version_mismatch: force_update / degrade / ignore.
• 互換不可変更時は HTTP 426 Upgrade Required を返し、クライアントは強制アップデートモーダルを表示する。
• On incompatible changes the BFF returns HTTP 426 Upgrade Required and the client shows a force-update modal.
• OpenAPI の info.version は api/package.json と同期させる（contracts ワークフローで lock）。
• OpenAPI info.version stays in sync with api/package.json (locked by the contracts workflow).
• sunset_date が設定された View はその日以降停止。クライアントは次回起動時にアップデート導線を提示する。
• Views carrying sunset_date stop being served after that date. Clients should surface an update prompt on next launch.

10. 関連ドキュメント10. Related docs

• 画面 × API マップScreen × API map
• モバイル / 責任分界詳細Mobile / responsibility detail
• BFF / エラー契約BFF / error contract
• OpenAPI 契約同期OpenAPI contract sync
• BFF / API 目次BFF / API index
• Swagger UI / Redoc
• root / アーキテクチャRoot / Architecture
• コード規約 / Layer-FirstCode conventions / Layer-First