Créer une app Android native avec Flutter depuis une API (Happy et Fluke)

Contexte

Vous avez un produit web et vous voulez offrir une expérience native de première classe sur Android (téléphone, tablette, TV, Wear OS, Auto). Ce workflow orchestre deux agents : Happy conçoit l’API exhaustive adaptée à tous les clients, puis Fluke la consomme pour construire un starter kit Android/Flutter compilable, avec tests, et accompagne jusqu’au déploiement Google Play Store.

Prérequis

Phase 1 (Happy — API Design)

Projet web existant (Next.js, Rails, Django, etc.)
Stack backend documenté
Modèles et endpoints existants ou spécification préliminaire
Optionnel : OpenAPI 3.1 spec si API existe

Phase 2 (Fluke — Android Implementation)

Android Studio 2024.1+
Flutter SDK 3.24+ (ou Kotlin 2.0+ pour Compose)
Android API level: 24+
Google Play Developer account

Ecosystem Prerequisites

Happy génère docs/api/ (source de vérité)
Steve (iOS) et Fluke (Android) réutilisent la même docs/api/
Si Happy génère d’abord, Fluke skip la Phase 0 et commence directement

Étapes

1. Phase 1 : Conception API avec Happy

Invoquer Happy pour auditer et concevoir l’API :

/ulk:happy
# ou
happy
# ou
API design
# ou
concevoir API

Happy génère docs/api/ complète (voir 11-web-to-ios.md pour détails).

2. Phase 2 : Implémentation Android avec Fluke

Une fois docs/api/ généré, invoquer Fluke :

/ulk:fluke
# ou
fluke
# ou
Android app
# ou
Flutter
# ou
Google Play

3. Fluke Phase 0-1 : Diagnostic et setup

Fluke détecte Happy a déjà généré l’API :

🤖 Fluke — Orchestrateur Android
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Lisant docs/api/...
  ✅ OpenAPI 3.1 trouvé
  ✅ 12 endpoints détectés
  ✅ Auth: JWT Bearer
  ✅ Push: FCM (Firebase Cloud Messaging)

Platforms Android cibles:
  ✅ Phone (API 24+)
  ✅ Tablet (API 24+)
  ✅ TV (optional)
  ✅ Wear OS (optional)
  ✅ Auto (optional)

Stack choix:
  Option 1: Flutter + Dart (multiplateforme)
    → Unique codebase pour phone/tablet/wear/TV/Auto
  Option 2: Kotlin + Jetpack Compose (natif)
    → Performance maximale, compile Compose uniquement

Recommendation: Flutter (coûts maintenabilité réduits)

4. Fluke Phase 2-5 : Génération starter kit

Option A : Flutter :

my_app/
├── lib/
│   ├── main.dart                      # App root
│   ├── models/
│   │   ├── user.dart                  # JSON serializable
│   │   ├── post.dart
│   │   └── ...
│   ├── services/
│   │   ├── api_client.dart            # HTTP requests
│   │   ├── auth_service.dart          # JWT + OAuth2
│   │   ├── push_service.dart          # FCM
│   │   └── offline_sync_service.dart
│   ├── providers/
│   │   ├── user_provider.dart         # Riverpod/Provider
│   │   ├── post_provider.dart
│   │   └── auth_provider.dart
│   ├── screens/
│   │   ├── home_screen.dart
│   │   ├── user_list_screen.dart
│   │   ├── post_detail_screen.dart
│   │   ├── auth_screen.dart
│   │   └── settings_screen.dart
│   ├── widgets/
│   │   ├── user_tile.dart
│   │   ├── post_card.dart
│   │   └── ...
│   └── theme/
│       └── app_theme.dart
├── test/
│   ├── api_client_test.dart
│   ├── user_provider_test.dart
│   └── ...
├── pubspec.yaml                       # Dependencies
└── android/                           # Native Android config

Option B : Kotlin/Compose :

MyApp/
├── app/src/main/
│   ├── kotlin/com/example/myapp/
│   │   ├── MainActivity.kt
│   │   ├── models/
│   │   │   ├── User.kt
│   │   │   ├── Post.kt
│   │   │   └── ...
│   │   ├── api/
│   │   │   ├── ApiClient.kt
│   │   │   ├── AuthService.kt
│   │   │   └── PushService.kt
│   │   ├── viewmodel/
│   │   │   ├── UserListViewModel.kt
│   │   │   ├── PostDetailViewModel.kt
│   │   │   └── ...
│   │   ├── ui/
│   │   │   ├── screens/
│   │   │   ├── composables/
│   │   │   └── theme/
│   │   └── ...
│   └── res/
├── build.gradle.kts                   # Gradle config
└── ...

5. Fluke Phase 6 : Tests et déploiement

Fluke génère :

Tests Flutter :

test('APIClient fetches users', () async {
  final client = APIClient();
  final users = await client.request<List<User>>('/users');
  expect(users, isNotEmpty);
});

test('AuthService JWT refresh', () async {
  final auth = AuthService();
  final token = await auth.refreshToken();
  expect(token, isNotNull);
});

Deploy instructions :

# Build APK (phone)
flutter build apk --release

# Build AAB (Google Play)
flutter build appbundle --release

# Deploy via Fastlane
fastlane init                           # Setup
fastlane supply --aab build/app.aab --track internal

Exemple de sortie

api_client.dart (Flutter, généré) :

import 'package:http/http.dart' as http;
import 'dart:convert';

class APIClient {
  static const String baseURL = 'https://api.example.com';
  late http.Client _httpClient;
  String? _authToken;

  APIClient() {
    _httpClient = http.Client();
  }

  Future<T> request<T>(
    String endpoint, {
    String method = 'GET',
    dynamic body,
    required T Function(Map<String, dynamic>) fromJson,
  }) async {
    final url = Uri.parse('$baseURL$endpoint');
    final headers = {
      'Content-Type': 'application/json',
      if (_authToken != null) 'Authorization': 'Bearer $_authToken',
    };

    final response = await _httpClient.request(
      method,
      url,
      headers: headers,
      body: body != null ? jsonEncode(body) : null,
    );

    if (response.statusCode >= 200 && response.statusCode < 300) {
      final json = jsonDecode(response.body);
      return fromJson(json);
    } else {
      throw APIException('Request failed: ${response.statusCode}');
    }
  }

  void setAuthToken(String token) {
    _authToken = token;
  }
}

pubspec.yaml (Flutter, généré) :

name: my_app
description: Native Android app from Happy API

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  riverpod: ^2.4.0
  flutter_riverpod: ^2.4.0
  json_serializable: ^6.7.1
  firebase_messaging: ^14.6.0
  flutter_secure_storage: ^9.0.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  riverpod_generator: ^2.3.0
  build_runner: ^2.4.0

Variantes

Variante A : Kotlin/Compose au lieu de Flutter — Fluke génère projet Kotlin natif avec Jetpack Compose (performance max)
Variante B : Multi-form factor — Fluke configure tablets, Wear OS, TV, Auto dans la même app (layouts adaptatifs Flutter)
Variante C : Offline-first — Fluke implémente local storage (Hive, SQLite) + sync strategy pour offline support
Variante D : Réutiliser Steve’s docs/api/ — Si Steve (iOS) a déjà exécuté, Fluke trouve docs/api/ existant et skip Phase 1 complètement

Agents enchaînés

Flux orchestré (Happy → Fluke) :

Happy (mobile/49) — Conception API
  └─ Output : docs/api/ (OpenAPI 3.1)
       ↓ réutilisé par
Fluke (mobile/48) — Implémentation Android
  ├─ Phase 0 : Lire docs/api/ (5 min)
  ├─ Phase 1 : Déterminer stack (Flutter vs Kotlin, 5 min)
  ├─ Phase 2 : Setup Android Studio + Google Play (10 min)
  ├─ Phase 3 : Générer Models + Services (30 min)
  ├─ Phase 4 : Générer Screens + Providers (30 min)
  ├─ Phase 5 : Générer Tests (20 min)
  └─ Output : Android Studio project compilable + deploy instructions

Après iOS et Android :

Steve (27) + Fluke (48) utilisent la MÊME docs/api/
→ Zéro redéfinition, maintien unique pour tous les clients

Troubleshooting

Symptôme	Cause probable	Résolution
”Happy API missing”	Happy n’a pas été lancé avant Fluke	Lancer Happy d’abord via `/ulk:happy`
”Flutter SDK not found”	Flutter non installé ou PATH mal configuré	Installer Flutter depuis flutter.dev, ajouter au PATH
”Google Play Developer account missing”	Pas de compte enregistré	Créer via play.google.com/console, configurer avec `fastlane init`
”FCM not working”	Firebase project pas lié à l’app Android	Créer Firebase project dans console.firebase.google.com, télécharger google-services.json, placer dans android/app/
“Kotlin compilation errors”	Versions dépendances incompatibles	Mettre à jour build.gradle.kts avec versions Fluke suggérées

Voir aussi

./11-web-to-ios.md — Créer une app iOS/SwiftUI (même API, autre platform)
./02-blackemperor-pre-release.md — Pre-release orchestrator (inclut Android deployment)
agents/mobile/49-happy.md — Documentation Happy (API design)
agents/mobile/48-fluke.md — Documentation Fluke (Android implementation)
agents/_shared/mobile-protocol.md — Protocole mobile complet
Google Play Console : https://play.google.com/console — Developer dashboard
Flutter Docs : https://flutter.dev/docs — Framework complet