開発者ガイド（Flutter モバイル） Developer guide (Flutter mobile)

Parky モバイルアプリ（Flutter）にコミットする開発者が最初に読むページです。 ローカル起動から BFF 呼び出し、Auth / Realtime / Push / 地図 / テスト / CI までを網羅的に解説します。 個別 API の詳細は Swagger UI / Redoc を参照してください。

The page every developer touching the Parky mobile app (Flutter) should read first. It walks through local setup, BFF calls, Auth / Realtime / Push / maps / testing / CI end-to-end. For per-route details see Swagger UI / Redoc.

技術スタック（確定版）Stack (what we actually use)

ディレクトリ構成Directory layout

mobileapp/prototype/flutter/
├── pubspec.yaml              # 依存固定（バージョン範囲は最小に保つ）
├── lib/
│   ├── main.dart             # エントリ: Supabase.initialize → runApp(ParkyApp)
│   ├── app.dart              # MaterialApp + go_router のルートテーブル
│   ├── config/               # 環境変数の読み込み、エンドポイント定義
│   ├── theme/                # カラー・タイポグラフィ・InputDecoration の共通化
│   ├── models/               # API レスポンスを受ける data class
│   ├── data/                 # BFF を叩くリポジトリ層（http + json serialize）
│   ├── domain/               # 画面が消費する純粋ロジック（計算・変換）
│   ├── widgets/              # 再利用パーツ（カード、ボタン、フォーム）
│   ├── screens/              # 画面単位ディレクトリ (1 画面 = 1 ディレクトリ)
│   └── utils/                # 日付・URL・エラー整形等の共通ヘルパー
├── assets/                   # 同梱画像・フォント・JSON (pubspec の flutter.assets に列挙)
├── android/ ios/ web/        # プラットフォーム固有設定
└── test/                     # widget / unit テスト

ローカル起動Local setup

1. Flutter インストール: fvm 推奨。ルート直下の .fvmrc（なければ stable）に合わせる。
2. Install Flutter: we recommend fvm; follow .fvmrc (fall back to stable if missing).
3. 依存解決: cd mobileapp/prototype/flutter && flutter pub get
4. Install deps: cd mobileapp/prototype/flutter && flutter pub get
5. 環境変数: run 時に --dart-define で渡す（次セクション 参照）。
6. Env vars: pass via --dart-define at run time (see next section).
7. 起動: 下の "よく使う flutter コマンド" を参照。
8. Run: see the cheat sheet below.

よく使う flutter コマンドFlutter cheat sheet

# iOS シミュレータで起動（環境変数は --dart-define で注入）
flutter run -d "iPhone 15" \
  --dart-define=SUPABASE_URL=https://afmyqhicretqrjwmvsaa.supabase.co \
  --dart-define=SUPABASE_ANON_KEY=eyJ... \
  --dart-define=PARKY_API_BASE=https://dev-api.parky.co.jp \
  --dart-define=MAPBOX_ACCESS_TOKEN=pk....

# Android エミュレータ
flutter run -d emulator-5554 --dart-define=...

# Web プレビュー（プロトタイプ確認用。本番は iOS/Android のみ）
flutter run -d chrome --dart-define=...

# パッケージ追加
flutter pub add firebase_messaging

# 世代更新
flutter pub upgrade --major-versions

# lint / フォーマット
dart analyze
dart format lib test

# テスト
flutter test
flutter test --coverage   # coverage/lcov.info が出る

環境変数（--dart-define）Environment variables (--dart-define)

Dart コードからは const String.fromEnvironment('KEY', defaultValue: '...') で読む。 lib/config/env.dart に集約すると扱いやすい。実行時に上書きできないのでビルド単位で固定される点に注意。

Read from Dart via const String.fromEnvironment('KEY', defaultValue: '...'). Collect them in lib/config/env.dart. Values bake into the build — you cannot change them at runtime.

BFF を叩く契約Calling the BFF

クライアントが叩ける唯一の API 層は Cloudflare Workers BFF（/v1/*） です。 OpenAPI 3.1 仕様 (parky/api/openapi.json) が Single Source of Truth で、認証は Supabase 発行の JWT を Authorization: Bearer <token> ヘッダに載せます。

The Cloudflare Workers BFF (/v1/*) is the only API surface clients call. The OpenAPI 3.1 spec at parky/api/openapi.json is the source of truth; auth is a Supabase-issued JWT in Authorization: Bearer <token>.

最小リポジトリ層サンプルMinimal repository sample

// lib/data/parking_repository.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:supabase_flutter/supabase_flutter.dart';
import '../config/env.dart';

class ParkyApiException implements Exception {
  ParkyApiException(this.status, this.code, this.message, {this.requestId});
  final int status;
  final String code;
  final String message;
  final String? requestId;
  @override
  String toString() => 'ParkyApiException($status $code): $message';
}

class ParkingRepository {
  ParkingRepository({http.Client? client}) : _client = client ?? http.Client();
  final http.Client _client;

  Uri _u(String path, [Map<String, dynamic>? query]) =>
      Uri.parse('${Env.apiBase}$path').replace(
        queryParameters: query?.map((k, v) => MapEntry(k, '$v')),
      );

  Map<String, String> _headers() {
    final token = Supabase.instance.client.auth.currentSession?.accessToken;
    return {
      'Content-Type': 'application/json',
      if (token != null) 'Authorization': 'Bearer $token',
    };
  }

  Future<Map<String, dynamic>> _get(String path, [Map<String, dynamic>? q]) async {
    final res = await _client.get(_u(path, q), headers: _headers());
    return _parse(res);
  }

  Map<String, dynamic> _parse(http.Response res) {
    final body = res.body.isEmpty ? {} : jsonDecode(res.body) as Map<String, dynamic>;
    if (res.statusCode >= 400) {
      final err = body['error'] as Map<String, dynamic>? ?? const {};
      throw ParkyApiException(
        res.statusCode,
        (err['code'] as String?) ?? 'unknown_error',
        (err['message'] as String?) ?? res.reasonPhrase ?? 'error',
        requestId: err['request_id'] as String?,
      );
    }
    return body;
  }

  Future<Map<String, dynamic>> listHubs({int min = 1}) =>
      _get('/v1/hubs/publishable', {'min': min});

  Future<Map<String, dynamic>> nearbyLots({
    required double lat,
    required double lng,
    int radiusM = 1000,
  }) =>
      _get('/v1/parking-lots/nearby', {'lat': lat, 'lng': lng, 'radius_m': radiusM});
}

エラー形式（Workers 統一）Unified error shape (Workers)

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "request_id": "uuid-v4",
    "issues": [ /* Zod validation issues */ ]
  }
}

• code は スネークケース機械可読コード。画面分岐に使う
• code is a snake_case machine-readable code — branch on it, not on the message
• request_id はサーバログと紐付く UUID。サポート連絡時に必ず添える
• request_id is a UUID that joins the server log — always include it when escalating
• 422 は Zod バリデーション失敗で issues[] に詳細が入る
• 422 means Zod validation failed; drill into issues[] for details

認証フローAuth flow

1. 起動時に Supabase.initialize(url, anonKey) を呼ぶ（main.dart）
2. Call Supabase.initialize(url, anonKey) on startup (main.dart)
3. ログイン: supabase.auth.signInWithPassword() / signInWithOtp() / signInWithOAuth()
4. Sign in via signInWithPassword(), signInWithOtp(), or signInWithOAuth()
5. Supabase.instance.client.auth.currentSession?.accessToken を BFF 呼出の Bearer に載せる
6. Attach currentSession?.accessToken to every BFF request as a Bearer token
7. セッションは SDK が自動更新。期限切れ近傍での refresh は内部で行われる
8. Session refresh is automatic — the SDK handles token rotation near expiry
9. ログアウト: supabase.auth.signOut()。同時にローカルキャッシュ（flutter_secure_storage 等）もクリア
10. Sign out with supabase.auth.signOut(); also wipe any local cache (flutter_secure_storage, etc.)

Realtime 購読Realtime subscriptions

通知・駐車セッション状態のライブ更新は supabase-flutter の Realtime を使います（データプレーン例外）。 RLS で行スコープをかけるため、サブスクライブ対象のテーブルに対して自分の user_id フィルタを付けます。

Live updates for notifications and parking sessions use supabase-flutter's Realtime (a data-plane exception). RLS scopes the rows, so always filter subscriptions by your own user_id.

final channel = Supabase.instance.client
    .channel('public:user_notifications')
    .onPostgresChanges(
      event: PostgresChangeEvent.insert,
      schema: 'public',
      table: 'user_notifications',
      filter: PostgresChangeFilter(
        type: PostgresChangeFilterType.eq,
        column: 'user_id',
        value: Supabase.instance.client.auth.currentUser!.id,
      ),
      callback: (payload) {
        // show snackbar / badge update
      },
    )
    .subscribe();

// dispose 時
channel.unsubscribe();

画像アップロード（R2）Image upload (R2)

1. image_picker で端末から画像取得 → XFile を入手
2. Pick an image with image_picker → get an XFile
3. POST /v1/storage/upload-url に { file_name, file_size, mime_type, category, is_public } を渡して presigned URL を取得
4. POST /v1/storage/upload-url with { file_name, file_size, mime_type, category, is_public } and get back a presigned URL
5. 返ってきた upload_url に 直接 PUT。バイト列は Workers を経由しない
6. PUT the bytes directly to upload_url — they skip Workers
7. サーバ側で assets テーブルへ行が INSERT 済なので、asset_id を親エンティティに紐付ける PATCH / POST を呼ぶ
8. A row was already inserted into assets, so call the parent entity's PATCH / POST with that asset_id
9. 表示は https://cdn.parky.co.jp/<s3_key> を cached_network_image に渡す（CDN は匿名 GET）
10. Display by passing https://cdn.parky.co.jp/<s3_key> to cached_network_image (anonymous CDN)

プッシュ通知（FCM）Push notifications (FCM)

1. firebase_core + firebase_messaging を pubspec.yaml に追加
2. Add firebase_core + firebase_messaging to pubspec.yaml
3. flutterfire configure で iOS / Android / Web の設定ファイルを生成
4. Run flutterfire configure to generate iOS / Android / Web configs
5. 起動後に権限要求 → FCM トークン取得 → PUT /v1/me/push-tokens で upsert
6. After startup, ask for permission → fetch FCM token → upsert via PUT /v1/me/push-tokens
7. 受信: FirebaseMessaging.onMessage (foreground) + onMessageOpenedApp (tap) + onBackgroundMessage (バックグラウンド)
8. Receive: onMessage (foreground) + onMessageOpenedApp (tap) + onBackgroundMessage (bg)
9. 配信ペイロードの data.type と data.notification_id で deep link する運用
10. Deep link from data.type + data.notification_id in the payload

地図 (Mapbox)Maps (Mapbox)

• トークンは --dart-define で注入。Dart 側では MapboxOptions.setAccessToken(Env.mapboxToken) を main で 1 回だけ呼ぶ
• Pass the token via --dart-define; call MapboxOptions.setAccessToken(Env.mapboxToken) once in main
• 位置権限は permission_handler で事前に確認。拒否された場合は「GPS なし」モード（住所入力ベース）にフォールバック
• Check location permission with permission_handler up-front. If denied, fall back to a no-GPS mode (address input)
• 駐車場マーカーは /v1/parking-lots/nearby の結果を使う。BFF が PostGIS RPC で半径検索を返す
• Load parking-lot markers from /v1/parking-lots/nearby; the BFF wraps a PostGIS radius-search RPC

テストTesting

• ユニットテスト: test/ 配下に配置。data/ のリポジトリ層は http.Client をモックしてレスポンスを差し替える
• Unit: place under test/. Repositories mock http.Client and inject fake responses
• Widget テスト: flutter_test の testWidgets。Supabase や ゴールデンファイル依存は避けて UI 単体を検証
• Widget: use testWidgets from flutter_test. Keep tests free of Supabase / goldens — verify the UI in isolation
• 統合テスト: integration_test パッケージ。CI でヘッドレス実機（Firebase Test Lab / BrowserStack）を使う想定だが現状は未配線
• Integration: the integration_test package is envisioned (Firebase Test Lab / BrowserStack) but not wired yet
• カバレッジ: flutter test --coverage で coverage/lcov.info を吐く。Codecov 配線は未
• Coverage: flutter test --coverage writes coverage/lcov.info. Codecov upload is not wired yet

Lint / フォーマットLint / formatting

• analysis_options.yaml で package:flutter_lints を有効化。supabase.from() 等の禁止呼び出しは カスタム lint ルールで lint エラー化 する方針（未実装タスク）
• analysis_options.yaml enables package:flutter_lints. Banning calls like supabase.from() with a custom lint rule is planned but not yet implemented
• PR 前には dart analyze && dart format lib test && flutter test を全部パスさせる
• Before opening a PR run dart analyze && dart format lib test && flutter test

ビルド・配布Build & release

Signing 用の keystore.jks（Android）や App Store Connect API Key（iOS）は 1Password の HF｜開発 vault から取得し、CI 実行時のみ復号して使う。レポジトリにはコミットしない。

Signing materials — keystore.jks (Android) and the App Store Connect API Key (iOS) — live in 1Password (HF｜開発 vault) and are decrypted only during CI. Never commit them.

Deep link / Universal linkDeep links / Universal links

• カスタムスキーム: parky://parking/{id} — OAuth リダイレクトや Push タップで使用
• Custom scheme: parky://parking/{id} — used by OAuth redirects and push taps
• Universal link: https://parky.co.jp/app/parking/{id} → iOS は apple-app-site-association、Android は assetlinks.json で bind
• Universal links: https://parky.co.jp/app/parking/{id} — bind with apple-app-site-association on iOS and assetlinks.json on Android
• 受信: app_links の uriLinkStream を go_router にブリッジ
• Receive: bridge app_links's uriLinkStream into go_router

よくあるハマりどころCommon pitfalls

• 401 が出る: currentSession が null（未ログイン）か、トークンが期限切れ。UI 側で onAuthStateChange を購読して自動 refresh を確認
• Getting 401: currentSession is null (not signed in) or the token expired. Subscribe to onAuthStateChange and confirm refresh works
• 403 が出る: BFF が RLS / 自前スコープで弾いている。request_id をコピーして Workers Observability で元ログを確認
• Getting 403: the BFF rejected it at RLS / user-scope. Copy request_id and dig into Workers Observability
• 422 が出る: Zod validation 失敗。issues[] にパス付きで理由が入っているので UI バリデーションを合わせる
• Getting 422: Zod validation failed — issues[] carries path-qualified reasons. Align UI validators
• 画像が出ない: cdn.parky.co.jp の CORS ではなく、PUT 時の Content-Type 不一致が犯人のことが多い。presign 時と PUT 時で完全一致させる
• Image missing: usually a Content-Type mismatch at PUT, not a CORS issue. Keep it identical between the presign call and the PUT
• OAuth redirect が戻らない: カスタムスキームが AndroidManifest / Info.plist に未登録。parky:// を両方で受ける設定を忘れずに
• OAuth redirect never returns: the custom scheme isn't registered in AndroidManifest / Info.plist. Make sure parky:// is declared on both
• Web プレビューで地図が出ない: Mapbox のトークンに Web ドメイン許可が無い。開発中は localhost:* を allow list に入れる
• Map missing in Web preview: the Mapbox token lacks the web domain. Add localhost:* to the allow list for dev

参考リンクReferences

• Swagger UI — インタラクティブに叩ける BFF 仕様（Dev 固定、英訳オーバーレイあり）Interactive BFF spec (Dev only, with EN overlay)
• Redoc — 読み物向けの BFF 仕様Reading-oriented BFF spec
• Architecture — 全体アーキテクチャ（mobile 視点）Overall architecture from the mobile angle
• API reference — クライアントが叩く API の整理Organized list of APIs the client calls
• Data model — モバイルが読む PG テーブルPG tables read by mobile
• Notifications — 通知全般（Push / アプリ内）Notifications end-to-end (push / in-app)
• Mobile UI mockup — 動作可能プロトタイプInteractive prototype