起動フロー（Splash / Bootstrap） Bootstrap flow (Splash)

1. 設計方針 1. Design principles

1.1 なぜ集約 endpoint に混ぜないか 1.1 Why not merge into one endpoint

1.2 静的 UI 文言 vs 動的コンテンツ 1.2 Static UI strings vs. dynamic content

「画面内に表示される動的文言」はサーバ側で解決して ViewEnvelope.data に直書きする。 一方で、ボタンラベル・フォームバリデーションメッセージ・汎用エラー文言など 静的 UI 文言 は 画面に依存せず、全画面で再利用されるため、i18n_messages テーブル由来の bundle を client 側にキャッシュして使う。

"Dynamic text that appears inside a screen" is resolved server-side and written directly into ViewEnvelope.data. Static UI strings — button labels, form validation messages, generic error copy — are screen-agnostic and reused across the app, so they are served from the i18n_messages table as a bundle that the client caches locally.

2. Splash での並列 fetch フロー 2. Parallel fetch flow on Splash

2.1 ステップ詳細 2.1 Step-by-step

1. ローカルキャッシュ読み込み：SharedPreferences / Hive から直近の i18n_version・i18n_messages・codes を復元。オフライン起動の安全網にもなる。
2. Read local cache: restore last-known i18n_version, i18n_messages, and codes from SharedPreferences / Hive. Also acts as a safety net for offline launches.
3. 2 本の並列 fetch：Future.wait([boot, bundle])。bundle 側は If-None-Match: "<cached_version>" を必ず付与する。
4. Issue 2 parallel fetches: Future.wait([boot, bundle]). The bundle call must send If-None-Match: "<cached_version>".
5. reconcile：boot.data.i18n.version と、bundle 応答から得た version を突き合わせる。異なる場合は server 側で短時間に更新があったケースなので、boot 側の version を正（最新）とみなし、次回起動時に再取得する。
6. Reconcile: compare boot.data.i18n.version with the version returned by the bundle call. A mismatch means the server was updated between the two calls; treat boot's value as authoritative and re-fetch on next launch.
7. キャッシュ書き込み：bundle が 304 なら touch のみ（TTL 更新）、200 なら新 messages + version を保存。
8. Write cache: on 304 just bump the TTL; on 200 persist the new messages and version.
9. ルーティング：boot.navigation.target に従って /main / /force_update / /onboarding へ遷移。
10. Route: follow boot.navigation.target to /main / /force_update / /onboarding.

3. エンドポイント仕様 3. Endpoint specs

3.1 GET /v1/mobile/views/boot（集約） 3.1 GET /v1/mobile/views/boot (aggregate)

ViewEnvelope 形式で me / codes / app_config / i18n を返す。 data.i18n.version は i18n bundle の変更検知キー で、bundle 本体は同梱しない。

Returns me / codes / app_config / i18n inside a ViewEnvelope. data.i18n.version is the cache invalidation key for the i18n bundle; the bundle itself is not included.

{
  "data": {
    "me":   { "user_id": "<uuid>", "email": null, "app_user": { ... } },
    "codes": [ { "category_id": "vehicle_type", "code": "sedan", "display_label": "セダン", "sort_order": 1 }, ... ],
    "app_config": { "mapbox_token": "...", "feature_X_enabled": true },
    "i18n": {
      "lang": "ja",
      "version": "d41d8cd98f00b204e9800998ecf8427e"
    }
  },
  "ui_config": { "feature_flags": { ... } },
  "navigation": { "target": "home", "strategy": "replace" },
  "fallback_behavior": { ... },
  "meta": {
    "server_time": "2026-04-24T10:00:00Z",
    "cache_key": null,
    "min_app_version": "1.0.0",
    "sunset_date": null
  }
}

認証は Bearer JWT が必須。X-App-Version ヘッダを付けると min_app_version と比較して navigation.target: "force_update" が返ることがある。

Requires a Bearer JWT. If the optional X-App-Version header is below min_app_version the server may return navigation.target: "force_update".

3.2 GET /v1/mobile/i18n/bundle（辞書本体） 3.2 GET /v1/mobile/i18n/bundle (dictionary body)

認証不要（login 前の welcome 画面からも叩けるように）。?lang=ja|en（未指定時 ja）。 If-None-Match で ETag を送ると、変更なしなら 304 Not Modified。

Unauthenticated (callable from the pre-login welcome screen). ?lang=ja|en (default ja). Send If-None-Match with the cached ETag; the server returns 304 Not Modified when unchanged.

GET /v1/mobile/i18n/bundle?lang=ja
If-None-Match: "d41d8cd98f00b204e9800998ecf8427e"

--- unchanged ---
HTTP/1.1 304 Not Modified
ETag: "d41d8cd98f00b204e9800998ecf8427e"

--- changed ---
HTTP/1.1 200 OK
ETag: "<new_version>"
Cache-Control: max-age=0, must-revalidate

{
  "lang": "ja",
  "version": "<new_version>",
  "updatedAt": "2026-04-24T10:00:00Z",
  "messages": {
    "common.save": "保存",
    "common.cancel": "キャンセル",
    "auth.welcome_message": "Parky へようこそ",
    ...
  }
}

3.3 リクエスト相関表 3.3 Request correlation

4. クライアントキャッシュ戦略 4. Client cache strategy

5. 辞書更新の伝播 5. Propagation of dictionary updates

管理者が Admin Portal（/i18n-messages）で辞書を編集すると、 i18n_messages.updated_at が変化し、md5(string_agg(key || ':' || value || ':' || epoch)) で計算される bundle version も変わる。次に client が Splash に到達したタイミングで、 boot.data.i18n.version が手元キャッシュと不一致になり、自動的に bundle を再取得する。

When an admin edits entries via Admin Portal (/i18n-messages), i18n_messages.updated_at changes and the bundle version (md5(string_agg(key || ':' || value || ':' || epoch))) rolls over. On the next Splash, boot.data.i18n.version diverges from the cached one and the client auto-fetches the new bundle.

つまり 「管理者が編集すれば次回起動で勝手に追従する」 がデフォルト挙動。強制配信（push）は現状不要。 緊急反映が必要な場合は、アプリ側 foreground 復帰時にも Splash と同じ fetch を走らせる実装を検討する（将来拡張）。

So the default behaviour is "admin edits will pick up on the next launch automatically"; no push delivery needed for now. If urgent propagation is needed, a future enhancement can re-run the same fetch when the app returns to foreground.

6. エラー・エッジケース 6. Errors & edge cases

7. 管理フロー（参考） 7. Admin flow (reference)

辞書の CRUD は Admin Portal 側で提供される。bundle 配信フローとは別系統。

Dictionary CRUD lives in the Admin Portal and is decoupled from bundle delivery.

7.5 Splash 後のルーティング判定 7.5 Splash routing decision

SplashController は boot 結果と ローカル Supabase session + OnboardingPrefs.hasSeen() を組み合わせて 次の画面を決める。BFF の navigation.target は強いヒントだが、auth 判定は端末側 session を正とする （BFF 不調で「サインイン済みユーザーが毎回サインインに飛ぶ」事故を防ぐため）。

SplashController combines the boot response with the local Supabase session and OnboardingPrefs.hasSeen() to decide the next screen. The BFF's navigation.target is a strong hint, but auth is judged from the on-device session (so a BFF outage cannot bounce signed-in users back to sign-in).

Onboarding 既読フラグの遡及付与: ログイン履歴がある端末では OnboardingPrefs.markSeen() を遡って true にする （ログアウト後の再起動でオンボーディングが再表示されるのを防止）。

Retroactive onboarding-seen flag: For devices that have ever signed in, OnboardingPrefs.markSeen() is back-filled to true so the onboarding tour does not re-appear after a sign-out + relaunch.

8. 関連ファイル 8. Related files

• api/src/bff/mobile/legacy/boot.ts — boot endpoint 本体（ViewEnvelope 整形、deprecated 2026-07-31）boot endpoint handler (ViewEnvelope shaping; deprecated 2026-07-31)
• mobileapp/prototype/flutter/lib/features/splash/application/splash_controller.dart — Flutter 側 Splash オーケストレータ（local session 判定 + boot fetch + onboarding 遡及付与）Flutter splash orchestrator (local-session check, boot fetch, retroactive onboarding-seen)
• api/src/core/mobile-boot/index.ts — fetchBootData（並列 SQL + i18n summary 合流）fetchBootData (parallel SQL + i18n summary)
• api/src/core/i18n/get-bundle.ts — bundle 取得 use case + ETag 判定bundle use case + ETag matching
• api/src/data/i18n-messages.data.ts — SQL（bundle 本体 / summary / admin CRUD）SQL (bundle body / summary / admin CRUD)
• api/src/bff/mobile/views/i18n-bundle.ts — bundle endpoint（If-None-Match → 304 / 200）bundle endpoint (If-None-Match → 304 / 200)
• api/src/bff/admin/i18n-messages.ts — admin CRUD endpointadmin CRUD endpoint
• infra/supabase/migrations/20260423050000_i18n_messages.sql — テーブル定義Table definition