📝docs(docs): add documentation for README.md

add documentation in README.md, usage.md, architecture.md, update python version based on the version used in development
2026-09-02 11:52:27 +02:00
parent a43afb9df7
commit bfa5fa600b
6 changed files with 340 additions and 10 deletions
@@ -0,0 +1,142 @@
+# Guide d'utilisation
+
+## Introduction
+
+Logwatcher analyse les comptes-rendus de suivi d'imports NOSYMAG (fichiers
+`CR_*.txt` et autres logs LAME MDC) pour identifier les erreurs pertinentes
+pour le support N2. Il génère trois rapports : un pour les erreurs N2, un
+pour les erreurs hors périmètre N2, et un rapport complet.
+
+---
+
+## Entrées
+
+### Analyser un fichier de logs
+
+```bash
+logwatcher --input-files chemin/vers/CR_fichier.txt
+```
+
+### Analyser plusieurs fichiers de logs
+L'option `--input-files` accepte plusieurs fichiers. Répéter l'option pour
+chaque fichier :
+
+```bash
+logwatcher --input-files fichier1.txt --input-files fichier2.txt
+```
+
+### Analyser tous les logs d'un répertoire
+
+```bash
+logwatcher --input-dir chemin/vers/dossier
+```
+
+L'option `--input-dir` analyse tous les fichiers `.log`, `.txt` ou sans
+extension contenus dans le répertoire. Les autres fichiers sont ignorés.
+
+> ### Règle d'exclusivité
+> `--input-files` et `--input-dir` sont mutuellement exclusifs. Fournir
+les deux options lève une erreur et le traitement est interrompu. Ne fournir
+aucune des deux lève également une erreur.
+
+## Sorties
+
+### Emplacement des rapports
+
+Par défaut, les rapports sont écrits dans le répertoire `output/` du dossier
+courant. Un autre emplacement peut être fourni avec `--output-dir` :
+
+```bash
+logwatcher --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie
+```
+
+### Les rapports générés
+
+Chaque analyse produit trois rapports différents : `all.log`, `n2.log` et `other.log`.
+
+- `all.log` : Toutes les erreurs analysées, N2 et hors N2.
+- `n2.log` : Uniquement les erreurs pertinentes pour le support N2.
+- `other.log` : Uniquement les erreurs hors périmètre N2
+
+
+#### Contenu d'un rapport
+
+Chaque rapport contient un en-tête avec la période analysée, le nombre de
+fichiers lus et le nombre total d'erreurs, suivi du détail des erreurs.
+Un rapport se présente ainsi :
+
+```text
+RAPPORT D'ANALYSE DE LOGS
+=========================
+Période	 : 01/09/2026 11:07:53 -> 01/09/2026 15:04:18
+Fichier(s) lu(s)	 : 1
+Nombre total d'erreur(s)	: 3
+
+=================================
+ERREURS SUPPORT N2
+=================================
+Nombre d'erreurs	 : 2
+
+[1] BL_AUTO_BESTSELLER_REJECTED
+    Magasin: DUMAS-DELAGE
+    MDC: MDC_340
+    Serveur: 192.168.13.23
+    Heure: 28/07/2026 08:05:27
+    Raison: Erreur : 1099_2622609667_DESADV : / 00098/000 ... ne correspond
+```
+
+## Options
+
+- `--output-dir` : Répertoire de sortie des rapports. Par défaut : `output/`.
+```bash
+logwatcher --input-dir logs/ --output-dir rapports/2026-09-01/
+```
+
+- `--version` : Affiche la version du package et quitte.
+```bash
+logwatcher --version
+# logwatcher version: 0.0.1
+```
+
+## Cas particuliers
+
+### Fichier vide
+
+Un fichier vide est lu sans erreur. Les trois rapports sont générés avec `Nombre total d'erreur(s) : 0`.
+
+
+### Répertoire vide
+
+Un répertoire vide est traité sans erreur. Les trois rapports sont générés
+avec `Fichier(s) lu(s) : 0 et Nombre total d'erreur(s) : 0`.
+
+
+### Logs non reconnus
+
+Les lignes qui ne correspondent pas au format LAME MDC (lignes système,
+en-têtes de répertoire, lignes corrompues) sont ignorées silencieusement
+et ne produisent pas d'entrée dans les rapports.
+
+
+### Encodage des fichiers
+
+Les fichiers d'entrée sont lus en Windows-1252 (encodage natif des logs
+LAME MDC). Les rapports générés sont également écrits en Windows-1252.
+
+## Exemple complet
+
+Analyser tous les logs d'un répertoire et écrire les rapports dans un
+dossier dédié :
+```bash
+logwatcher --input-dir logs/2026-09-01/ --output-dir rapports/2026-09-01/
+```
+
+Après exécution, les fichiers suivants sont créés dans `rapports/2026-09-01/` :
+```text
+all.log      # toutes les erreurs
+n2.log       # erreurs pertinentes pour le N2
+other.log    # erreurs hors périmètre N2
+```
+
+Le rapport `n2.log` peut ensuite être transmis aux techniciens N2, et
+`other.log` aux équipes concernées par les autres erreurs.