# LabConnect — Plateforme de gestion des demandes (prélèvement, consommable, réclamation, résultats) Application Laravel avec 3 espaces : **Admin**, **Partenaire** (labo/clinique), **Agent de collecte**. > 📘 Ce fichier est le guide **technique** (installation, déploiement, architecture). > Pour la formation des utilisateurs (partenaires, agents de collecte, administrateur), voir > **`GUIDE_UTILISATEUR.md`** — un guide simple, sans jargon technique. Une aide contextuelle > est aussi disponible directement dans l'application (menu **❓ Aide**). ## ⚠️ Étape obligatoire avant tout : installer les dépendances (composer) Ce zip contient tout le code de l'application, **sauf le dossier `vendor/`** (les librairies Laravel elles-memes), qui doit etre genere par `composer install`. C'est la methode standard de deploiement Laravel. ### Option A — Composer est disponible en SSH sur votre hebergement mutualise ```bash cd labconnect composer install --no-dev --optimize-autoloader cp .env.example .env php artisan key:generate ``` ### Option B — Composer n'est PAS disponible sur le serveur (SSH restreint) Faites-le en local (sur votre PC, avec Composer installe : https://getcomposer.org) : ```bash composer install --no-dev --optimize-autoloader ``` Cela cree un dossier `vendor/`. Uploadez ensuite CE dossier `vendor/` par FTP dans `labconnect/vendor/` sur le serveur (peut prendre du temps vu le nombre de fichiers — un zip + extraction via SSH `unzip` est plus rapide si possible). ## Configuration du fichier .env Copiez `.env.example` en `.env` et renseignez au minimum : ``` APP_URL=https://votre-domaine.tn DB_DATABASE=nom_de_votre_base DB_USERNAME=utilisateur_mysql DB_PASSWORD=mot_de_passe_mysql ``` Puis generez la cle d'application : ```bash php artisan key:generate ``` ## Base de donnees Creez une base MySQL vide depuis votre panel d'hebergement (cPanel/Plesk), puis : ```bash php artisan migrate php artisan db:seed ``` Le seeder cree automatiquement 3 comptes de test : | Role | Email | Mot de passe | |---|---|---| | Admin | admin@labconnect.tn | ChangeMoi123! | | Partenaire (golden customer) | partenaire@labconnect.tn | ChangeMoi123! | | Agent de collecte | coursier@labconnect.tn | ChangeMoi123! | **Changez ces mots de passe des la premiere connexion** (depuis l'espace admin > Comptes, ou directement en base). ## Lien de stockage (photos de collecte) ```bash php artisan storage:link ``` Si cette commande echoue (restrictions symlink sur mutualise), copiez manuellement le contenu de `storage/app/public/` vers `public/storage/` apres chaque nouvelle photo, ou contactez votre hebergeur pour l'activation des liens symboliques. ## Configuration du document root (IMPORTANT) Laravel doit avoir comme **document root le dossier `public/`**, pas la racine du projet. - **Si votre panel permet de choisir le document root** (souvent le cas via cPanel > "Domains") : pointez-le vers `labconnect/public`. C'est la methode recommandee, rien d'autre a faire. - **Si vous ne pouvez pas changer le document root** (cas frequent en mutualise strict) : utilisez les fichiers fournis `index_root_option_shared_hosting.php` et `htaccess_root_option_shared_hosting.txt`. Les instructions detaillees sont commentees directement dans `index_root_option_shared_hosting.php`. ## Permissions (si SSH le permet) ```bash chmod -R 775 storage bootstrap/cache ``` ## Optimisation en production ```bash php artisan config:cache php artisan route:cache php artisan view:cache ``` ⚠️ Si vous modifiez le `.env` ensuite, executez `php artisan config:clear` avant de relancer `config:cache`. ## Structure fonctionnelle **Espace Partenaire** (`/partner`) : 4 menus — demande de prelevement, demande de consommable, reclamation, demande de resultats. Chaque demande cree un enregistrement traçable avec historique. **Espace Admin** (`/admin`) : creation/gestion des comptes partenaires et agents de collecte, vue globale de toutes les demandes avec filtres, assignation des agents de collecte, detection automatique des ecarts de quantite. **Espace Agent de collecte** (`/courier`) : liste des demandes assignees, confirmation de collecte (avec quantite reelle + photo optionnelle), signalement d'indisponibilite, confirmation de livraison au laboratoire. **Point cle anti-perte d'analyse** : le statut "collecte" ne peut etre declenche QUE par le agent de collecte, jamais par le partenaire. Si la quantite reellement collectee differe de la quantite demandee, le systeme bascule automatiquement la demande en statut "Ecart detecte", visible immediatement par l'admin — sans attendre une reclamation du client. ## Mise à jour : gestion complète des partenaires et agents de collecte depuis l'administration Espace **Admin > Partenaires** et **Admin > Comptes** : chaque fiche dispose maintenant d'un bouton « Modifier » permettant de changer les coordonnées ET le compte de connexion (email/login + mot de passe) directement depuis l'interface, sans passer par la base de données. ## Mise à jour : configuration email — solution Brevo (résout le blocage OVH) **Contexte** : sur l'hébergement mutualisé OVH (`capara.tn`), les connexions SMTP sortantes sont bloquées par le pare-feu (y compris vers les serveurs mail d'OVH eux-mêmes), et le service local `sendmail`/`mail()` de PHP nécessite l'activation du service **« Scripts e-mail »** dans le manager OVH — un service parfois capricieux ou lent à activer selon l'hébergement. **Solution retenue : Brevo (ex-Sendinblue), via son API HTTP.** Contrairement au SMTP, une requête HTTP (port 443, HTTPS) n'est jamais bloquée par un hébergeur — c'est le même protocole que n'importe quel appel à une API tierce. Brevo offre 300 emails/jour gratuits, sans carte bancaire. ### Configuration 1. Créez un compte sur [brevo.com](https://www.brevo.com) (gratuit). 2. Menu **SMTP & API > API Keys** > créez une nouvelle clé API. 3. Dans `.env` sur le serveur : ```env MAIL_MAILER=brevo BREVO_API_KEY=votre_cle_api_brevo MAIL_FROM_ADDRESS="qualite@labobouaicha.com" MAIL_FROM_NAME="LabConnect" ``` 4. **Important** : dans Brevo, allez dans **Expéditeurs & IP > Expéditeurs** et ajoutez/validez `qualite@labobouaicha.com` comme expéditeur autorisé (Brevo envoie un email de confirmation à cette adresse, ou demande une validation DNS — sinon vos emails partiront avec un expéditeur générique Brevo, moins professionnel). 5. `php artisan config:clear` ### Test ```bash php test_mail.php ``` (le script créé pendant le diagnostic — sinon, recréez-le comme indiqué plus haut dans cette conversation). ### Solutions alternatives (si vous ne voulez pas utiliser Brevo) - `MAIL_MAILER=phpmail` — fonction `mail()` native PHP. Nécessite que le service **« Scripts e-mail »** soit actif dans le manager OVH, sur l'hébergement exact qui contient `capara.tn` (attention si vous avez plusieurs hébergements OVH sur le même compte, comme rencontré pendant la mise en place — vérifiez bien lequel correspond à `capara.tn` avant d'activer). - `MAIL_MAILER=sendmail` — nécessite un binaire `sendmail` compatible mode `-bs`, souvent absent sur mutualisé. - `MAIL_MAILER=smtp` — nécessite un SMTP non bloqué par l'hébergeur (rarement le cas sur OVH mutualisé). ## Mise à jour : notification WhatsApp automatique des agents de collecte (API officielle Meta) À chaque nouvelle demande créée par un partenaire, un message WhatsApp est envoyé automatiquement à tous les agents de collecte actifs ayant un numéro de téléphone renseigné (fiche agent > Modifier > Téléphone, format international recommandé : `+216 XX XXX XXX`). Le message contient le partenaire, le type de demande, la quantité annoncée, et un **bouton qui ouvre un lien de confirmation en un tap** — l'agent peut confirmer la collecte directement depuis WhatsApp, sans se connecter à l'application. Le premier agent qui confirme prend automatiquement la demande en charge. Cette fonctionnalité utilise l'**API officielle WhatsApp Cloud** de Meta — fiable, sans risque de suspension de numéro (contrairement aux méthodes non-officielles), mais nécessite une configuration préalable côté Meta Business Manager. ### Configuration requise (compte Meta Business) 1. Créez un compte [Meta Business Manager](https://business.facebook.com) et y ajoutez un produit **WhatsApp**. 2. Obtenez un **numéro de téléphone WhatsApp Business** (numéro dédié, différent de votre numéro personnel). 3. Générez un **jeton d'accès permanent** (Système d'utilisateurs > jeton avec la permission `whatsapp_business_messaging`). 4. Notez le **Phone Number ID** (visible dans le tableau de bord WhatsApp de Meta Business Manager). 5. Créez et faites approuver un **template de message** (obligatoire pour tout message initié par l'entreprise). Le template doit contenir : - Un corps de message avec 3 variables : `{{1}}` = nom du partenaire, `{{2}}` = type de demande, `{{3}}` = quantité. Exemple : *"Nouvelle demande chez {{1}} : {{2}}, {{3}} échantillon(s) annoncé(s)."* - Un **bouton de type "URL"** (dynamique) pointant vers `https://votre-domaine.tn/{{1}}`. - Soumettez le template dans Meta Business Manager > WhatsApp Manager > Modèles de message ; l'approbation prend généralement quelques heures à 1-2 jours. 6. Renseignez dans `.env` sur le serveur : ```env WHATSAPP_ENABLED=true WHATSAPP_TOKEN=votre_jeton_permanent WHATSAPP_PHONE_NUMBER_ID=votre_phone_number_id WHATSAPP_TEMPLATE_NAME=nom_exact_du_template_approuve WHATSAPP_TEMPLATE_LANG=fr ``` 7. `php artisan config:clear` **Tant que `WHATSAPP_ENABLED=false` (valeur par défaut)**, l'application fonctionne normalement sans tenter d'envoyer de message — aucune demande n'est bloquée par l'absence de configuration WhatsApp. > Une méthode non-officielle (Baileys/WhatsApp Web, sans validation Meta) a été explorée précédemment > dans le projet séparé `labconnect-whatsapp-bot` ; elle reste utilisable si besoin, mais comporte un > risque de bannissement du numéro. L'API officielle Meta ci-dessus est la méthode recommandée pour > un usage professionnel durable. ## Mise à jour : correction orthographique (accents) L'ensemble des textes affichés à l'écran (libellés, boutons, messages) a été relu et corrigé pour respecter l'orthographe française avec accents. Les valeurs techniques stockées en base de données (statuts internes comme `assigne`, `collecte`, `litige`, noms de route, noms de colonnes) restent volontairement sans accent — ce sont des identifiants techniques invisibles pour l'utilisateur final, les modifier casserait l'application. ## Mise à jour : processus de validation des ecarts (2 niveaux) **Niveau 1 — au ramassage (par demande)** : quand le agent de collecte confirme une collecte, le systeme compare la quantite reellement collectee a la quantite annoncee par le partenaire. - **Ecart positif** (plus collecte qu'annonce) : simple information, la demande continue son cycle normalement. - **Ecart negatif** (moins collecte qu'annonce) : la demande passe en statut *"Ecart au ramassage"* et est **bloquee** — elle ne peut pas etre livree tant qu'un admin ne l'a pas validee (espace Admin > Validations). L'admin peut approuver (la demande repart dans le cycle normal) ou escalader en litige (investigation manuelle hors application). **Niveau 2 — au depot au laboratoire (lot de livraison)** : le agent de collecte ne livre plus demande par demande, mais regroupe toutes ses collectes de la journee dans un "lot" (Agent de collecte > Livrer au laboratoire), selectionne les demandes concernees, et declare le **total physiquement remis au labo**. - Si le total declare correspond exactement a la somme des quantites collectees individuellement : le lot est valide automatiquement, toutes les demandes passent a "Livre". - Si le total ne correspond pas (ex: agent de collecte a collecte 2+3+7=12 chez 3 partenaires mais declare 10 au depot) : le lot passe en **"Ecart critique"**, toutes les demandes du lot sont bloquees, et l'admin doit investiguer (espace Admin > Validations > lot concerne) : recomptage physique, ajustement des quantites finales par demande, commentaire de resolution obligatoire, puis cloture du lot. Migrations associees : `2026_07_06_000001_create_delivery_batches_table.php` et `2026_07_06_000002_add_validation_fields_to_service_requests_table.php`. Executez `php artisan migrate` apres avoir mis a jour le code sur le serveur. ## Prochaines etapes suggerees 1. Tester le parcours complet avec le golden customer (Clinique Pilote Nabeul, deja cree par le seeder). 2. Ajuster les champs des formulaires selon les retours terrain. 3. Ajouter des notifications email/SMS automatiques sur les ecarts detectes. 4. Envisager la version application mobile pour le agent de collecte une fois le workflow valide.