# Documentation du Widget EntiteForm avec RegionRepository

Cette documentation explique comment utiliser le widget `EntiteForm` avec le `RegionRepository` pour afficher et gérer les régions dans le formulaire d'entité.

## Intégration du RegionRepository

Le widget `EntiteForm` est conçu pour fonctionner avec le `RegionRepository` afin de récupérer la liste des régions disponibles pour le champ de sélection de région. Voici comment l'intégrer :

### 1. Initialisation du RegionRepository

Le `RegionRepository` doit être initialisé et fourni au widget `EntiteForm` via un `Provider`. Voici un exemple d'initialisation :

```dart
final regionRepository = RegionRepository();
await regionRepository.init();
```

### 2. Fournir le RegionRepository via Provider

Pour que le widget `EntiteForm` puisse accéder au `RegionRepository`, vous devez le fournir via un `Provider` :

```dart
MultiProvider(
  providers: [
    ChangeNotifierProvider<RegionRepository>.value(value: regionRepository),
    // Autres providers si nécessaire
  ],
  child: EntiteForm(
    amicale: amicale,
    onSubmit: handleSubmit,
    readOnly: false,
  ),
)
```

### 3. Mise à jour des régions depuis l'API

Lorsque l'API renvoie les données des régions dans la réponse de login, vous devez les mettre à jour dans le `RegionRepository` :

```dart
// Dans le service qui gère la connexion
void handleLoginResponse(Map<String, dynamic> response) {
  // Autres traitements...

  // Mise à jour des régions si présentes dans la réponse
  if (response.containsKey('regions') && response['regions'] is List) {
    final regionRepository = Provider.of<RegionRepository>(context, listen: false);
    regionRepository.updateRegionsFromApi(response['regions']);
  }
}
```

## Fonctionnement avec les restrictions d'accès

Le widget `EntiteForm` gère automatiquement les restrictions d'accès basées sur le rôle de l'utilisateur :

- Pour les utilisateurs avec un rôle ≤ 2, le champ de sélection de région est en lecture seule
- Pour les utilisateurs avec un rôle > 2, le champ de sélection de région est modifiable

## Filtrage des régions selon le code postal

Le `RegionRepository` offre une méthode `getRegionByPostalCode` qui permet de filtrer les régions en fonction du code postal :

```dart
// Récupérer la région correspondant au code postal
final codePostal = '75001';
final region = regionRepository.getRegionByPostalCode(codePostal);
if (region != null) {
  // Utiliser la région trouvée
  print('Région trouvée : ${region.libelle}');
}
```

Cette fonctionnalité est particulièrement utile pour pré-remplir le champ de région lorsque l'utilisateur entre un code postal.

## Exemple complet d'utilisation

Un exemple complet d'utilisation est disponible dans le fichier `app/lib/presentation/widgets/examples/entite_form_with_regions_example.dart`.

### Exemple simplifié

```dart
class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late RegionRepository _regionRepository;
  AmicaleModel? _amicale;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _regionRepository = RegionRepository();
    _initData();
  }

  Future<void> _initData() async {
    setState(() {
      _isLoading = true;
    });

    try {
      // Initialiser le repository des régions
      await _regionRepository.init();

      // Charger l'amicale si nécessaire
      // ...

      setState(() {
        _isLoading = false;
      });
    } catch (e) {
      debugPrint('Erreur lors de l\'initialisation: $e');
      setState(() {
        _isLoading = false;
      });
    }
  }

  void _handleSubmit(AmicaleModel amicale) {
    // Traiter la soumission du formulaire
  }

  @override
  Widget build(BuildContext context) {
    return MultiProvider(
      providers: [
        ChangeNotifierProvider<RegionRepository>.value(value: _regionRepository),
      ],
      child: Scaffold(
        appBar: AppBar(title: Text('Formulaire d\'entité')),
        body: _isLoading
            ? const Center(child: CircularProgressIndicator())
            : SingleChildScrollView(
                padding: const EdgeInsets.all(16.0),
                child: EntiteForm(
                  amicale: _amicale,
                  onSubmit: _handleSubmit,
                  readOnly: false,
                ),
              ),
      ),
    );
  }
}
```

## Mise à jour du code postal et de la région

Pour mettre à jour automatiquement la région lorsque l'utilisateur change le code postal, vous pouvez étendre le widget `EntiteForm` ou créer un wrapper qui écoute les changements du champ de code postal et met à jour la région en conséquence.

## Remarques importantes

1. Assurez-vous que le `RegionRepository` est initialisé avant d'afficher le formulaire.
2. Le widget `EntiteForm` s'adapte automatiquement au rôle de l'utilisateur pour les restrictions d'accès.
3. Les régions sont filtrées en fonction du code postal de l'amicale pour les utilisateurs avec un rôle ≤ 2.
4. Pour les utilisateurs avec un rôle > 2, toutes les régions sont disponibles dans le dropdown.
