ViewEnvelope ガイド（SDUI Level 3） ViewEnvelope guide (SDUI Level 3)

Parky の Mobile BFF が 全 View / Action endpoint で返す共通 JSON 構造（ViewEnvelope） の業者向け解説です。 SDUI Level 3 という設計レベルの位置付け、各セクションの役割、ETag / version の意味、 Flutter 側の実装パターン、よくある罠を実例とともに整理しています。

A vendor-oriented guide to ViewEnvelope — the shared JSON shape returned by every Mobile BFF View/Action endpoint. Covers the SDUI Level 3 design, the role of each section, the meaning of ETag and version fields, Flutter-side implementation patterns, and common pitfalls — with concrete examples.

1. SDUI Level とは 1. What is SDUI Level?

Server-Driven UI（SDUI）は「UI の何を / どこまで サーバーが駆動するか」のスペクトルです。 Parky は Level 3 で固定運用 しており、これより下も上も採用しません。

Server-Driven UI (SDUI) is a spectrum: how much of the UI does the server drive? Parky locks in at Level 3 and does not adopt levels below or above.

なぜ L3 か Why L3

• L0〜L2 は弱い: A/B テスト・段階的廃止・experiment 切替・error 振る舞い変更を全部 Flutter リリース待ちにする必要があり、リリース前期間でも判断速度が落ちる
• L0–L2 are too weak: A/B tests, deprecation, experiment toggles, error-behavior changes all wait on Flutter release cadence — slowing decisions even pre-launch
• L4〜L5 は重い: DSL を作って維持するコストが Flutter 1 名体制では割に合わない。レイアウト/インタラクションの自由度も DSL で削れてしまう
• L4–L5 are too heavy: building and maintaining a DSL isn't worth it for a 1-Flutter-dev org, and the DSL itself caps layout/interaction freedom
• L3 は中庸: Widget ツリーは Flutter で自由に書ける一方、A/B / experiment / error 規約 / バリデーション / 遷移 / 廃止予告はサーバーから動かせる
• L3 is the sweet spot: free to write any widget tree in Flutter, while server still drives A/B, experiments, error contract, validation, navigation, deprecation

2. ViewEnvelope の構造 2. ViewEnvelope structure

全 View endpoint は以下の 7 ブロック構造を返します。Action endpoint は meta が mutation_id を含む ActionMeta に拡張され、navigation が必須になる以外は同じ構造です。

Every View endpoint returns the 7-block structure below. Action endpoints use the same shape but with meta extended to ActionMeta (adds mutation_id) and navigation required.

2.1 全体構造（TypeScript 型） 2.1 Overall shape (TypeScript)

// api/src/lib/view/meta.ts
export interface ViewEnvelope<D> {
  data: D;                              // 画面固有の payload
  ui_config?: UiConfig;                 // server-side UI override
  navigation?: NavigationHint;          // 遷移指示
  validation?: ValidationRule[];        // フォーム field rule
  states?: States;                      // error / empty / skeleton
  fallback_behavior: FallbackBehavior;  // 通信エラー / auth / version の規約 (必須)
  meta: ViewMeta;                       // server_time / cache_key / min_app_version / view_spec_ref ...
}

2.2 JSON 例（mobile-home-feed） 2.2 JSON example (mobile-home-feed)

GET /v1/mobile/views/home-feed の実装は api/src/bff/mobile/legacy/home-feed.ts （routes-manifest 上で stability: 'deprecated', sunsetDate: '2026-07-31'。後継 view への分割を予定）。 サンプルレスポンスは以下のような形になります。

Implementation: api/src/bff/mobile/legacy/home-feed.ts (marked stability: 'deprecated' with sunsetDate: '2026-07-31' in routes-manifest; will be split into follow-up views). A sample response looks like this:

{
  "data": {
    "lots": [
      { "id": "5fe4...", "name": "○○タワー駐車場", "lat": 35.6586, "lng": 139.7454,
        "distance_m": 120, "status": "available" }
    ],
    "sponsors": [
      { "id": "ad9c...", "name": "△△カフェ", "lat": 35.6588, "lng": 139.7460, "distance_m": 95 }
    ],
    "active_session": null,
    "banners": [
      { "id": "b1a2...", "slot_key": "home_top", "title": "プレミアム 7 日無料",
        "subtitle": null, "image_url": "https://r2.../banner.png",
        "link_type": "deep", "link_url": "parky://premium", "display_order": 0 }
    ],
    "gamification": {
      "slot_type": "tutorial_mission",
      "missions": [{ "badge_id": "...", "name": "初回駐車", "icon": "park",
                     "description": "...", "progress_percent": 0, "threshold": 1 }],
      "earned_count": 0, "total_tutorial_count": 5
    }
  },
  "ui_config": {
    "experiment_id": "membership_arm_b",
    "highlighted_fields": ["pricing"]
  },
  "states": {
    "skeleton": { "layout": "map" },
    "error": [
      { "code": "unauthorized", "message_code": "common.error.unauthorized",
        "retryable": false, "fallback": "block" },
      { "code": "service_unavailable", "message_code": "common.error.unavailable",
        "retryable": true, "fallback": "cached" },
      { "code": "internal_error", "message_code": "common.error.internal",
        "retryable": true, "fallback": "cached" },
      { "code": "timeout", "message_code": "common.error.timeout",
        "retryable": true, "fallback": "cached" },
      { "code": "bad_request", "message_code": "common.error.bad_request",
        "retryable": false, "fallback": "block" },
      { "code": "network_unreachable", "message_code": "common.error.network_unreachable",
        "retryable": true, "fallback": "cached" }
    ]
  },
  "fallback_behavior": {
    "on_network_error": "show_cached",
    "on_auth_error": "redirect_login",
    "on_version_mismatch": "degrade",
    "cache_ttl_seconds": 60
  },
  "meta": {
    "server_time": "2026-04-30T10:00:00.000Z",
    "cache_key": "home.banners_a1b2c3d4.codes_def.feed_ef01.i18n_ghi.ui_jkl",
    "min_app_version": "1.0.0",
    "sunset_date": null,
    "expected_ui_version": "ui_2026_04_26_1547",
    "view_spec_ref": "home_feed_v1"
  }
}

3. 各セクション解説 3. Section-by-section reference

3.1 data 3.1 data

画面固有のドメインデータ。形は endpoint ごとに違い、api/src/schema/view/ 配下の Zod schema が SSoT。 Flutter 側は ViewEnvelope<T>.fromJson(json, T.fromJson) で T の decoder を渡して受け取ります。

Screen-specific domain data. Shape varies per endpoint; SSoT is the Zod schema under api/src/schema/view/. Flutter receives it via ViewEnvelope<T>.fromJson(json, T.fromJson), supplying a decoder for T.

3.2 navigation — 遷移制御 3.2 navigation — transition control

{
  "target": "lot_detail",          // 画面識別子（"none" で「現画面留まる」）
  "params": { "id": "uuid..." },   // target に渡すパラメタ
  "strategy": "push"               // push / replace / pop_to_root
}

• View envelope: optional。指定があれば「読み込み完了後に遷移」
• View envelope: optional. If present, "navigate after load completes"
• Action envelope: 必須。Action 成功後の画面遷移を駆動
• Action envelope: required. Drives the post-action transition
• "refresh current screen" は { target: "none", strategy: "replace" }（NAVIGATION_REFRESH_CURRENT 定数）
• "Refresh the current screen" is { target: "none", strategy: "replace" } (the NAVIGATION_REFRESH_CURRENT constant)

3.3 ui_config — UI パラメータ 3.3 ui_config — UI parameters

{
  "messages": { "home.title": "今日のおすすめ" },  // i18n の緊急 override（A/B 用）
  "feature_flags": { "show_map_clusters": true },
  "experiment_id": "membership_arm_b",
  "theme_hint": "auto",
  "highlighted_fields": ["pricing", "roof"]      // 検索条件にマッチした項目をハイライト
}

サーバー側で A/B テストや experiment 切り替えを動かすための層。 highlighted_fields は検索条件（料金・屋根あり 等）に合致したフィールドを Flutter 側でハイライト表示するためのヒント。

The layer the server uses to drive A/B tests and experiment toggles. highlighted_fields tells Flutter which fields to highlight (e.g. pricing, roofed) when they match the user's search criteria.

3.4 validation — フォーム field rule 3.4 validation — form field rules

[
  { "field": "email",    "rule": "required",   "message_code": "common.error.required" },
  { "field": "email",    "rule": "regex",      "param": "^[^@]+@[^@]+$",
    "message_code": "auth.error.invalid_email" },
  { "field": "password", "rule": "min_length", "param": 8,
    "message_code": "auth.error.password_too_short" }
]

• rule の種類: required / min_length / max_length / regex / numeric_range
• Rule kinds: required, min_length, max_length, regex, numeric_range
• Flutter は rule をローカル先行チェックに使い、message_code を i18n 辞書で resolve
• Flutter runs these rules locally first, then resolves message_code through the i18n dictionary
• サーバー側でも同じ rule を二重に検査するので、client は UX 改善目的の先行検査だけ
• The server validates the same rules again — the client check is only there for UX speed

3.5 states — 画面状態 3.5 states — screen states

3.5.1 states.skeleton 3.5.1 states.skeleton

{ "layout": "map", "item_count": 5 }   // layout: list / detail / map / grid / splash

loading 中に表示する shimmer skeleton のレイアウトヒント。item_count は list/grid 時の件数。

Layout hint for the shimmer skeleton shown while loading. item_count applies to list/grid layouts.

3.5.2 states.empty 3.5.2 states.empty

{
  "illustration": "empty_search",
  "title_code": "search.empty.title",
  "body_code": "search.empty.body",
  "cta": { "label_code": "search.empty.cta", "action": "open_filters" }
}

0 件結果時の empty view。CTA は null 可能。illustration は asset key（実 URL ではない）。

Empty view for zero results. CTA can be null. illustration is an asset key, not a URL.

3.5.3 states.error[] 3.5.3 states.error[]

この endpoint で 起こり得るエラー種別を事前に列挙 する層。 現在エラーが起きているわけではなく、Flutter 側が「もしこの code が来たらこう振る舞う」を準備するための定義です。

Up-front enumeration of error kinds this endpoint may emit. It's not a "current error" — it's the contract Flutter uses to prepare per-code behavior.

{
  "code": "unauthorized",
  "message_code": "common.error.unauthorized",
  "retryable": false,           // 自動 retry 可否
  "fallback": "block"           // cached / empty / block
}

• fallback: "cached" — 最後の cache を表示しつつ retry。一時障害（5xx / timeout）で使用
• fallback: "cached" — show last cache and retry. For transient failures (5xx / timeout)
• fallback: "empty" — 空 view を表示。404 系で使用
• fallback: "empty" — show empty view. For 404-style cases
• fallback: "block" — エラー画面で操作 block。auth / 入力エラー / upgrade 必要 等で使用
• fallback: "block" — show error screen and block interaction. For auth / input / upgrade-required cases

サーバー側は buildErrorStatesFromCodes([...COMMON_ERROR_CODES, "bad_request"]) のように ERROR_CATALOG から自動生成。NETWORK_UNREACHABLE_STATE は HTTP より前に検知される擬似 code として extra で追加。

Server-side, this is generated from ERROR_CATALOG via buildErrorStatesFromCodes([...COMMON_ERROR_CODES, "bad_request"]). NETWORK_UNREACHABLE_STATE is a synthetic code (detected before HTTP returns) added as extra.

3.6 fallback_behavior — エラー時の規約 3.6 fallback_behavior — failure-mode contract

{
  "on_network_error":     "show_cached",   // show_cached / show_empty / show_error
  "on_auth_error":        "redirect_login",// redirect_login / show_error
  "on_version_mismatch":  "degrade",       // force_update / degrade / ignore
  "cache_ttl_seconds":    60               // 0 = cache しない
}

画面性格別にプリセットがあり、route 側で選ぶ運用です。

There are presets per screen kind; the route picks one.

3.7 meta — 画面メタ情報 3.7 meta — envelope metadata

{
  "server_time":          "2026-04-30T10:00:00.000Z",
  "cache_key":            "home.banners_a1b2c3d4.codes_def.feed_ef01.i18n_ghi.ui_jkl",
  "min_app_version":      "1.0.0",
  "sunset_date":          null,
  "expected_ui_version":  "ui_2026_04_26_1547",
  "view_spec_ref":        "home_feed_v1",
  "realtime": {                                // optional, mobile では原則使わない
    "channel": "...",
    "event_types": ["INSERT"],
    "fallback_poll_seconds": 0
  }
}

3.8 Action envelope の追加要素 3.8 Additional Action-envelope fields

// ActionMeta = ViewMeta + mutation_id
{
  "server_time": "...",
  "cache_key": null,
  "min_app_version": "1.0.0",
  "sunset_date": null,
  "mutation_id": "9a3f5d10-..."   // サーバー採番。client は Idempotency-Key と突合可
}

Action では navigation が必須。冪等性は routes-manifest.ts の idempotent: true + Idempotency-Key middleware で保証され、 mutation_id はクライアント向け ack（toast 表示・重複検知）として使います。

For Actions, navigation is required. Idempotency is enforced by idempotent: true in routes-manifest.ts plus the Idempotency-Key middleware; mutation_id is a client-facing ack used for toast display / duplicate detection.

4. ETag / version の意味 4. ETag / version semantics

4.1 composite ETag 4.1 Composite ETag

Parky の主要 endpoint は composite ETag を採用しています。 単一の row hash ではなく、関連する複数の鮮度トークンを join した形:

Major Parky endpoints use a composite ETag — not a single row hash but a join of multiple freshness tokens:

"home.banners_a1b2c3d4.codes_def.feed_ef01.i18n_ghi.ui_jkl"
   ↑     ↑                ↑           ↑          ↑          ↑
   prefix banners snapshot codes ver  feed hash  i18n ver   ui_layer ver

client は前回の ETag を If-None-Match で送り、サーバ側 ETag と一致すれば 304 Not Modified を返します。 いずれか 1 つの token がズレれば 200 で新 envelope を返す。

The client sends the previous ETag in If-None-Match; if it matches the server's ETag, the server returns 304 Not Modified. If any single token shifts, the server returns 200 with a fresh envelope.

4.2 expected_ui_version と view_spec_ref 4.2 expected_ui_version and view_spec_ref

SDUI cache layering: /boot 集約 endpoint が ui_layer catalog（ui_version, codes, i18n, view_specs）を返し、 各 view レスポンスは meta.expected_ui_version でその catalog 版数を相乗りします。

SDUI cache layering: a /boot aggregator returns the ui_layer catalog (ui_version, codes, i18n, view_specs), and every view response carries that version through meta.expected_ui_version.

• client cache の ui_version と一致 → そのまま使う
• If the client's cached ui_version matches → use cache as-is
• 不一致 → background で /boot を再 fetch（BootRevalidator）。表示は止めない
• If mismatch → refetch /boot in background (BootRevalidator); rendering does not block
• view_spec_ref は ui_layer 内の view_specs[id] への key。Flutter は spec を cache から resolve して validation/states/fallback_behavior を取得
• view_spec_ref keys into view_specs[id] within the catalog. Flutter resolves the spec from cache to recover validation/states/fallback_behavior

将来（P4 以降）envelope の validation / states / fallback_behavior は client cache から resolve するため envelope payload を slim 化する計画です（shouldSlimEnvelope 参照）。

From P4 onward, the plan is to slim the envelope by resolving validation / states / fallback_behavior from the client cache (see shouldSlimEnvelope).

4.3 min_app_version による version mismatch 判定 4.3 Version-mismatch decisions via min_app_version

// api/src/lib/view/meta.ts
checkMinAppVersion(clientVersion, minRequired) → "ok" | "degraded" | "force_update"

• client >= required → ok
• client >= required → ok
• client < required かつ 1 major 以内 → degraded（警告のみ、画面は出す）
• client < required within 1 major → degraded (warn only, still render)
• 2 major 以上遅れ → force_update（強制アップデート画面）
• 2 majors behind or more → force_update (force-update screen)

どの挙動を取るかは fallback_behavior.on_version_mismatch がさらに上書きします（force_update / degrade / ignore）。

The actual behavior is further overridden by fallback_behavior.on_version_mismatch (force_update / degrade / ignore).

5. Flutter 側の実装パターン 5. Flutter implementation pattern

5.1 envelope → Widget の流れ 5.1 envelope → Widget flow

sequenceDiagram
  participant W as Widget
  participant C as Controller (Riverpod AsyncNotifier)
  participant R as Repository
  participant B as ParkyBffClient (dio)
  participant API as Workers BFF

  W->>C: ref.watch(homeFeedProvider)
  C->>R: fetchHomeFeed(lat, lng)
  R->>B: getHomeFeedApi.v1MobileViewsHomeFeedGet(...)
  B->>API: GET /v1/mobile/views/home-feed (If-None-Match: prev ETag, X-App-Version)
  API-->>B: 200 / 304 (with composite ETag)
  B-->>R: dio Response
  R-->>R: ViewEnvelope.fromJson(json, HomeFeedData.fromJson)
  R-->>C: AsyncValue>
  C-->>W: render data + states + nav
  W->>W: NavigationResolver.resolve(envelope.navigation)

5.2 受信コード（Dart） 5.2 Receiving code (Dart)

// prototype/flutter/lib/core/bff/view_envelope.dart
final envelope = ViewEnvelope<HomeFeedData>.fromJson(
  json,
  (raw) => HomeFeedData.fromJson(raw as Map<String, dynamic>),
);

// data 描画
return HomeMapScreen(data: envelope.data);

// navigation
final nav = envelope.navigation;
if (nav != null && nav.target != 'none') {
  context.read(navigationResolverProvider).resolve(nav);
}

// version mismatch / force update
final minVer = envelope.meta?.minAppVersion;
if (minVer != null && isOlder(currentAppVersion, minVer)) {
  // fallback_behavior.on_version_mismatch を見て判断
}

5.3 既製 helper 5.3 Built-in helpers

• core/bff/bff_client.dart — Authorization header 自動付与・ETag 管理
• core/bff/bff_client.dart — auto-injects Authorization header, manages ETag
• core/bff/envelope_consumer.dart — envelope を受け取り states/error_toast を統一処理
• core/bff/envelope_consumer.dart — common handler for states / error toast
• core/bff/navigation_resolver.dart — NavigationHint をルーターに変換
• core/bff/navigation_resolver.dart — converts NavigationHint into router actions
• core/bff/envelope_inspector.dart — debug 時の envelope 可視化
• core/bff/envelope_inspector.dart — envelope visualization for debugging
• core/sdui/boot_revalidator.dart — expected_ui_version ズレ時に /boot 再 fetch
• core/sdui/boot_revalidator.dart — refetches /boot when expected_ui_version drifts
• core/sdui/ui_layer_cache.dart — ui_layer catalog の永続 cache
• core/sdui/ui_layer_cache.dart — persistent cache for the ui_layer catalog

6. やってはいけないこと 6. What not to do

7. 参考実装（envelope の典型例） 7. Reference implementations (envelope examples)

8. 関連ドキュメント 8. Related documents

• BFF 側の正規 ViewEnvelope 仕様Canonical ViewEnvelope spec (BFF side)
• ERROR_CATALOG（全 error code）ERROR_CATALOG (all error codes)
• 業者向けオンボーディングVendor onboarding
• システム全体像・責任分界System architecture & responsibility split
• OpenAPI（Redoc）OpenAPI (Redoc)
• 画面 × API マップScreen × API map