docs(docs): 📝 update documentation files

update ruff and pyproject.toml. Sync or reinstall the package
2026-09-17 18:13:57 +02:00
parent 22e54da876
commit fa5987215f
8 changed files with 263 additions and 83 deletions
@@ -9,7 +9,9 @@ génère des rapports texte.
 Le traitement suit un pipeline linéaire :

 ```text
-fichiers de logs
+Flux fichiers fichiers de logs
+
+  fichiers de logs
      │
      ▼
  parser.py       lit et parse les fichiers en LogEntry
@@ -24,6 +26,29 @@ fichiers de logs
  rapports .log
 ```

+```text
+Flux mail
+
+  boîte Exchange (dossier Logs)
+      │
+      ▼
+  read_mail.py
+      │
+      ▼
+  perser.py
+      │
+      ▼
+  classifier.py
+      │
+      ▼
+  reporter.py
+      │
+      ▼
+  notifier.py
+```
+
+L'envoi du mail précède le déplacement des mails vers `Analyzed`. Si l'envoi échoue, les mails restent dans `Logs` et le rapport est régénéré au prochain passage : un rapport peut être envoyé deux fois en cas d'échec après envoi, mais jamais perdu.
+
 ## Structure du package

 ```text
@@ -31,25 +56,68 @@ src/logwatcher/
 ├── __init__.py          # expose __version__
 ├── __main__.py          # point d'entrée : python -m logwatcher
 ├── cli.py               # interface en ligne de commande (Typer)
-├── config.py            # constantes : chemins, formats
+├── config.py            # constantes : chemins, formats, source type
 ├── logging_config.py    # configuration du logging
 ├── models.py            # LogEntry : structure de données
-├── parser.py            # lecture et parsing des fichiers
+├── mail_reader.py       # lecture de la boîte mail (EWS)
+├── mail_utils.py        # utilitaires boîte mail (dossiers, constantes)
+├── notifier.py          # envoi du rapport n2 par mail
+├── parser.py            # lecture et parsing des logs
 ├── classifier.py        # classification N2 / hors N2
 └── reporter.py          # génération des rapports texte
 ```

 ### Modules
-#### cli.py — point d'entrée
+
+#### [`classifier.py`](../src/logwatcher/classifier.py) — classification
+
+* `N2_PATTERNS` : dictionnaire des motifs d'erreurs pertinents pour le N2, fournis par les techniciens.
+* `classify_log_entries()` : sépare les entrées en deux listes (relevant, irrelevant) et remplit entry.error_name pour les entrées pertinentes.
+
+
+#### [`cli.py`](../src/logwatcher/cli.py) — point d'entrée

 * Définit `app = typer.Typer()` et la commande principale.
 * Valide les arguments (`--input-files` / `--input-dir` mutuellement exclusifs).
 * Orchestre le pipeline : parsing → classification → rapports.
-* Gère les erreurs utilisateur (`BadParameter`, code de sortie 2) et
-* les erreurs d'exécution (code de sortie 1).
+* Gère les erreurs utilisateur (`BadParameter`, code de sortie 2) et les erreurs d'exécution (code de sortie 1).
 * Expose `--version` (eager, affiche et quitte).

-#### models.py — LogEntry
+
+#### [`config.py`](../src/logwatcher/config.py) — constantes
+
+* Chemins : `OUTPUT_PATH`, `RESULT_PATH`, `LOGGING_PATH`, `TEST_PATH`, `FIXTURE_PATH`
+* Date et fuseau : `DATETIME_FORMAT`, `FRENCH_TIMEZONE`
+* Types : `SourceType` (`FILE`, `MAIL`)
+
+
+#### [`logging_config.py`](../src/logwatcher/logging_config.py) — logging
+
+* `setup_logging()` : configure le logger racine.
+* Handler console (`INFO`, ou `DEBUG` si verbose) + handler fichier.
+* Le fichier de log `logwatcher.log` est horodaté et écrit dans le dossier de sortie.
+* Les loggers verbeux des dépendances (exchangelib) sont ramenés au niveau WARNING, afin de ne pas polluer `logwatcher.log`.
+
+
+#### [`mail_reader.py`](../src/logwatcher/mail_reader.py) — lecture de la boîte mail
+
+Accès à la boîte via EWS (exchangelib), en authentification NTLM.
+
+* `connect_to_mailbox()` : lit `EMAIL`, `PASSWORD` et `EWS_URL` dans l'environnement, construit le compte et vérifie la connexion par un aller-retour serveur (accès à `account.protocol.version`).
+* `fetch_log_messages()` : retourne les mails du dossier Logs. 
+* `extract_logs_from_mails()` : pour chaque mail, extrait les logs du corps ou de la pièce jointe `CR_*`, et les normalise en une liste de lignes. Ignore les lignes non conformes et avertit si le corps annonce une pièce jointe introuvable. 
+* `move_analyzed_mails()` : déplace les mails traités vers le dossier `Analyzed`. 
+
+
+#### [`mail_utils.py`](../src/logwatcher/mails_utils.py) — utilitaires boîte mail
+* `get_or_create_folder(account, folder_name)` retourne un dossier du compte, et le crée s'il n'existe pas. Utilisé pour les dossiers `Analyzed` et `Sent`.
+* Constantes : `LOG_DIR`, `ANALYZED_FOLDER`, `SENT_FOLDER`, `LOG_IN_ATTACHMENT_PATTERN`.
+
+#### [`notifier.py`](../src/logwatcher/notifier.py) — envoi du rapport
+* `send_n2_report(account, summary, n2_log_file)` : construit un message Exchange avec `MAIL_TEMPLATE` comme corps, attache `n2_log_file`, et l'envoie aux destinataires de `N2_REPORT_RECIPIENTS`. Une copie du message envoyé est conservée dans `Logs/Sent` (copy_to_folder). L'envoi passe par les services Exchange (message.send) : aucun serveur SMTP externe n'est requis.
+
+
+#### [`models.py`](../src/logwatcher/models.py) — LogEntry

 Dataclass immuable (par convention) représentant une ligne de log parsée.

@@ -65,41 +133,32 @@ Champs principaux :

 LogEntry est créée uniquement par le parser. Le classifier l'enrichit
 (remplit `error_name`). Le modèle lui-même ne contient pas de logique métier.
-[`parser.py`]() — lecture et parsing

-* `LOG_PATTERN` : expression régulière du format d'une ligne LAME MDC.
-* `parse_log_file()` : lit un fichier, retourne list[LogEntry].
-* Les lignes non conformes (système, en-têtes, corrompues) sont ignorées silencieusement.

-#### classifier.py — classification
+#### [`parser.py`](../src/logwatcher/parser.py) — lecture et parsing

-* N2_PATTERNS : dictionnaire des motifs d'erreurs pertinents pour le N2, fournis par les techniciens.
-* classify_log_entries() : sépare les entrées en deux listes (relevant, irrelevant) et remplit entry.error_name pour les entrées pertinentes.
+* Patterns réutilisables : `SERVER_IP_PATTERN`, `MDC_SERVER_NAME_PATTERN`, `DATE_TIME_PATTERN`, `STORE_NAME_PATTERN`, `ERROR_MESSAGE_PATTERN`. 
+* `LOG_PATTERN` : expression régulière compilée du format d'une ligne LAME MDC. 
+* `parse_line()` : parse une ligne, retourne `LogEntry | None`. 
+* `parse_lines()` : parse un itérable de lignes, ignore les lignes non conformes. 
+* `parse_file()` : lit un fichier (encodage windows-1252) et délègue à `parse_lines()`.

-#### reporter.py — rapports
+
+#### [`reporter.py`](../src/logwatcher/reporter.py) — rapports

 * Templates texte (`string.Template`) : `BASE_TEMPLATE`, `N2_SUPPORT_TEMPLATE`, `OTHER_TEMPLATE`, `ERROR_TEMPLATE`.
 * `build_reports()` : construit les trois rapports (`dict n2, other, all`).
-* `write_log_report()` : écrit les rapports sur disque en Windows-1252.
+* `write_log_report()` : prend un SourceType (`FILE` ou `MAIL`) pour adapter le libellé de l'en-tête ("Fichier(s) lu(s)" ou "Mail(s) lu(s)"). Les fichiers générés s'appellent `all.log`, `n2.log` et `other.log`.
 * `_get_period()` : calcule les bornes min/max des error_time.

-#### logging_config.py — logging
-
-* `setup_logging()` : configure le logger racine.
-* Handler console (`INFO`, ou `DEBUG` si verbose) + handler fichier.
-* Le fichier de log `logwatcher.log` est horodaté et écrit dans le dossier de sortie.
-
-#### config.py — constantes
-
-* Chemins (`OUTPUT_PATH`, `FIXTURE_PATH` ...).
-* Formats de date (`DATETIME_FORMAT`).

 ## Dépendances

 | Package | Rôle |
 |---------|------|
-| `typer` | Interface en ligne de commande |
+| `exchangelib` | Accès EWS à la boîte mail et envoi des rapports |
+| `mypy` | Typage statique (dev) |
 | `pytest` | Tests (dev) |
 | `pytest-cov` | Couverture (dev) |
 | `ruff` | Linting/formatage (dev) |
-| `mypy` | Typage statique (dev) |
+| `typer` | Interface en ligne de commande |
@@ -7,14 +7,34 @@ Logwatcher analyse les comptes-rendus de suivi d'imports NOSYMAG (fichiers
 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 --input-files chemin/vers/CR_fichier.txt
+logwatcher from-files --input-files chemin/vers/CR_fichier.txt
 ```

 ### Analyser plusieurs fichiers de logs
@@ -22,21 +42,22 @@ 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
+logwatcher from-files --input-files fichier1.txt --input-files fichier2.txt
 ```

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

 ```bash
-logwatcher --input-dir chemin/vers/dossier
+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. Fournir
-les deux options lève une erreur et le traitement est interrompu. Ne fournir
+> `--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
@@ -47,7 +68,7 @@ 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
+logwatcher from-files --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie
 ```

 ### Les rapports générés
@@ -85,19 +106,56 @@ Nombre d'erreurs	 : 2
    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

- `--output-dir` : Répertoire de sortie des rapports. Par défaut : `output/`.
+### 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 --input-dir logs/ --output-dir rapports/2026-09-01/
+logwatcher version: 1.0.1
 ```

- `--version` : Affiche la version du package et quitte.
+### Options de `from-files` et `from-mails`
+- `--output-dir` répertoire de sortie des rapports. Par défaut : `output/`.
+
+Exemple :  
 ```bash
-logwatcher --version
-# logwatcher version: 0.0.1
+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
@@ -118,17 +176,34 @@ 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
+### 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
+- 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/
+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/` :
@@ -138,5 +213,14 @@ 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.
+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.