TimeManagerCLI.py

🔷 INFORMATIONS GÉNÉRALES

Champ Détail

Nom du script TimeManagerCLI.py

Version 1.0.0

Date de création 11/03/2026

Auteur / Demandeur IA Générée (Gemini)

Objectif principal Gérer le temps de travail des équipes de production de Champagne via une interface en ligne de commande.

🎯 DESCRIPTION FONCTIONNELLE

📌 Que fait ce script ?

Ce script permet de suivre précisément les étapes de production du champagne (vendange, tirage, dégorgement, etc.) en enregistrant les sessions de travail des membres d’une équipe. Il calcule automatiquement les durées et génère des rapports d’activité filtrables.

📌 Problème résolu

Il remplace les fiches de temps papier ou les tableurs complexes par un outil interactif simple, permettant de consolider les heures travaillées par cuvée, par lot et par phase de production pour une meilleure traçabilité.

⚙️ SPÉCIFICATIONS TECHNIQUES

🐍 Environnement

Élément Valeur

Version Python 3.7+ (utilise les dataclasses)

OS cible Tous (Windows / Linux / MacOS)

Mode d’exécution CLI (Interface en ligne de commande)

📦 Dépendances / Librairies

# Librairies standard (built-in)

json : Stockage des données.

os : Vérification de l’existence du fichier de données.

dataclasses : Structure des objets Team et WorkSession.

datetime : Gestion des horodatages et calculs de durée.

typing : Typage statique des données.

# Librairies externes

Aucune (le script est auto-suffisant).

📥 ENTRÉES (INPUTS)

# Nom Type Obligatoire Description Exemple

1 choice str ✅ Oui Choix du menu principal « 4 »

2 team_id int ✅ Oui Identifiant numérique de l’équipe 1

3 phase_choice int ✅ Oui Index de la phase de production 2

4 cuvee / lot str ❌ Non Références de production « Brut Réserve »

📂 Fichiers / Sources de données en entrée

Type Chemin / Format Description

JSON gestion_temps_champagne.json Base de données locale contenant les équipes et sessions.

📤 SORTIES (OUTPUTS)

# Nom Type Description Exemple

1 Report stdout Affichage textuel des statistiques d’heures « Total: 12h30 »

2 Sessions list Liste des sessions ouvertes affichées à l’écran –

📂 Fichiers / Données en sortie

Type Chemin / Format Description

JSON gestion_temps_champagne.json Persistance des données après chaque modification.

🧱 STRUCTURE DU SCRIPT

Plaintext

TimeManagerCLI.py

│

├── 📌 IMPORTS (json, datetime, dataclasses…)

├── 📌 CONSTANTES (PHASES_PRODUCTION, DATA_FILE)

├── 📌 FONCTIONS UTILITAIRES (now_iso, format_duration…)

├── 📌 CLASSES DE DONNÉES (Team, WorkSession)

├── 📌 CLASSE PRINCIPALE (TimeManagerCLI)

│ ├── load() / save() → Persistance JSON

│ ├── start_session() → Logique de début de tâche

│ ├── close_session() → Logique de fin de tâche

│ └── report_hours() → Moteur d’agrégation

└── 📌 MAIN (Point d’entrée app.run())

🔄 LOGIQUE / ALGORITHME

Initialisation : Chargement du fichier JSON. Si inexistant, initialise des dictionnaires vides.

Boucle Principale : Affichage du menu et attente d’une saisie utilisateur.

Ouverture de session : Enregistre start_at avec l’heure actuelle. La session reste « ouverte » (end_at est None).

Clôture : L’utilisateur choisit une session ouverte. Le script injecte end_at.

Rapport :

Parcourt toutes les sessions.

Filtre par date (si fourni) et par équipe.

Additionne les durées calculées par duration_hours().

🚨 GESTION DES ERREURS

Cas d’erreur Type d’exception Comportement attendu

ID non numérique ValueError Capturé par ask_int, retourne None, message « ID invalide ».

Date mal formatée ValueError Message « Format de date invalide », retour au menu.

Fichier JSON corrompu json.JSONDecodeError Le script plante (non géré explicitement en try/except).

✅ CONTRAINTES & RÈGLES MÉTIER

Règle 1 : Une session ne peut être comptabilisée dans le rapport que si elle est clôturée.

Règle 2 : La durée d’une session ne peut pas être négative (sécurité max(delta, 0.0)).

Règle 3 : Si un membre n’existe pas dans l’équipe lors du démarrage, le script propose son ajout automatique.

Règle 4 : Les phases de production sont limitées à la liste prédéfinie (Vendange à Expédition).

🧪 TESTS ATTENDUS

# Cas de test Entrée Résultat attendu Statut

1 Création équipe Nom: « Cave A » Équipe créée avec ID 1 ⬜ À tester

2 Calcul durée Start: 08:00, End: 10:30 Rapport affiche « 2h30 » ⬜ À tester

3 Filtre date Fin: 2026-03-10 Exclut les sessions du 2026-03-11 ⬜ À tester

📝 EXEMPLE D’UTILISATION

▶️ Lancement en ligne de commande

Bash

python TimeManagerCLI.py

📋 Exemple de sortie attendue (Rapport)

Plaintext

=== RAPPORT HEURES ===

Total: 45h15

Par équipe :

– Équipe Fermentation: 30h00

– Équipe Cave: 15h15

Par membre :

– Jean: 20h00

– Alice: 25h15