pardis/README.fr.md

Pardis

PWA hors ligne de suivi des heures de chantier. Tant que l’application est ouverte, elle peut démarrer automatiquement la journée et proposer sa clôture. Chaque tâche commence là où la précédente s’est terminée. Les journées clôturées ont un récapitulatif concis, prêt à être recopié dans un registre papier.

Version actuelle de l’application : 1.0.0.

Conçue pour l’extérieur : contraste élevé, grandes zones tactiles et utilisable avec des gants. Les données sont enregistrées localement dans IndexedDB. Une synchronisation facultative chiffrée de bout en bout les partage entre appareils autorisés, sans inscription par e-mail ni mot de passe.

Version anglaise : README.md.

Développement

npm install
npm run dev      # http://localhost:5173
npm test         # tests unitaires et de régression IndexedDB
npm run check    # vérification Svelte
npm run build    # build de production dans dist/
npm run validate # tests, vérification Svelte et build complet de la PWA
npx playwright install chromium # installer le navigateur pour les tests UI
npm run test:e2e # profils vierges, données synthétiques et test PWA hors ligne
npm run validate:all # inclure les tests navigateur dans la validation complète

Exporter et importer les données

Dans Réglages → Gérer les données et sauvegardes, l’écran Données et sauvegardes regroupe l’export, l’import, la vérification des sauvegardes et la durée de conservation. Le rappel Sauvegarder ouvre aussi cet écran.

Les données restent disponibles dans le navigateur sur cet appareil. La synchronisation chiffrée peut être activée séparément pour les partager avec vos autres appareils. Effacer les données du site ou perdre l’appareil peut faire perdre l’historique : gardez une copie vérifiée du fichier exporté sur un autre support.

Exporter les données télécharge un fichier pardis-AAAA-MM-JJ.json. Il contient toutes les journées conservées, leurs postes et les réglages enregistrés. L'export fonctionne hors ligne et ne modifie pas les données de l'appareil. Les identifiants internes des postes sont recréés à l'import.

Pour restaurer une sauvegarde, choisissez Importer un fichier… puis vérifiez le nom du fichier, les compteurs et les éventuels ajustements signalés. Deux modes sont disponibles :

• Fusionner ajoute seulement les dates absentes. Une date déjà présente est conservée intégralement, même si le fichier contient une autre version de ses postes. Les réglages locaux sont conservés. Importer deux fois le même fichier ne crée pas de doublons.
• Remplacer tout demande une confirmation, puis remplace toutes les journées, tous les postes et les réglages, y compris une journée locale en cours. Si le fichier ne contient pas de réglages, les valeurs par défaut sont rétablies.

Les journées importées sont enregistrées comme terminées. Pour une journée exportée en cours, le dernier poste est arrêté à l'heure de l'export : le temps écoulé est conservé. Les intervalles sans travail déjà présents sont conservés. Une sauvegarde vide est valide et peut servir à restaurer un appareil vide.

Le format JSON est identifié par format: "timelog-export" et version: 2. Le format v1 reste importable. Les anciennes applications refusent le format v2 pour éviter de transformer les pauses en travail. Les fichiers étrangers, versions non prises en charge, dates en double et réglages invalides sont refusés. Les postes inutilisables et les corrections de plages horaires sont signalés avant confirmation. La limite de taille est de 20 Mo. L'écriture est transactionnelle : un échec annule le remplacement ou la fusion dans son intégralité. Le récapitulatif, le thème et les suggestions sont ensuite actualisés sans recharger la page.

Dans Durée de conservation, Conserver (jours) détermine les journées anciennes proposées à la purge. Modifier cette durée ne supprime rien ; la purge automatique est désactivée. L’historique conservé alimente les suggestions et les statistiques. La dernière journée terminée et les journées actives sont conservées.

Purger maintenant présente les dates concernées et demande confirmation. Une sauvegarde locale est conservée avant la suppression ; Récupérer la sauvegarde avant purge permet de la fusionner ou de remplacer les données, puis de l’exporter après restauration. Cette copie est remplacée à la prochaine purge et disparaît si les données du site sont effacées : un fichier externe reste nécessaire.

Les tests d'import/export couvrent le format, les réglages, la fidélité des durées, les fichiers invalides, la fusion, le remplacement et l'annulation transactionnelle sur une IndexedDB simulée. src/lib/fixtures/backup.json est le jeu d'essai fourni ; il n'est pas publié avec l'application.

Journées, reprise et historique

• Une journée oubliée est clôturée au retour dans l'application, à son heure de fin prévue (prolongations comprises), sans jamais précéder la dernière activité enregistrée. Cette heure est une estimation : l'application ne mesure pas le travail lorsqu'elle est fermée. Le dernier poste conserve ainsi sa durée jusqu'à cette limite, au lieu d'être ramené à zéro.
• Une journée terminée aujourd’hui propose Reprendre la journée avec confirmation : prolonger le dernier poste, ou créer une pause jusqu’à maintenant (choix initial). Un dernier repas ou une pause garde sa nature ; le travail reprend dans un nouveau poste. Les journées passées se corrigent par Voir les détails → Corriger cette journée.
• La création, la clôture et la reprise sont transactionnelles. Les actions simultanées sur le même poste ne créent pas de doublons ; une journée clôturée ne peut pas recevoir un nouveau poste actif. La purge épargne les journées actives et conserve toujours la dernière journée terminée.
• Les horaires de déjeuner affichent un rappel puis une heure indicative de reprise. Les transitions restent manuelles sauf si l'option Pause déjeuner est activée dans les automatismes.
• Dans Récap, le sélecteur Journée à consulter permet d'afficher et de copier chaque journée terminée encore conservée, y compris les journées importées.

Les tests couvrent notamment les clôtures oubliées, les reprises, les appels concurrents, les retours d'horloge, les échecs transactionnels et la conservation.

Automatismes

Dans Réglages → Automatismes, chaque comportement a son interrupteur :

Option	Comportement
Ouverture	Démarrer aux horaires et jours prévus. Activée par défaut, comme auparavant.
Début de journée	Au bouton « Arrivé sur site », proposer la dernière tâche de travail de la précédente journée enregistrée, hors repas et transport.
Pause déjeuner	Ouvrir la pause à l'heure habituelle et reprendre la tâche précédente après la durée réglée. Reprendre le type de repas et le restaurant de la précédente journée enregistrée.
Arrivée sur chantier	Lors du repas automatique, transformer un transport initial non renseigné en un transport de 1/5/15/30 minutes, selon l'arrondi, suivi de la tâche précédente.
Fin de demi-journée	À la pause ou à la clôture, remplacer une plage automatique non renseignée par la dernière tâche de travail connue. Conserver tout poste manuel.
Fin de journée	Clôturer à l'heure prévue sans confirmation.

Les cinq nouvelles options sont désactivées par défaut. Elles sont conservées dans les sauvegardes et rétablies lors d'un import en remplacement. L'option Arrivée sur chantier intervient seulement avec un repas automatique. Sans cette estimation de transport, Fin de demi-journée peut remplacer le transport initial non renseigné par du travail sur toute la plage. Une tâche de travail déjà présente suffit : aucun doublon n'est ajouté à la demi-journée.

« Précédente » désigne la dernière journée terminée enregistrée avant la date courante, y compris après un week-end. La complétion utilise la dernière tâche de travail connue ; sans historique de travail, elle utilise Travaux sur site. Les postes produits automatiquement portent la mention Auto. Les corriger les rend manuels et les protège des déductions suivantes. Les saisies anciennes sans cette information sont considérées comme manuelles.

Une pause commencée ou corrigée manuellement n'est pas terminée par l'automatisme de déjeuner. Un choix manuel du type ou du restaurant est conservé. Une pause supprimée n'est pas recréée. Désactiver l'option arrête les transitions suivantes ; cela ne supprime pas les postes déjà enregistrés. Une durée de déjeuner nulle n'ajoute aucune pause automatique. La durée d'une pause automatique déjà commencée est conservée si le réglage change ensuite.

L'app vérifie l'horloge toutes les 30 secondes et au retour à l'écran. Une PWA fermée ou suspendue ne peut pas exécuter du code à heure fixe : à la réouverture, les étapes manquées sont rattrapées avec leurs horaires prévus, sans écraser une action manuelle plus tardive. Les journées déjà clôturées restent intactes et les dates entièrement absentes ne sont pas créées. Pour une journée sans intervention, activer les options voulues et ouvrir l'app au moins une fois pour cette journée.

Les prolongations et la reprise d'une journée sont respectées. Un démarrage manuel laisse au moins une heure avant une clôture automatique. Les transitions automatiques sont transactionnelles : une erreur annule toute l'opération et des appels simultanés ne créent pas de doublons.

Jours non travaillés

Dans Réglages → Jours non travaillés, ajouter les dates à bloquer à l'avance. La liste est triée par date ; chaque date peut être modifiée ou supprimée. Les doublons sont refusés. Ces exceptions priment sur les jours de semaine habituellement travaillés et empêchent l'ouverture automatique, y compris lors du rattrapage à la réouverture de l'app ou hors ligne.

Aucune journée ni aucun poste n'est créé pour une date bloquée. Les journées déjà commencées ou terminées restent conservées. Dans Journée, le bouton Démarrer quand même permet un démarrage manuel exceptionnel. Retirer une date rétablit les règles habituelles de démarrage automatique.

La liste est enregistrée avec les réglages et incluse dans l'export des données. Un import en remplacement rétablit la liste de la sauvegarde ; un import en fusion conserve la liste locale, comme les autres réglages. Une ancienne sauvegarde sans cette liste la réinitialise à vide lors d'un remplacement.

Corriger les postes et les journées terminées

Le Total des heures de présence exclut les pauses et le repas. Le repas reste affiché séparément dans le récapitulatif et le texte copié. Les totaux suivent le réglage d’arrondi existant.

Dans Journée, touchez un poste dans Postes de la journée pour modifier son début, sa fin, sa tâche ou son client. Les boutons Poste ordinaire, Repas et Pause permettent de choisir la nature du poste. Le type interne d'un transport déjà enregistré est conservé quand on corrige ses horaires ou son libellé. Les sélecteurs d'heure ne proposent pas de date : ils conservent la date du poste. Les minutes et les boutons d'ajustement suivent l'arrondi choisi dans les réglages (1, 5, 15 ou 30 minutes). Les tâches, clients et restaurants utilisent les mêmes suggestions et la même saisie libre que l'écran de la journée. Les corrections sont enregistrées ensemble avec Enregistrer. Annuler ne modifie rien ; ouvrir puis valider un horaire inchangé conserve sa valeur enregistrée. Le début du premier poste et la fin du dernier définissent les bornes de la journée. Modifier une limite intermédiaire ajuste la limite du poste voisin, sans chevauchement. La fin d'un poste encore en cours reste pilotée par les boutons de changement de tâche ou de clôture.

Ajouter un poste oublié permet de choisir une plage existante puis les horaires du poste à insérer dans cette plage. Le début et la fin sont préremplis avec les deux bornes connues (jusqu'à l'heure actuelle pour un poste en cours). Il suffit de changer une seule borne pour corriger le début ou la fin de la plage. Les portions avant et après sont conservées avec leur tâche et leur client. Par exemple, un poste 08:00–12:00 peut devenir 08:00–09:00, une tâche oubliée 09:00–10:00, puis 10:00–12:00. Le bouton Repas permet aussi d’ajouter un déjeuner oublié et de renseigner panier ou restaurant ; Pause ajoute une pause hors repas. Pour ajouter juste après une frontière existante, choisissez le poste qui commence à cette frontière.

Dans Récap, choisissez la date puis Voir les détails → Corriger cette journée : les mêmes actions sont disponibles sans réouverture, même si une autre journée est en cours. Le récapitulatif et son texte à copier sont recalculés après chaque enregistrement. La suppression d'un poste demande confirmation ; le voisin absorbe sa durée, et le dernier poste d'une journée ne peut pas être supprimé. Supprimer un repas réaffecte sa durée au poste voisin et peut donc changer le total des heures de présence.

Chaque correction est transactionnelle. Les horaires inversés, les insertions hors de la plage choisie et les formulaires devenus périmés après une autre modification sont refusés sans écriture partielle.

Statistiques

Ouvrez Réglages → Consulter les statistiques. Le bouton Stats de la barre du bas n'apparaît que sur cette page ; les autres écrans gardent leurs trois boutons habituels. La page fonctionne hors ligne. Les calculs de statistiques restent sur l’appareil ; la synchronisation facultative peut partager leur historique source chiffré.

Les filtres couvrent tout l'historique, le mois, l'année, les 30 derniers jours ou une plage de dates inclusive. Les journées en cours sont exclues par défaut. L'option pour les inclure affiche des cumuls et détails provisoires. Les moyennes de « Repères et observations », la médiane, les extrêmes et les profils par jour de semaine restent calculés sur les seules journées terminées enregistrées.

Les statistiques présentent :

• Les heures de présence hors repas et pauses, les pauses, le transport identifié, les nombres de journées, postes, tâches et clients.
• Les heures de présence par client et par tâche, leurs parts des heures de présence, les nombres de journées concernées et les détails croisés, accessibles en ouvrant une ligne.
• L'évolution par mois ou semaine, sans inventer des heures pour les jours absents.
• Les journées avec repas panier ou restaurant, les restaurants fréquentés, les durées de pause et les journées sans pause enregistrée. Plusieurs fragments de repas le même jour ne créent pas plusieurs journées de repas.
• Les moyennes, la médiane, les journées extrêmes, les principales concentrations de temps par client et tâche, et le détail quotidien.
• Les clients ou restaurants non renseignés, les postes à zéro après arrondi, les journées vides, les plages non couvertes et les chevauchements éventuels.

Le calcul reprend l'arrondi du récapitulatif et exclut toujours le repas et les pauses des heures de présence. Seules les données encore conservées sont analysées : les jours absents ou purgés ne permettent pas de conclure à une absence de travail. Le transport identifié repose sur le type enregistré, pas sur une déduction à partir du nom de la tâche.

En développement, la console expose timelog.seed() pour générer 20 jours d’historique réaliste (utile pour tester le moteur de suggestions) et timelog.wipe() pour l’effacer.

Déploiement

La pile comprend l’application statique servie par Caddy et une API de synchronisation facultative adossée à SQLite dans un volume persistant. Caddy obtient et renouvelle le certificat HTTPS. La synchronisation reste désactivée dans chaque client jusqu’à son activation explicite. Voir SYNC.md pour l’association, le chiffrement, la récupération, les quotas et les sauvegardes du serveur.

cp .env.example .env
$EDITOR .env          # renseigner SITE_ADDRESS, ACME_EMAIL et TRUST_PROXY
docker compose up -d --build

Prérequis :

• SITE_ADDRESS doit déjà pointer vers le serveur.
• ACME_EMAIL est obligatoire et doit être une adresse de contact valide.
• Les ports 80 et 443 doivent être accessibles depuis Internet. Le port 80 est obligatoire : le défi ACME l’utilise pour vérifier la propriété du domaine.

Les certificats sont stockés dans le répertoire monté ./caddy/data. Conservez-le : sans lui, Caddy redemande un certificat à chaque recréation et atteindra la limite de requêtes de Let's Encrypt après quelques redémarrages.

Pour mettre à jour, récupérez les changements et reconstruisez l’image :

git pull && docker compose up -d --build

Les clients déjà ouverts ne se rechargent pas seuls. Chaque application vérifie toutes les heures si une nouvelle version est disponible et affiche une bannière « Installer », uniquement lorsqu’aucune journée n’est en cours, afin qu’une mise à jour n’interrompe jamais une journée de travail.

HTTPS est obligatoire

Les navigateurs n’enregistrent un service worker que dans un contexte sécurisé. En http:// simple, sur une adresse IP ou un nom d’hôte, l’application se charge mais n’a pas de fonctionnement hors ligne, ne peut pas être installée et ne se met jamais à jour - ce qui annule l’intérêt de sa conception. localhost est la seule exception, d’où le fonctionnement de npm run dev sans certificat.

Derrière un reverse proxy existant

La configuration Caddy actuelle termine elle-même TLS et accepte le protocole PROXY depuis l’adresse ou le CIDR défini dans TRUST_PROXY. Indiquez l’adresse réelle du proxy amont ; 192.0.2.10/32 dans .env.example est une valeur fictive de documentation. LISTEN_IP sélectionne l’interface locale des ports publiés et vaut 0.0.0.0 par défaut. Un déploiement qui termine TLS ailleurs doit disposer de sa propre configuration Caddy et de ports ; modifier SITE_ADDRESS seul ne configure pas ce mode.

L’application doit être servie à la racine de son domaine. start_url et la portée du service worker valent tous deux / : un hébergement dans un sous-répertoire ne fonctionnera pas sans modifier le manifeste et base dans Vite.

Architecture

Deux décisions structurent le reste de l’application.

Les horodatages bruts sont enregistrés ; l’arrondi n’est appliqué qu’à l’affichage. Modifier l’arrondi corrige donc aussi les journées passées. Deux postes adjacents partagent le même instant enregistré - la fin du poste N est le début du poste N+1 - afin que l’arrondi ne puisse jamais créer de trou entre eux. Les sélecteurs d’heure suivent la grille d’arrondi choisie ; ouvrir puis valider un horaire inchangé préserve son horodatage. Les récapitulatifs appliquent le même arrondi à l’affichage.

Les suggestions sont déduites de l’historique, pas de tables de compteurs. Rien n’est à synchroniser : le modèle est reconstruit en mémoire à partir des postes. En contrepartie, une durée de conservation courte dégrade les prédictions ; c’est pourquoi elle est de deux ans par défaut.

src/lib/
  time.js        dates locales, arrondi, formatage     (pur)
  predict.js     moteur de suggestions                 (pur)
  resume.js      génération du texte du registre       (pur)
  db.js          schéma Dexie et invariant de chaîne
  day.svelte.js  machine à états du cycle de journée

Les fonctions pures et les opérations de base de données et de cycle de vie ont des tests de régression. db.js regroupe les modifications des journées et des postes dans des transactions communes, notamment la création, la clôture, la reprise et la correction des bornes.

Pauses et nouveaux parcours

Journée → Commencer une pause ferme le poste courant. Reprendre le travail propose la dernière tâche de travail et son client, immédiatement modifiables. Une pause a ses propres horaires et son libellé, sans client ni type de repas. Le détail montre tous les postes ; la consultation reste séparée de la correction. Le récapitulatif et sa copie excluent les pauses. Le transport entre dans le total des heures de présence, les repas et pauses en sont exclus. Seules les statistiques montrent le cumul des pauses, séparément des repas. Les intervalles vides importés sont préservés.

Réglages → Gérer les automatismes et Gérer les jours non travaillés ouvrent des pages dédiées ; le bouton Retour du navigateur fonctionne via les routes hash. Gérer les données et sauvegardes ouvre aussi une page dédiée, avec retour aux réglages, conservation de la durée après rechargement et accès hors ligne. Les réglages sont écrits par transaction sur la dernière valeur persistée pour préserver les modifications d’autres onglets. Les erreurs de démarrage et actualisation sont affichées avec une action Réessayer.

La checklist avant production et les validations restant à exécuter sont suivies dans PRODUCTION.md.

Sauvegarde vérifiée et validation navigateur

Exporter les données prépare le fichier et enregistre son empreinte complète. Vérifier le fichier exporté… relit le fichier téléchargé, contrôle qu’il est importable et compare son contenu à l’export. La date de la dernière sauvegarde vérifiée est distincte de celle du dernier export préparé. Après sept jours sans export vérifié, Pardis affiche un rappel pendant son utilisation. L’export reste local ; conservez le fichier hors de cet appareil. La synchronisation facultative utilise un coffre distinct et ne remplace pas cette sauvegarde.

La purge affiche une liste figée de journées. Sauvegarde et suppression partagent une transaction ; une correction concurrente bloque la purge et demande une nouvelle consultation. Les autres journées récemment importées restent intactes.

Les tests Playwright utilisent des contextes neufs et des données synthétiques, à 320 px. Ils vérifient consultation/correction, focus, Retour, reprise à deux onglets, export vérifié, purge/restauration et rechargement hors ligne. Ils couvrent aussi le nouvel écran Données, le retour du champ de conservation à sa valeur persistée après un échec, le refus d’un export modifié et l’annulation complète d’une purge en erreur, avec préservation de la sauvegarde précédente. Traces, vidéos et captures sont désactivées. Pour un Chrome déjà installé, définir PARDIS_CHROME_PATH avec son chemin ; sinon installer Chromium avec Playwright. La CI installe Chromium Headless Shell et ses dépendances avant de lancer ces tests. Elle télécharge uniquement la variante utilisée par les tests sans interface et accorde 180 secondes à chaque connexion de téléchargement, avec les nouvelles tentatives intégrées à Playwright. L’installation dispose de 20 minutes et le job de validation de 30 minutes. Une erreur d’installation bloque le déploiement.

Synchronisation facultative entre appareils

Données et sauvegardes → Synchronisation et appareils permet de créer un coffre chiffré sans e-mail ni mot de passe, puis de lier des appareils avec un code temporaire ou un QR code et une confirmation sur l’écran dédié. La saisie reste locale et fonctionne hors ligne. Les journées concurrentes sont conservées pour résolution. Un document de secours permet de retrouver l’accès après perte des appareils.

Les règles métier sont partagées ; le thème et le suivi des sauvegardes restent locaux. Un appareil est responsable des automatismes, avec proposition de transfert à l’ouverture sur un appareil secondaire. Les demandes d’association ne produisent aucune alerte ailleurs dans l’application.

Le protocole, les limites de sécurité, le fonctionnement des suppressions et les commandes de sauvegarde/restauration du serveur sont documentés dans SYNC.md. Pour le développement, lancer aussi npm run sync:server avec Node.js 24.

Licence et crédits typographiques

Le code source de Pardis est distribué sous la licence GNU General Public License, version 3 uniquement (GPL-3.0-only). Le texte intégral se trouve dans LICENSE.md. Les fichiers de polices fournis sont des œuvres distinctes, distribuées sous la SIL Open Font License, version 1.1. Leurs mentions de droits d’auteur et le texte de cette licence figurent dans public/fonts/OFL.txt. Copyright (C) 2026 EI Adrien Weiskopff.

• Bebas Neue, par Ryoichi Tsunekawa - SIL Open Font License 1.1.
• Charis SIL - SIL Open Font License 1.1. Voir le site officiel de Charis SIL.