# インフラ設計書

## 概要

本ドキュメントは、Bagisto Open Source eCommerce Mobile Appのインフラストラクチャ構成について記述する。本アプリケーションはFlutterで構築されたクロスプラットフォームモバイルアプリケーションであり、バックエンドにBagisto eCommerceプラットフォーム（Laravel）を使用する。アプリケーションはGraphQL APIを介してバックエンドと通信し、Firebase Cloud Messagingによるプッシュ通知機能を提供する。

## システム構成

### 全体構成

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              ユーザー端末                                    │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │    Android端末    │  │     iOS端末      │  │    Web (PWA)     │          │
│  │    (SDK 22+)     │  │    (iOS 16+)     │  │                  │          │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘          │
└───────────┼─────────────────────┼─────────────────────┼─────────────────────┘
            │                     │                     │
            │      HTTPS (GraphQL API)                  │
            └─────────────────────┼─────────────────────┘
                                  │
┌─────────────────────────────────▼─────────────────────────────────────────┐
│                         外部サービス層                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐        │
│  │  Firebase Cloud   │  │   Google Maps    │  │     PayPal       │        │
│  │    Messaging      │  │      API         │  │   Payment API    │        │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘        │
└───────────────────────────────────────────────────────────────────────────┘
                                  │
                                  │ HTTPS
                                  ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                        バックエンド層                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                    Bagisto eCommerce Platform                       │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │ │
│  │  │  GraphQL API  │  │   Laravel    │  │   Database   │              │ │
│  │  │   Endpoint   │  │  Framework   │  │   (MySQL)    │              │ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘
```

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| モバイルアプリ | クライアントアプリケーション（Flutter） | N/A（ユーザー端末） | N/A |
| Bagistoサーバー | eCommerceバックエンド、GraphQL API提供 | 運用環境に依存 | 1台以上 |
| Firebase | プッシュ通知（FCM）、クラッシュ分析 | Google Cloud管理 | N/A |
| Google Maps | 位置情報サービス、地図表示 | Google Cloud管理 | N/A |
| PayPal | 決済処理 | PayPal管理 | N/A |

### ネットワーク構成

#### 通信プロトコル

| 通信経路 | プロトコル | ポート | 用途 |
| --- | --- | --- | --- |
| アプリ → Bagisto API | HTTPS | 443 | GraphQL API通信 |
| アプリ → Firebase | HTTPS | 443 | プッシュ通知登録・受信 |
| アプリ → Google Maps | HTTPS | 443 | 地図・位置情報取得 |
| アプリ → PayPal API | HTTPS | 443 | 決済処理 |

#### セキュリティ設定

- **iOS**: `NSAppTransportSecurity`で任意のHTTPS通信を許可
- **Android**: `usesCleartextTraffic=true`（開発用、本番環境では制限推奨）
- **証明書検証**: `MyHttpOverrides`クラスで証明書バイパス実装（開発用）

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Flutter SDK | 3.32.5 | クロスプラットフォームモバイルアプリ開発フレームワーク |
| Dart | 3.8.1 | プログラミング言語 |
| Firebase Core | 3.13.0 | Firebase初期化・基盤機能 |
| Firebase Messaging | 15.2.5 | プッシュ通知（FCM） |
| GraphQL Flutter | 5.1.1 | GraphQL APIクライアント |
| Google Maps Flutter | 2.4.0 | 地図表示 |
| Hive | 2.2.3 | ローカルデータストレージ |
| Get Storage | 2.0.3 | 設定・キャッシュ管理 |
| Dio | 5.3.3 | HTTPクライアント |
| Retrofit | 4.0.2 | REST APIクライアント |
| Flutter PayPal Payment | 1.0.8 | PayPal決済統合 |
| PayPal Checkout (iOS) | 1.5.0 | iOS向けPayPal SDK |

### Android ビルド設定

| 設定項目 | 値 |
| --- | --- |
| compileSdkVersion | 35 |
| minSdkVersion | 22 |
| targetSdkVersion | 35 |
| NDK Version | 27.0.12077973 |
| Kotlin Version | 動的設定 |

### iOS ビルド設定

| 設定項目 | 値 |
| --- | --- |
| 最小iOSバージョン | 16.0 |
| Xcode | 16.3 |
| Swift | 6.1 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| Bagisto GraphQL API | 商品・注文・ユーザー管理等のバックエンド機能 | GraphQL over HTTPS |
| Firebase Cloud Messaging (FCM) | プッシュ通知配信 | Firebase SDK |
| Firebase Crashlytics | クラッシュレポート・分析 | Firebase SDK |
| Google Maps Platform | 地図表示・住所検索・位置情報 | REST API / SDK |
| PayPal Standard | 決済処理（Web支払い） | REST API |
| PayPal Smart Button | 決済処理（ネイティブ） | Native SDK |
| Google ML Kit | 画像認識・テキスト認識（商品検索） | Native SDK |
| ARCore (Android) | AR機能（商品プレビュー） | Native SDK |

### API エンドポイント設定

```dart
// lib/utils/server_configuration.dart
const String baseDomain = "";  // 運用環境で設定
const String baseUrl = "$baseDomain/graphql";
const String defaultChannelId = "1";
const String defaultStoreCode = "en";
```

### 対応決済方法

- `cashondelivery` - 代金引換
- `moneytransfer` - 銀行振込
- `paypal_standard` - PayPal標準
- `paypal_smart_button` - PayPalスマートボタン

## スケーリング設計

### モバイルアプリケーション

- **プラットフォーム対応**: Android、iOS、Web (PWA)の3プラットフォームに対応
- **多言語対応**: 8言語サポート（英語、フランス語、オランダ語、トルコ語、スペイン語、アラビア語、ポルトガル語(ブラジル)、ヒンディー語）
- **多通貨対応**: デフォルトUSD、動的通貨切り替え対応

### バックエンド（Bagisto）

- **API設計**: GraphQL APIによる効率的なデータ取得
- **キャッシング**: アプリ側でHive/GetStorageによるローカルキャッシュ実装
- **プリフェッチ**: `isPreFetchingEnable`オプションでコンテンツ事前読み込み

### 推奨バックエンドスケーリング

| 負荷レベル | 構成 |
| --- | --- |
| 小規模（〜1,000 DAU） | 単一サーバー構成 |
| 中規模（〜10,000 DAU） | 負荷分散 + DBレプリケーション |
| 大規模（10,000+ DAU） | マイクロサービス + CDN + 水平スケーリング |

## 可用性設計

### モバイルアプリケーション

- **オフライン対応**: Hiveによるローカルデータ永続化
- **ネットワーク監視**: `internet_connection_checker`による接続状態監視
- **リトライ機能**: GraphQL Flutterによる自動リトライ
- **エラーハンドリング**: カスタムエラーハンドラによる graceful degradation

### バックエンド推奨構成

| 対策 | 説明 |
| --- | --- |
| ロードバランサー | 複数APサーバーへの負荷分散 |
| データベースレプリケーション | マスター/スレーブ構成 |
| CDN | 静的コンテンツ配信 |
| 自動スケーリング | 負荷に応じたインスタンス増減 |

### サービス稼働目標

| サービス | 目標稼働率 | 許容ダウンタイム/月 |
| --- | --- | --- |
| Bagisto API | 99.5% | 3.65時間 |
| Firebase FCM | 99.95%（SLA保証） | 21.6分 |
| Google Maps | 99.9%（SLA保証） | 43.2分 |

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| Bagistoデータベース | フルバックアップ + 増分 | 日次 | 30日 |
| ユーザーアップロードファイル | オブジェクトストレージ同期 | リアルタイム | 無期限 |
| アプリ設定（ローカル） | GetStorage/Hive | 自動（操作時） | アプリ削除まで |
| Firebase設定 | Firebase Console | 手動エクスポート | プロジェクト存続期間 |

### ローカルデータ永続化

- **GetStorage**: 設定情報、言語、通貨設定
- **Hive**: 製品データ、カテゴリデータのキャッシュ
- **Cached Network Image**: 画像キャッシュ

## 監視設計

### アプリケーション監視

| 監視項目 | ツール | 説明 |
| --- | --- | --- |
| クラッシュレポート | Firebase Crashlytics | アプリクラッシュの検知・分析 |
| パフォーマンス | Flutter DevTools | 開発時のパフォーマンス分析 |
| ネットワーク | `debugPrint` / カスタムログ | API通信のデバッグ |

### バックエンド監視（推奨）

| 監視項目 | 推奨ツール | 閾値 |
| --- | --- | --- |
| APIレスポンスタイム | New Relic / Datadog | > 500ms で警告 |
| エラーレート | Sentry | > 1% で警告 |
| サーバーリソース | CloudWatch / Prometheus | CPU > 80% で警告 |
| データベース接続 | MySQLモニタリング | 接続数上限の80%で警告 |

### プッシュ通知監視

| 監視項目 | ツール | 説明 |
| --- | --- | --- |
| 配信成功率 | Firebase Console | FCM配信統計 |
| 購読者数 | Firebase Console | トピック別購読者管理 |

## 環境構成

### 開発環境

| 項目 | 設定 |
| --- | --- |
| Flutter SDK | 3.32.5 |
| Android Studio | Meerkat 2024.3.1 Patch 2 |
| Xcode | 16.3 |
| API接続 | 開発用Bagistoサーバー |
| 証明書検証 | バイパス有効 |

### ステージング環境

| 項目 | 設定 |
| --- | --- |
| API接続 | ステージングBagistoサーバー |
| Firebase | ステージングプロジェクト |
| 証明書検証 | 有効 |

### 本番環境

| 項目 | 設定 |
| --- | --- |
| API接続 | 本番Bagistoサーバー |
| Firebase | 本番プロジェクト |
| 証明書検証 | 有効（厳格） |
| コード難読化 | ProGuard有効（Android） |
| リリースサイニング | 専用キーストア |

## デプロイメント

### アプリ配布

| プラットフォーム | 配布先 | 要件 |
| --- | --- | --- |
| Android | Google Play Store | 署名済みAPK/AAB |
| iOS | Apple App Store | 署名済みIPA、App Store Connect |
| Web | 静的ホスティング | Flutter Web ビルド |

### ビルドコマンド

```bash
# 依存関係インストール
flutter pub get

# コード生成
flutter pub run build_runner build --delete-conflicting-outputs

# リリースビルド（Android）
flutter build apk --release

# リリースビルド（iOS）
flutter build ios --release

# リリースビルド（Web）
flutter build web --release
```

## 備考

### セキュリティに関する注意事項

1. **証明書検証**: 本番環境では`MyHttpOverrides`クラスを削除し、適切な証明書検証を実施すること
2. **APIキー管理**: Google Maps APIキー、PayPalクレデンシャルは環境変数または安全なストレージで管理すること
3. **署名キー**: リリース用署名キーは安全に保管し、ソースコード管理に含めないこと

### 依存関係

- Bagisto eCommerce Platform v2.3.6以上が必要
- [Bagisto Headless eCommerce API](https://github.com/bagisto/headless-ecommerce/)のインストールが必須

### 既知の制限事項

1. ARCore機能はAndroidのみ対応
2. ML Kit機能は一部端末で制限あり
3. PayPal Smart Buttonは地域によって利用不可

### 変更履歴

| 日付 | バージョン | 変更内容 |
| --- | --- | --- |
| 2026-01-28 | 1.0 | 初版作成 |
