logwatcher/docs/usage.md

# 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.

Deux modes d'entrée sont disponibles : l'analyse de fichiers locaux, et 
l'analyse des compte-rendus reçus par correspondance dans une boîte Exchange.

---

## Entrées

### Analyser les compte-rendus reçus par mail
```bash
logwatcher from-mails --output-dir chemin/vers/sortie 
```

Les mails sont lus dans le dossier `Logs` de la boîte (les compte-rendus y sont 
déplacés par une règle automatique). Les logs sont extraits du corps du message, 
ou de la pièce jointe `CR_*` lorsque le corps indique que le compte-rendu dépasse 
100 lignes. 

Après traitement, les mails sont déplacés dans le sous-dossier 
`Logs/Analyzed` et ne seront pas relus. Le dossier `Analyzed` est créé automatiquement 
au premier passage s'il n'existe pas. Les trois rapports sont écrits sur disque. 
Le rapport `n2.log` est envoyé automatiquement aux destinataires définis dans 
`N2_REPORT_RECIPIENTS` (variable du fichier `.env`). Une copie du mail envoyé est 
conservée dans le dossier `Logs/Sent`.

### Analyser un fichier de logs

```bash
logwatcher from-files --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 from-files --input-files fichier1.txt --input-files fichier2.txt
```

### Analyser tous les logs d'un répertoire

```bash
logwatcher from-files --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 et ne concernent 
que la commande from-files. Il n'y a pas de règle équivalente pour from-mails. 
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 from-files --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
```

Pour la commande `from-mails`, la ligne "Fichier(s) lu(s)" devient "Mail(s) lu(s)". Le reste de l'en-tête est identique. Ce libellé est déterminé par le type de source (fichiers ou mails).



## Options

### Options communes à toutes les commandes
- `--verbose, -v` affiche les logs DEBUG sur la sortie standard. Sans cette option, seuls les avertissements et erreurs sont affichés. 
Le fichier de log contient toujours le niveau DEBUG. 

- `--version` affiche la version du package et quitte.

```bash
logwatcher version: 1.0.1
```

### Options de `from-files` et `from-mails`
- `--output-dir` répertoire de sortie des rapports. Par défaut : `output/`.

Exemple :  
```bash
logwatcher from-files --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie
```


### Options de `from-files` uniquement
- `--input-files` fichiers de logs à analyser.
- `--input-dir` répertoire contenant les fichiers de logs

---

## Automatisation sous Windows

Le flux mail est destiné à être déclenché automatiquement par le Planificateur de tâches Windows, après réception des compte-rendus du créneau. 

- Réglages de la tâche Déclencheur : tous les jours à 07h20, répété toutes les 4 heures pendant 1 jour

- Action : ...\.venv\Scripts\logwatcher.exe

- Arguments : from-mails --output-dir ...\results

- Commencer dans : répertoire du projet

- Sécurité : "N'exécuter que si un utilisateur a ouvert une session"

Le mode "uniquement si un utilisateur a ouvert une session" est nécessaire lorsque le compte d'exécution ne dispose pas du droit "Ouvrir une session en tant que tâche" (SeBatchLogonRight). 

Sur une machine de production, ce droit doit être accordé à un compte de service, afin que la tâche puisse s'exécuter sans session ouverte. Conséquence de ce mode : la tâche ne se déclenche pas si aucune session n'est ouverte. Les créneaux de 07h20 à 19h20 tombent dans la journée de travail ; le créneau de 03h20 ne se déclenchera pas.


## 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.


### Mail en retard

Si un compte-rendu arrive après le passage du Planificateur, il reste dans le dossier `Logs` et sera traité au créneau suivant. Le rapport indique alors le nombre de mails effectivement lus, sans signaler l'absence.

### Mails déjà traités

Les mails traités sont déplacés dans `Logs/Analyzed` et ne sont pas relus. Le dossier `Analyzed` est créé automatiquement au premier passage s'il n'existe pas.

### Mail sans logs exploitables

Un mail qui ne contient ni logs dans le corps ni pièce jointe `CR_*` est ignoré, avec un avertissement dans le log applicatif. Il en va de même si le corps annonce une pièce jointe mais qu'aucune n'est trouvée. Les autres mails du dossier sont traités normalement.

### Échec de l'envoi du rapport

L'envoi du mail a lieu avant le déplacement des mails vers Analyzed. Si l'envoi échoue, les mails restent dans Logs : le rapport sera régénéré et renvoyé au prochain passage. Un rapport peut donc être envoyé deux fois en cas d'échec après envoi, mais jamais perdu.

## 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.
Le corps des mails et le contenu des pièces jointes `CR_*` sont également lus en windows-1252.

## Exemple complet

- Analyser tous les logs d'un répertoire et écrire les rapports dans un
dossier dédié :
```bash
logwatcher from-files --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
```

La commande n'envoie rien ; le rapport `n2.log` est transmis manuellement.


- Depuis la boîte mail : 
```bash
logwatcher from-mails --output-dir rapports/2026-09-01/
```

Les trois rapports sont créés dans `rapports/2026-09-01/`. Le rapport `n2.log` est envoyé aux destinataires définis dans `N2_REPORT_RECIPIENTS`, et une copie du mail est conservée dans `Logs/Sent`. Les mails traités sont déplacés dans `Logs/Analyzed`.

le rapport `n2.log` est transmis automatiquement aux techniciens N2.