# Fiche technique complète — FreeGive > État du projet relevé le 26 août 2026. ## 1. Identification du projet | Élément | Valeur | |---|---| | Nom fonctionnel | FreeGive | | Nature | Plateforme web de dons, d’assistance et de commerce solidaire | | Architecture | Monolithe modulaire Laravel, interfaces Web Blade et API JSON | | Backend | PHP 8.3.16, Laravel 13.18.1 | | Frontend | Blade, Tailwind CSS 4, JavaScript natif, Vite 8 | | Base active | MySQL (`fg_dbase`) | | Base de test | SQLite en mémoire | | Gestionnaire PHP | Composer 2.8.10 | | Langue de l’interface | Français | | Monnaie métier | XOF | | Fuseau actuellement configuré | UTC | | État des tests | 90 tests, 587 assertions, tous réussis | FreeGive met en relation quatre familles d’acteurs : particuliers donateurs ou bénéficiaires, organisations, marchands et administrateurs. La plateforme permet de donner ses propres biens ou services, financer une offre d’un marchand, demander une assistance, réserver un don, sécuriser sa remise et suivre les opérations. ## 2. Objectifs fonctionnels - Rendre visibles publiquement les dons disponibles et les demandes d’assistance. - Permettre à un particulier d’offrir un bien ou un service lui appartenant. - Permettre le financement d’un bien provenant du catalogue d’un marchand. - Attribuer un don privé par téléphone, e-mail ou nom complet. - Gérer la réservation et la remise avec un code et un jeton sécurisés. - Fournir aux marchands la gestion du catalogue, des stocks, des prix et des commandes. - Fournir aux organisations la gestion de leur structure, de leurs lieux et membres. - Fournir aux administrateurs la supervision, la modération et les journaux d’audit. ## 3. Profils et droits ### Particulier — Donateur / bénéficiaire Un même compte reçoit les rôles `donor` et `beneficiary`. Il peut publier un don, réserver un don public, recevoir un don privé, publier une demande d’assistance, répondre à une demande et consulter son historique. ### Organisation L’inscription crée automatiquement l’organisation, son acteur métier, son propriétaire et son lieu principal. Types pris en charge à l’inscription : établissement scolaire, centre hospitalier, ONG, association, entreprise, ministère et autre. ### Marchand L’inscription crée une organisation de type `merchant`, un point de vente principal et le rôle `merchant`. Le marchand peut gérer ses offres, prix, stocks et commandes. ### Administration Les rôles `admin` et `super_admin` ne sont jamais proposés lors de l’inscription publique. Ils doivent être attribués par une procédure administrative contrôlée. Les autres rôles disponibles comprennent `pickup_manager`. ### Acteurs métier La table `actors` découple l’identité de connexion du participant métier. Un acteur représente exclusivement un utilisateur ou une organisation. Les commandes, dons, paniers et demandes référencent ces acteurs. ## 4. Architecture applicative ```text Navigateur / client API │ ├── Interface Web Blade ── app/Http/Controllers/Web └── API JSON ───────────── app/*/Presentation/Http │ Actions métier │ Domaines et modules fonctionnels │ Repositories / modèles Eloquent │ MySQL ``` Le code suit une organisation modulaire : - `app/Core` : modèles de base, contrats, traits, objets-valeur et enums partagés. - `app/Domains/Catalog` : articles, offres, prix et stocks. - `app/Domains/Order` : paniers, commandes, réservations et exécution. - `app/Domains/Payment` : paiements, fournisseurs et webhooks. - `app/Modules/Identity` : inscription, connexion et profils utilisateurs. - `app/Modules/Actors` : identité métier des personnes et organisations. - `app/Modules/IAM` : rôles applicatifs. - `app/Modules/Organizations` : structures, membres, lieux, contacts et documents. - `app/Modules/Donation` : dons personnels ou issus de commandes, bénéficiaires et retraits. - `app/Modules/Assistance` : demandes, besoins et réponses. - `app/Modules/Notification` : notifications internes pilotées par événements. - `app/Modules/Audit` : historique des changements de statut. - `app/Modules/Moderation` : signalements, litiges, messages et pièces jointes. - `app/Modules/Administration` : agrégats et supervision administrative. Les contrôleurs restent principalement responsables de la validation HTTP et délèguent les transitions métier à des classes `Action`. Les interfaces de repositories sont liées à leurs implémentations Eloquent dans `AppServiceProvider`. ## 5. Modules fonctionnels ### Identité et inscription - Inscription et connexion Web/API. - Normalisation des e-mails, noms d’utilisateur et numéros de téléphone. - Mot de passe minimal de huit caractères avec majuscules, minuscules et chiffres. - Choix public entre particulier, organisation et marchand. - Création atomique du compte, de l’acteur, des rôles et, si nécessaire, de la structure. - Statuts de compte et middleware interdisant l’accès aux comptes inactifs. ### Catalogue et commerce - Articles de type produit ou service. - Offres rattachées à une organisation. - Prix datés, devise XOF et prix par défaut. - Inventaire, seuil d’alerte et disponibilité. - Options retrait et livraison. - Panier, lignes de panier, commande et réservation de stock. - Cycle de préparation, mise à disposition, livraison, retrait, annulation et remboursement. ### Dons Deux origines sont prises en charge : 1. `personal` : bien ou service appartenant directement au donateur ; remise directe ou via un partenaire. 2. don issu d’une commande payée : bien financé dans le catalogue d’un marchand. Un don peut être public ou attribué à un bénéficiaire précis. Pour un don privé, le bénéficiaire est recherché par téléphone, e-mail ou nom complet. En cas d’homonymie, le téléphone ou l’e-mail est exigé. États possibles : `draft`, `published`, `pending_payment`, `paid`, `reserved`, `ready`, `picked_up`, `completed`, `expired`, `cancelled`. La remise est protégée par un code à six chiffres et un jeton aléatoire de 64 caractères. Seuls leurs condensats sont conservés en base. ### Assistance communautaire - Publication d’une demande avec titre, description, ville et éléments demandés. - Brouillon ou publication publique. - Réponses des membres de la communauté. - Acceptation d’une réponse par le demandeur. - Modification, annulation et expiration. - États : `draft`, `published`, `fulfilled`, `cancelled`, `expired`. ### Paiements - Moyens déclarés : espèces, mobile money et carte. - Fournisseur espèces fonctionnel. - Mobile money actuellement fourni par un simulateur. - Fournisseur carte non configuré (`null`). - Vérification de signature et tolérance temporelle des webhooks mobile money. - Conservation des événements webhook, idempotence et reprise automatique des échecs. - Création événementielle du don après paiement réussi. - États : `processing`, `pending`, `succeeded`, `failed`, `cancelled`, `refunded`. ### Notifications - Notifications persistées en base. - Compteur de notifications non lues dans la navigation. - Marquage individuel ou global comme lu. - Notifications sur commande, paiement, attribution, réservation, disponibilité, retrait et expiration. ### Modération et audit - Signalements et litiges portant sur utilisateurs, organisations, dons, demandes, commandes ou paiements. - Messages et pièces jointes privées. - Contrôle d’accès aux dossiers. - États de modération : `open`, `under_review`, `resolved`, `rejected`. - Journal automatique des transitions de statut sur les principales ressources. - Frises chronologiques consultables via l’API. ### Administration - Tableau de bord consolidé. - Modération des utilisateurs et organisations. - Supervision des commandes, paiements, dons et demandes d’assistance. - Consultation des webhooks de paiement et du journal d’audit. - Accès protégé par authentification, statut actif et rôle administrateur. ## 6. Interfaces disponibles Le projet expose 138 routes applicatives : 60 routes Web et 78 routes API. ### Pages publiques principales | URL | Fonction | |---|---| | `/` | Accueil et indicateurs publics | | `/catalogue` | Catalogue solidaire | | `/dons` | Liste des dons publics, accessible sans connexion | | `/dons/{donation}` | Détail d’un don public ou autorisé | | `/entraide` | Liste des demandes d’assistance publiques | | `/entraide/{demande}` | Détail d’une demande | | `/connexion` | Connexion | | `/inscription` | Inscription et choix du profil | ### Espace authentifié - `/tableau-de-bord` - `/faire-un-don` - `/mes-dons/effectues` - `/mes-dons/recus` - `/mes-dons/reserves` - `/demander-de-aide` - `/mes-demandes` - `/panier` - `/notifications` - `/profil` - `/historique` ### Espaces métier - `/marchand` et `/marchand/{organisation}/*` pour les opérations marchandes. - `/administration/*` pour la supervision réservée aux administrateurs. - `/api/*` pour les intégrations et clients applicatifs. Les routes sensibles utilisent les middlewares `auth`, `active`, `admin` et des limites de débit, notamment 10 requêtes par minute sur les écritures exposées. ## 7. Modèle de données La base est construite par 36 migrations. | Groupe | Tables principales | |---|---| | Identité | `users`, `user_profiles`, `roles`, `user_roles`, `actors` | | Organisations | `organizations`, `organization_locations`, `organization_contacts`, `organization_members`, `organization_documents` | | Catalogue | `catalog_items`, `offers`, `offer_inventories`, `offer_prices` | | Commerce | `carts`, `cart_items`, `orders`, `order_items`, `reservations` | | Paiement | `payments`, `payment_webhook_events` | | Dons | `donations`, `donation_items`, `donation_beneficiaries`, `donation_pickups` | | Assistance | `assistance_requests`, `assistance_request_items`, `assistance_responses` | | Gouvernance | `notifications`, `audit_entries`, `moderation_cases`, `moderation_case_messages`, `moderation_case_attachments` | | Infrastructure | `sessions`, `cache`, `cache_locks`, `jobs`, `job_batches`, `failed_jobs`, `password_reset_tokens` | Les clés internes sont numériques. Les ressources exposées utilisent selon les cas des UUID ou ULID. Les contraintes étrangères, index, suppressions logiques et contraintes d’unicité assurent l’intégrité des relations critiques. ## 8. Sécurité - Protection CSRF sur les formulaires Web. - Sessions et files d’attente persistées en base. - Hachage Laravel des mots de passe. - Validation systématique avec `FormRequest` ou validation contrôleur. - Autorisation par propriétaire, membre d’organisation, acteur participant et rôles. - Limitation de débit sur l’authentification et les opérations sensibles. - Réponses API structurées en JSON, y compris pour les erreurs. - En-têtes globaux : CSP, HSTS sous HTTPS, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy` et `Cross-Origin-Opener-Policy`. - Pages personnalisées 403, 404, 419, 429, 500 et 503. - Secrets webhook fournis par variables d’environnement. - Pièces de modération servies après contrôle d’accès. - Rôle administrateur non auto-attribuable à l’inscription. ## 9. Traitements asynchrones et planifiés La connexion de file recommandée est `database`. Un worker doit tourner en permanence : ```bash php artisan queue:work --tries=3 ``` Deux tâches sont exécutées chaque minute avec verrou anti-chevauchement : - `lifecycle:expire --limit=500` : expiration des commandes impayées, dons publics et demandes d’assistance. - `payments:webhooks:retry --limit=100` : reprise des webhooks en échec sous la limite configurée. Le serveur doit appeler `php artisan schedule:run` chaque minute. ## 10. Configuration Variables essentielles : ```dotenv APP_NAME=FreeGive APP_ENV=production APP_DEBUG=false APP_URL=https://votre-domaine APP_LOCALE=fr APP_FALLBACK_LOCALE=fr DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=fg_dbase DB_USERNAME= DB_PASSWORD= SESSION_DRIVER=database SESSION_SECURE_COOKIE=true QUEUE_CONNECTION=database CACHE_STORE=database MOBILE_MONEY_WEBHOOK_SECRET= PAYMENT_WEBHOOK_TOLERANCE_SECONDS=300 PAYMENT_WEBHOOK_RETRY_MAX_ATTEMPTS=10 ``` Ne jamais versionner le fichier `.env`. L’instance locale observée utilise encore le nom `Laravel`, la locale `en`, le mode debug actif et l’URL `localhost`. Ces valeurs sont acceptables en développement mais doivent être corrigées avant livraison. ## 11. Installation locale ```bash composer install cp .env.example .env php artisan key:generate php artisan migrate --seed npm install --ignore-scripts npm run build composer run dev ``` Sous PowerShell : ```powershell Copy-Item .env.example .env npm.cmd run build ``` ## 12. Déploiement ```bash composer install --no-dev --optimize-autoloader npm ci npm run build php artisan migrate --force php artisan optimize php artisan queue:restart php artisan ops:check --production ``` Le déploiement doit également assurer HTTPS, la persistance du stockage, les sauvegardes MySQL, la supervision du worker et la tâche cron Laravel. ## 13. Tests et qualité - PHPUnit 12.5. - 26 fichiers de tests fonctionnels et un socle unitaire. - Base SQLite en mémoire pour l’isolation. - 90 tests et 587 assertions réussis lors du présent relevé. - Scénarios couverts : identité, profils, organisations, catalogue, commande, paiement, webhooks, dons, assistance, notifications, audit, modération, administration, sécurité HTTP et commande de diagnostic. Commandes de validation : ```bash php artisan test vendor/bin/pint --test npm run build php artisan view:cache php artisan ops:check --production ``` Le contrôle Pint global peut encore relever du formatage historique dans d’anciens fichiers du socle ; les fichiers fonctionnels récemment modifiés sont conformes. ## 14. Exploitabilité et supervision La commande suivante contrôle les prérequis essentiels : ```bash php artisan ops:check --production ``` Elle vérifie notamment la clé applicative, le mode debug, la file d’attente, le secret mobile money, la connexion SQL, les tables critiques, les cookies sécurisés et la présence de jobs échoués. Éléments à surveiller : - profondeur de la table `jobs` ; - entrées dans `failed_jobs` ; - webhooks au statut d’échec ; - paiements bloqués en attente ; - commandes, dons et demandes expirés ; - erreurs HTTP 5xx ; - espace disque des journaux et pièces jointes ; - disponibilité MySQL et durée des sauvegardes. ## 15. Identité visuelle et ergonomie - Palette principale : vert `#087f5b`, vert foncé `#07543f`, bleu `#1769e0`, vert fluor `#7cff00`. - Interface responsive pour ordinateur, tablette et mobile. - Tableau de bord particulier centré sur deux actions : « Faire un don » et « Demander une assistance ». - Navigation latérale : tableau de bord, dons effectués, reçus, réservés et aide. - Navigation horizontale publique : catalogue, dons publics et demandes d’assistance. - Navigation authentifiée : marchands, notifications, panier et menu profil. - États de focus visibles, lien d’évitement et prise en charge de la réduction des animations. ## 16. Limites et recommandations 1. Le mobile money repose actuellement sur un fournisseur simulé : intégrer le fournisseur réel avant encaissement en production. 2. Le paiement par carte est déclaré mais ne possède pas encore de fournisseur. 3. Ajouter la vérification d’adresse e-mail et, si nécessaire, de téléphone. 4. Prévoir un processus formel d’attribution et de révocation des rôles administratifs. 5. Ajouter une politique de conservation des pièces jointes, audits et données personnelles. 6. Ajouter une solution de stockage objet et antivirus si le volume de pièces jointes augmente. 7. Mettre en place CI/CD, analyse statique PHP et mesure de couverture. 8. Configurer une solution d’e-mail ou SMS réelle pour les notifications externes. 9. Documenter et publier un contrat OpenAPI pour les 78 routes API. 10. Aligner le `.env` local avec `APP_NAME=FreeGive`, `APP_LOCALE=fr` et le fuseau métier retenu. ## 17. Critères de préparation à la production - Toutes les migrations sont appliquées. - `php artisan test` et `npm run build` réussissent. - `php artisan ops:check --production` réussit. - `APP_DEBUG=false`, HTTPS et cookies sécurisés sont actifs. - Le fournisseur de paiement réel et son secret webhook sont configurés. - Le worker, le scheduler, les sauvegardes et la supervision sont actifs. - Un compte administrateur initial est créé par une procédure sécurisée. - Les mentions légales, règles de confidentialité et conditions d’utilisation sont publiées.