unionflow-mobile-apps/docs/DATA_CONSISTENCY.md

Cohérence des données — UnionFlow Mobile

Ce document décrit les conventions et alignements API ↔ app pour éviter les incohérences.

1. Configuration

• API : AppConfig.apiBaseUrl (initialisé dans main() via AppConfig.initialize()). Utilisé par ApiClient (Dio baseUrl).
• Keycloak : AppConfig.keycloakBaseUrl, keycloakRealmUrl, keycloakTokenUrl.
• Toutes les requêtes passent par le même ApiClient (token, refresh, timeouts).

2. Membres (Annuaire)

Backend (MembreSummaryResponse / PagedResponse)	Mobile (MembreCompletModel / repository)
data (liste), total, page, size, totalPages	_parseMembreSearchResult lit data, total (num→int), page, size, totalPages
associationNom	Normalisé → organisationNom dans _normalizeAndParseMembre
statutCompte ("ACTIF", etc.)	Normalisé → statut (enum StatutMembre)
photoUrl (MembreResponse détail)	Normalisé → photo si absent
id, organisationId (UUID)	Convertis en String avant fromJson
nom, prenom, email requis	Modèle : champs requis ; summary backend les envoie toujours

• Liste paginée : GET /api/membres?page=&size= → réponse PagedResponse avec data, total, page, size, totalPages.
• Recherche : GET /api/membres/recherche?q=&page=&size= → liste ou même structure paginée selon backend.
• Affichage annuaire : members_page_wrapper convertit MembreCompletModel en Map avec status = libellé français (Actif, En attente, etc.) via _mapStatutToString(statut).

3. Cotisations (Contributions)

• Mes cotisations : GET /api/cotisations/mes-cotisations?page=&size= → backend renvoie une liste (pas un objet paginé). Le repository gère data is List.
• En attente : GET /api/cotisations/mes-cotisations/en-attente → liste. Le repository accepte aussi data['data'] ou data['content'] si le format change.
• Modèle : ContributionModel avec id, statut, montantDu, montantPaye, dateEcheance, nomMembre, etc. alignés sur les champs backend. Côté mobile, membreNom utilise nomMembre avec fallback sur nomCompletMembre (Summary vs Response).

4. Épargne

• Comptes : GET /api/v1/epargne/comptes/mes-comptes → liste de comptes. CompteEpargneModel : id, membreId, organisationId en String (backend UUID sérialisé).
• Transactions : GET /api/v1/epargne/transactions/compte/{compteId} → liste. TransactionEpargneModel.fromJson avec _toDouble pour montants.
• Tous les IDs (compte, membre, org) sont traités en String côté mobile (toString() si besoin).

5. Organisations

• Mes organisations : GET /api/organisations/mes → liste. OrganizationModel avec id, nom, nomCourt, etc.
• Liste (admin) : GET /api/organisations?page=&size= → liste ou paginée selon endpoint. Repository parse response.data as List ou structure paginée.

6. Admin utilisateurs (SUPER_ADMIN)

• Liste : GET /api/admin/users?page=&size=&search= → UnionFlow renvoie UserSearchResultDTO (proxy lions-user-manager). Structure vérifiée dans lions-user-manager-server-api :
  • UserSearchResultDTO : users (List<UserDTO>), totalCount (Long), currentPage (Integer), pageSize (Integer), totalPages (Integer), plus optionnels (hasNextPage, criteria, executionTimeMs, etc.).
  • UserDTO (BaseDTO + champs) : id, username, email, prenom, nom, enabled, realmRoles (List<String>), statut, dateCreation, etc.
  • Le repository mobile lit data['users'], totalCount, currentPage, pageSize, totalPages (avec cast num → int) et parse chaque élément avec AdminUserModel.fromJson. Alignement confirmé.
• Associer organisation : POST /api/admin/associer-organisation avec body { "email", "organisationId" }.

7. Dashboard

• Avec organisation : appel avec organizationId et userId (chaînes). DashboardEntity / DashboardStatsModel alignés sur les réponses backend.
• Membre sans org : GET /api/dashboard/membre/me → MembreDashboardSyntheseModel, mappé vers la même DashboardEntity pour réutilisation UI.

8. Bonnes pratiques

• IDs : toujours normaliser en String côté mobile (.toString()) pour UUID backend.
• Pagination : préférer (data['total'] as num?)?.toInt() pour accepter int ou double selon la sérialisation JSON.
• Statut / libellé : backend envoie souvent statutCompte + statutCompteLibelle ; le mobile peut normaliser statutCompte → statut (enum) et utiliser les libellés pour l’affichage.
• Noms de champs : garder une seule normalisation dans le repository (ex. _normalizeAndParseMembre) pour éviter les doublons (associationNom, photoUrl, statutCompte, etc.).

9. Vérifications effectuées

• Membres : PagedResponse data/total/page/size/totalPages alignés ; normalisation associationNom, statutCompte, photoUrl, id/organisationId.
• Cotisations : liste directe pour mes-cotisations et en-attente.
• Épargne : IDs en string, montants avec _toDouble.
• Config : une seule base URL et un seul ApiClient.