Documentation Crystal

Modèle de Données - Projet Crystal

Cette documentation détaille le modèle de données du système Crystal, présentant les tables principales, leurs relations et leur organisation.

Le schéma de base de données est conçu pour gérer l'ensemble du flux, du consentement initial des entrepreneurs jusqu'à leur qualification par les partenaires financiers.

Gestion des migrations avec Liquibase

Crystal utilise Liquibase comme outil de gestion des migrations de base de données, ce qui permet un contrôle précis des changements de schéma et une meilleure traçabilité.

Configuration Liquibase

  • Automatisation : Les migrations sont exécutées automatiquement au démarrage de l'application
  • Fichiers SQL : Modifications du schéma définies dans des fichiers SQL versionnés
  • Registre de changements : Suivi précis de l'historique des modifications via le fichier changeLog.xml
  • Intégration Quarkus : Utilisation de l'extension quarkus-liquibase pour une intégration transparente

Accès aux données avec Quarkus Panache

Le système Crystal utilise Quarkus Panache Reactive pour l'accès aux données, offrant une approche simplifiée et réactive des opérations de persistance.

Caractéristiques principales

  • Modèle actif vs Repository : Crystal utilise le modèle Repository de Panache pour une meilleure séparation des préoccupations
  • Approche réactive : Utilisation de PanacheEntityBase et PanacheRepository en mode réactif pour des opérations non-bloquantes
  • Requêtes simplifiées : Méthodes prédéfinies comme findById, findAll, persist, etc.
  • Requêtes personnalisées : Possibilité d'écrire des requêtes personnalisées avec une syntaxe fluide

Entités principales du modèle de données

L'analyse du code source a permis d'identifier les entités principales suivantes dans le modèle de données:

Principales entités identifiées

  • Account, Person, Administrator - Gestion des utilisateurs et authentification
  • Enterprise, EnterpriseService - Partenaires financiers et services proposés
  • PdeEntrepreneur, PdeEntrepreneurEnterpriseRelation - Données importées de PDE
  • FieldAgent, FieldVisit - Agents terrain et visites chez les entrepreneurs
  • EntrepreneurActivity, EntrepreneurQualification - Suivi des activités et qualifications
  • ActivityDocument, DocumentStorage - Gestion des documents et pièces justificatives
  • SubPrefecture, Commune, Neighborhood, Sector - Hiérarchie géographique
  • Application, ApplicationKey - Gestion des applications externes accédant à l'API
  • AdminSession, AuditLog, ApiLog - Sécurité et traçabilité

Schéma général

Le modèle de données est organisé en plusieurs domaines fonctionnels:

Diagramme des principales entités et leurs relations

Schéma général des domaines fonctionnels

Le modèle de données est organisé en plusieurs domaines fonctionnels qui segmentent les responsabilités et facilitent la maintenance.

Organisation du modèle de données par domaines fonctionnels

Description des domaines fonctionnels

  • Gestion des utilisateurs et comptes - Gère l'authentification, les autorisations et les profils utilisateurs du système
  • Entrepreneurs et données PDE - Stocke les informations des entrepreneurs ayant donné leur consentement via la plateforme PDE
  • Entreprises partenaires - Centralise les profils, services proposés et niveaux d'accès des partenaires financiers
  • Activités terrain - Permet le suivi des visites, qualifications et collectes de données effectuées par les agents
  • Géographie et localisation - Définit l'organisation territoriale hiérarchique pour segmenter les zones d'intervention
  • Stockage de documents - Assure la gestion des pièces justificatives et documents liés aux entrepreneurs et activités

Avantages de cette organisation

  • Maintenance simplifiée - Chaque domaine peut être maintenu et évoluer indépendamment
  • Cloisonnement des données - Sécurité renforcée par la séparation des domaines sensibles
  • Migration facilitée - Les scripts Liquibase peuvent être organisés par domaine fonctionnel
  • Évolutivité - De nouveaux domaines peuvent être ajoutés sans impacter l'existant
  • Support multiéquipe - Différentes équipes peuvent travailler sur différents domaines en parallèle

Utilisateurs et Comptes

Cette partie du modèle gère l'authentification, les autorisations et les profils des utilisateurs du système.

account

Table centrale de gestion des comptes utilisateurs contenant les informations d'authentification.

Clé primaire: id

Champs principaux:

  • email - Adresse email (unique, validée par contrainte)
  • phone_number - Numéro de téléphone (validé par contrainte)
  • account_type - Type de compte (ADMINISTRATOR, PROVIDER, ENTERPRISE_STAFF)
  • password - Mot de passe (hashé)
  • requires_2fa, two_factor_secret - Gestion de l'authentification à deux facteurs
  • email_verified, phone_verified - État de vérification des contacts
  • is_active, deleted - Gestion du cycle de vie du compte

person

Informations personnelles associées à un compte utilisateur.

Clé primaire: account_id (clé étrangère vers account)

Champs principaux:

  • first_name, last_name - Nom et prénom
  • address - Adresse physique
  • avatar_url - URL de l'avatar
  • sexe - Genre (MALE, FEMALE)
  • birth_date - Date de naissance
  • zone_assignment - Zone géographique assignée (pour les agents)

administrator

Administrateurs système avec leurs rôles et privilèges spécifiques.

Clé primaire: id

Clés étrangères: account_id (vers account)

Champs principaux:

  • display_name - Nom d'affichage
  • dynamics_id, dynamics_role - Intégration avec systèmes externes
  • admin_role - Rôle d'administrateur (SUPER_ADMIN, VALIDATOR, SUPPORT, VIEWER)

field_agent

Agents de terrain rattachés à des entreprises partenaires.

Clé primaire: id

Clés étrangères:

  • account_id (vers account) - Compte de l'agent
  • enterprise_id (vers enterprise) - Entreprise partenaire
  • created_by (vers account) - Créateur du compte agent

Champs principaux:

  • agent_code - Code unique d'identification
  • agent_type - Type d'agent (COLLECTOR, INSPECTOR, PARTNER)
  • is_active - État d'activité

Entrepreneurs et PDE

Cette partie gère les données des entrepreneurs importées depuis PDE.CI après consentement et leurs relations avec les entreprises partenaires.

pde_entrepreneur

Données des entrepreneurs ayant donné leur consentement au partage via PDE.CI.

Clé primaire: id

Clés étrangères:

  • activity_sector_id (vers activity_sector) - Secteur d'activité
  • sector_id (vers sector) - Secteur géographique

Champs principaux:

  • activity_name, entrepreneur_name - Activité et nom
  • phone_number, company_phone_number - Contacts
  • identity_document_type, identity_document_number - Pièce d'identité
  • address, additional_address - Localisation
  • entrepreneur_certificate_path - Chemin du certificat
  • size - Taille de l'entreprise
  • gps_latitude, gps_longitude - Coordonnées GPS
  • status - État du dossier

pde_entrepreneur_enterprise_relation

Relation entre un entrepreneur PDE et une entreprise partenaire qui l'a contacté.

Clé primaire: id

Clés étrangères:

  • pde_entrepreneur_id (vers pde_entrepreneur) - Entrepreneur
  • enterprise_id (vers enterprise) - Entreprise partenaire
  • created_by (vers account) - Créateur de la relation

Champs principaux:

  • relation_status - État de la relation (PENDING, IN_PROGRESS, etc.)
  • first_contact_date, last_contact_date - Dates de contact
  • notes - Notes sur la relation

Contraintes: Unicité (pde_entrepreneur_id, enterprise_id)

Entreprises Partenaires

Cette partie du modèle gère les entreprises partenaires, leurs services et l'accès à leurs informations.

enterprise

Entreprises partenaires offrant des services financiers aux entrepreneurs.

Clé primaire: id

Clés étrangères: approved_by (vers administrator)

Champs principaux:

  • business_name - Nom commercial
  • registration_number, tax_number - Identification légale
  • web_site, logo_url - Présence en ligne
  • type - Type d'entreprise (Association, SA, SARL, etc.)
  • email, phone - Contacts
  • bank_name, bank_account_number - Informations bancaires
  • verified - État de vérification
  • status - État du processus d'approbation

enterprise_service

Services financiers proposés par les entreprises partenaires.

Clé primaire: id

Clés étrangères:

  • enterprise_id (vers enterprise) - Entreprise partenaire
  • created_by (vers account) - Créateur du service

Champs principaux:

  • service_name - Nom du service
  • service_type - Type de service (FINANCING, CONSULTING, etc.)
  • min_amount, max_amount, currency - Montants proposés
  • duration_days - Durée du service
  • eligibility_criteria - Critères d'éligibilité (JSON)
  • required_documents - Liste des documents requis
  • is_active - État d'activité

account_enterprise_access

Contrôle de l'accès des utilisateurs aux entreprises partenaires.

Clé primaire: id

Clés étrangères:

  • enterprise_id (vers enterprise) - Entreprise
  • user_account_id (vers account) - Compte utilisateur
  • granted_by (vers account) - Compte ayant accordé l'accès

Champs principaux:

  • permissions - Tableau des permissions accordées
  • is_active - État d'activité

Contraintes: Unicité (enterprise_id, user_account_id)

Activités Terrain

Cette partie gère le suivi des activités des agents sur le terrain et leurs interactions avec les entrepreneurs.

field_visit

Visites effectuées par les agents terrain auprès des entrepreneurs.

Clé primaire: id

Clés étrangères:

  • field_agent_id (vers field_agent) - Agent terrain
  • entrepreneur_id (vers pde_entrepreneur) - Entrepreneur visité

Champs principaux:

  • visit_purpose - Objectif de la visite
  • visit_outcome - Résultat
  • start_time, end_time - Période
  • gps_latitude, gps_longitude, gps_accuracy - Localisation
  • notes - Observations

entrepreneur_qualification

Qualification des entrepreneurs par les agents des entreprises partenaires.

Clé primaire: id

Clés étrangères:

  • enterprise_id (vers enterprise) - Entreprise qualifiée
  • field_agent_id (vers field_agent) - Agent qui qualifie

Champs principaux:

  • qualification_level - Niveau de qualification
  • qualification_notes - Notes détaillées
  • qualification_date - Date de qualification
  • has_valid_docs - Présence de documents valides
  • annual_turnover, business_age, employee_count - Indicateurs économiques

entrepreneur_activity

Activités proposées par les entreprises partenaires aux entrepreneurs.

Clé primaire: id

Clés étrangères:

  • entrepreneur_id (vers enterprise) - Entrepreneur
  • service_provider_id (vers enterprise) - Fournisseur de service
  • field_agent_id (vers field_agent) - Agent terrain
  • service_id (vers enterprise_service) - Service proposé
  • status_changed_by (vers account) - Compte ayant modifié le statut

Champs principaux:

  • status - État de l'activité
  • request_amount, currency - Montant demandé
  • purpose - Objectif
  • duration_days - Durée
  • notes, completion_notes - Commentaires

entrepreneur_form_response

Réponses des entrepreneurs aux formulaires de qualification.

Clé primaire: id

Clés étrangères:

  • entrepreneur_id (vers pde_entrepreneur) - Entrepreneur
  • form_id (vers service_qualification_form) - Formulaire
  • field_agent_id (vers field_agent) - Agent collecteur
  • visit_id (vers field_visit) - Visite associée

Champs principaux:

  • responses - Réponses au formulaire (JSON)
  • interested - Intérêt pour le service

Géographie et Localisation

Cette partie gère la structure géographique et administrative du territoire.

sub_prefecture

Sous-préfectures (niveau administratif supérieur).

Clé primaire: id

Champs principaux:

  • name - Nom de la sous-préfecture
  • gps_latitude, gps_longitude - Coordonnées GPS

commune

Communes au sein des sous-préfectures.

Clé primaire: id

Clés étrangères: sub_prefecture_id (vers sub_prefecture)

Champs principaux:

  • name - Nom de la commune
  • gps_latitude, gps_longitude - Coordonnées GPS

neighborhood

Quartiers au sein des communes.

Clé primaire: id

Clés étrangères: commune_id (vers commune)

Champs principaux:

  • name - Nom du quartier
  • gps_latitude, gps_longitude - Coordonnées GPS

sector

Secteurs au sein des quartiers.

Clé primaire: id

Clés étrangères: neighborhood_id (vers neighborhood)

Champs principaux:

  • name - Nom du secteur
  • gps_latitude, gps_longitude - Coordonnées GPS
  • coordinates - Définition géographique complète

activity_sector

Secteurs d'activité économique.

Clé primaire: id

Champs principaux:

  • name - Nom du secteur d'activité
  • form - Forme d'activité (SERVICE, COMMERCE)

Stockage de Documents

Cette partie gère le stockage et le suivi des documents et pièces justificatives.

document_storage

Documents associés aux entreprises.

Clé primaire: id

Clés étrangères:

  • enterprise_id (vers enterprise) - Entreprise
  • uploaded_by, verified_by, deleted_by (vers account) - Comptes

Champs principaux:

  • document_type - Type de document
  • file_name, original_name - Noms de fichier
  • file_path - Chemin d'accès
  • mime_type, file_size, file_hash - Métadonnées
  • verified, verified_at - Vérification
  • deleted, deleted_at - Suppression

activity_document

Documents associés aux activités des entrepreneurs.

Clé primaire: id

Clés étrangères:

  • activity_id (vers entrepreneur_activity) - Activité
  • uploaded_by, verified_by, deleted_by (vers account) - Comptes

Champs principaux:

  • document_type - Type de document
  • file_name, original_name - Noms de fichier
  • file_path - Chemin d'accès
  • mime_type, file_size, file_hash - Métadonnées
  • verified, verified_at - Vérification
  • deleted, deleted_at - Suppression

Types d'Énumération

Le schéma utilise plusieurs types énumérés pour garantir la cohérence des données:

Type Valeurs Description
process_status CREATED, SUBMITTED, IN_VERIFICATION, REJECTED, APPROVED Suivi des états de processus d'approbation
enterprise_type Association, SA, SARL, SARLU, OTHER Types d'entreprises reconnus
account_type ADMINISTRATOR, PROVIDER, ENTERPRISE_STAFF Types de comptes utilisateurs
admin_role SUPER_ADMIN, VALIDATOR, SUPPORT, VIEWER Rôles d'administrateurs
staff_role ADMIN, AGENT, INSPECTOR Rôles du personnel
document_type ID_CARD, BUSINESS_REGISTRATION, TAX_CERTIFICATE, OTHER_SUPPORTING_DOC Types de documents
qualification_level NOT_QUALIFIED, BASIC, INTERMEDIATE, ADVANCED, PREMIUM Niveaux de qualification
service_type FINANCING, CONSULTING, TRAINING, MARKET_ACCESS, EQUIPMENT, OTHER Types de services proposés
activity_status PENDING, INTERESTED_NOT_QUALIFIED, NOT_INTERESTED, IN_PROGRESS, NEEDS_DOCUMENTS, READY_FOR_REVIEW, COMPLETED, CANCELLED États détaillés des activités
activity_form SERVICE, COMMERCE Formes d'activité économique
enterprise_size Très petite, Petite, Moyenne, Grande Tailles d'entreprises