# Suivi de tournées de collecte

Application PWA de suivi des tournées : la feuille de route papier est
photographiée, les arrêts sont relevés automatiquement par un modèle de vision,
relus par le manager, puis pointés par l'équipage depuis son téléphone. Le
manager suit l'avancement en direct.

## Créer une tournée

Le manager choisit d'abord le mode, puis remplit un formulaire réglé dessus :
document attendu, champs, vocabulaire et modèle CSV suivent le choix. Une
feuille de route tient sur un document ; les bons se numérisent par paquets,
un par client, chacun devenant un arrêt.

## Trois modes de tournée

| Mode | Déroulé | Conclusion d'un arrêt |
|---|---|---|
| **Encombrants** | Collecte sur demande, feuille de route Grand Calais | Pointage effectué / non effectué |
| **Livraison de meubles** | Meubles vendus par la ressourcerie | Bon de livraison signé par le client, archivé en PDF |
| **Collecte de meubles** | Reprise chez le particulier | Bon de collecte signé, archivé en PDF |

Le déroulé d'une journée est suivi explicitement : **départ**, **pauses**
(vidage du camion aux bennes, repas, imprévu), **reprise**, **clôture** au
retour au dépôt. Le dernier arrêt pointé ne termine pas la tournée — il reste
à vider le camion et à rentrer.

Une tournée close reste consultable par l'équipage **dans son historique
jusqu'à la fin de la journée de travail** (`TOURS_END_OF_DAY`, 16 h 30 par
défaut), puis sort de son écran. Le manager la conserve entière et peut la
rouvrir en cas d'appui malheureux sur « Terminer ». Une tournée assignée pour
un jour suivant reste visible à tout moment.

## Rôles

Trois rôles, par droits croissants :

| | Chauffeur | Manager | Administrateur |
|---|:---:|:---:|:---:|
| Voir et pointer sa tournée (seul ou en équipage) | ✅ | — | — |
| Joindre une photo à un arrêt | ✅ | ✅ | ✅ |
| Démarrer, mettre en pause et clôturer sa tournée | ✅ | ✅ | ✅ |
| Faire signer un bon de livraison / collecte | ✅ | ✅ | ✅ |
| Importer, vérifier et valider une tournée | — | ✅ | ✅ |
| Corriger une tournée déjà validée | — | ✅ | ✅ |
| Tableau de bord, historique, export | — | ✅ | ✅ |
| Modifier un compte existant | — | ✅ ¹ | ✅ |
| Réinitialiser un mot de passe | — | chauffeurs | tous |
| Créer et supprimer un compte, attribuer les rôles | — | — | ✅ |
| Changer son propre mot de passe | ✅ | ✅ | ✅ |

¹ Sauf les comptes administrateurs, et sans pouvoir changer un rôle : sinon un
manager pourrait se promouvoir lui-même ou désactiver l'administrateur.

Chacun change son mot de passe depuis **Mon compte** ; les autres appareils
encore connectés sont alors déconnectés.

## Pile technique

| Brique | Choix | Pourquoi |
|---|---|---|
| Back-end | Laravel 13 (PHP 8.3) | Compatible CloudPanel sans configuration particulière |
| Front-end | Inertia + Vue 3 + Tailwind 4 | Une seule application, pas d'API à maintenir en double |
| Base de données | MySQL 8 | Déjà en place sur le VPS |
| Extraction | API Claude (vision), modèle `claude-opus-5` | Robuste aux photos de biais, mal éclairées, aux gabarits variables |
| Import CSV | Lecture directe, sans dépendance | Un export déjà structuré n'a pas besoin d'un modèle de vision |
| Géocodage | [API Adresse (BAN)](https://adresse.data.gouv.fr) | Gratuite, sans clé, opérée en France — pas de transfert hors UE |
| Itinéraire | OSRM + heuristique locale (plus proche voisin puis 2-opt) | Auto-hébergeable, aucun coût à l'appel |
| Temps réel | Sondage Inertia partiel (15 s) | Suffisant à cette échelle, aucun service supplémentaire à exploiter |
| Photos terrain | Réduction navigateur + file IndexedDB | Envoyables en 4G, jamais perdues en zone blanche |
| Bons signés | dompdf + signature au doigt sur canvas | PDF de 5 Ko archivé, sans dépendance externe |

Les décisions et leurs alternatives sont détaillées dans
[docs/decisions-techniques.md](docs/decisions-techniques.md).

## Installation locale

Prérequis : PHP 8.3 avec `pdo_mysql`, `gd`, `intl`, `mbstring`, `curl`, `zip`,
Composer, Node 20+, MySQL 8.

```bash
composer install
npm install
cp .env.example .env
php artisan key:generate
```

Renseigner dans `.env` la connexion MySQL puis :

```bash
php artisan migrate --seed
npm run build
php artisan serve
```

Comptes créés par le seeder (**à supprimer ou modifier avant mise en ligne**) :

| Rôle | E-mail | Mot de passe |
|---|---|---|
| Administrateur | `admin@exemple.fr` | `motdepasse` |
| Manager | `manager@exemple.fr` | `motdepasse` |
| Chauffeur | `chauffeur@exemple.fr` | `motdepasse` |

Sur une base déjà en service où aucun compte n'a le rôle administrateur :

```bash
php artisan tournees:admin responsable@exemple.fr
```

La commande promeut le compte s'il existe, sinon le crée.

Les bons signés portent l'identité de la structure, à renseigner dans `.env`
(voir `config/organisation.php`) :

```dotenv
ORG_NAME="Ressourcerie du Calaisis"
ORG_ADDRESS="…"
ORG_POSTAL_CODE=62100
ORG_CITY=Calais
ORG_PHONE="03 21 …"
ORG_SIRET=…
```

**Un bon sans raison sociale ni coordonnées n'a aucune valeur de preuve** :
ces valeurs sont à remplir avant la première livraison.

> **Le gabarit du bon est provisoire.** `resources/views/pdf/bon.blade.php`
> reprend les mentions indispensables, pas la maquette des bons déjà en usage à
> la ressourcerie. Toute la présentation tient dans ce seul fichier : le
> remplacer ne touche ni au recueil de la signature ni à l'archivage.

L'extraction des feuilles de route nécessite une clé API dans `.env` :

```dotenv
ANTHROPIC_API_KEY=sk-ant-...
```

Sans clé, l'application reste pleinement utilisable : le manager saisit les
arrêts à la main dans l'écran de vérification.

La numérisation passe par la file d'attente ; en développement, lancer :

```bash
php artisan queue:work
```

## Tests

```bash
php artisan test
```

La suite couvre le cycle complet (création, vérification, validation avec
géocodage et calcul d'itinéraire, correction d'une tournée déjà validée,
pointage, synchronisation hors-ligne, cloisonnement des trois rôles,
changement de mot de passe, affectation à un équipage, photos jointes aux
arrêts, déroulé de la tournée avec rotations de vidage, signature et génération
du bon PDF, export, purge RGPD). Les services externes sont simulés : la suite
tourne hors ligne.

## Déploiement et exploitation

Voir [docs/deploiement.md](docs/deploiement.md) — installation sur CloudPanel,
worker de file d'attente, tâche planifiée, sauvegardes, mise à jour, et le
point RGPD (durée de conservation, purge automatique).