Lecteur de logs Laravel avec notification par favicon

Application web locale (axum, Leptos 0.8, Tailwind v4, SQLite) qui suit
les fichiers storage/logs de projets Laravel et signale les nouvelles
entrées par le favicon et le titre de l'onglet.

- Ajout de projets par chemin (validation, chemin canonique, doublons)
- Découverte récursive des *.log et indexation incrémentale en flux,
  détection de troncature et de rotation
- Curseur de lecture par fichier, polling à intervalle configurable
- Vue fichier : pagination, filtres par niveau (niveaux absents grisés,
  double-clic pour isoler un niveau), recherche texte
- Tri des fichiers par nom ou date de modification, projets repliables
- Spécification complète dans .spec/specification.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Romulus21andClaude Opus 5.5 committed 2026-10-21 10:52:04 +02:00
commit 818527b758
20 files changed
+6523

No files matched your search

+387
View File
@@ -0,0 +1,387 @@
# Lara Logs Reader — Spécification
> Document dérivé du brief `.spec/spec.md`.
> Statut : brouillon v1 — 2026-10-21.
---
## 1. Vue d'ensemble
Lara Logs Reader est une application web **locale et mono-utilisateur** qui permet à un développeur de :
1. enregistrer un ou plusieurs projets Laravel par leur chemin sur le disque ;
2. voir tous les fichiers de log de chaque projet et en lire les entrées ;
3. être prévenu, via le **favicon** et le titre de l'onglet, de toute nouvelle entrée apparue depuis sa dernière consultation ;
4. choisir l'intervalle de rafraîchissement.
### 1.1 Périmètre
| Dans le périmètre | Hors périmètre (v1) |
|---|---|
| Fichiers de log sur le disque local | Logs distants (SSH, S3, Papertrail…) |
| Format Monolog par défaut de Laravel (`single`, `daily`, channels custom en fichier) | Formats JSON, syslog, stderr |
| Lecture seule des logs | Édition, suppression ou vidage des logs |
| Un seul utilisateur, sans authentification | Comptes, rôles, partage |
| Notification par favicon et titre d'onglet | E-mail, Slack, notifications natives de l'OS |
---
## 2. Glossaire
| Terme | Définition |
|---|---|
| **Projet** | Un projet Laravel enregistré, identifié par son chemin racine **canonique** (absolu, symlinks résolus, sans `/` final). |
| **Répertoire de logs** | `<racine>/storage/logs`. |
| **Fichier de log** | Tout fichier `*.log` situé (récursivement) dans le répertoire de logs. |
| **Entrée** | Une écriture de log. Elle commence par une ligne d'en-tête Monolog et contient toutes les lignes suivantes jusqu'à la prochaine ligne d'en-tête (stack trace comprise). |
| **Ligne d'en-tête** | Ligne qui correspond à `^\[(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[+-]\d{2}:?\d{2})?)\] (\w+)\.(\w+): ` → horodatage, environnement, niveau. |
| **Niveau** | L'un des niveaux PSR-3 : `DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERROR`, `CRITICAL`, `ALERT`, `EMERGENCY`. |
| **Entrée complète** | Une entrée suivie d'une autre ligne d'en-tête, ou, pour la dernière du fichier, terminée par `\n` dans un fichier non modifié depuis 1 s. |
| **Offset de scan** | Position (en octets) jusqu'à laquelle le fichier a été lu et découpé en entrées complètes. |
| **Curseur de lecture** | Position (en octets) de fin de la dernière entrée **consultée** par l'utilisateur, une par fichier. |
| **Non-lu** | Une entrée complète qui commence à un offset ≥ curseur de lecture. |
| **Intervalle** | Délai en secondes entre deux rafraîchissements côté client. |
---
## 3. Architecture
```
┌──────────────── Navigateur ────────────────┐
│ Leptos (hydratation WASM) + Tailwind │
│ - poll unread_summary toutes les N s │
│ - dessine le favicon (canvas) + titre │
└──────────────▲─────────────────────────────┘
│ server functions Leptos (HTTP)
┌──────────────┴──────── Serveur ────────────┐
│ axum + leptos_axum (SSR) │
│ - Scanner : découverte + lecture │
│ incrémentale + parsing │
│ - Repository SQLite (sqlx, migrations) │
└──────┬───────────────────────────┬─────────┘
│ lecture seule │
<projet>/storage/logs/*.log data.sqlite
```
- **Build** : `cargo-leptos` (features `ssr` / `hydrate`), Tailwind CSS intégré via la config `tailwind-input-file` de cargo-leptos.
- **Persistance** : SQLite via `sqlx`, migrations embarquées (`sqlx::migrate!`) appliquées au démarrage, `PRAGMA foreign_keys = ON`, mode WAL.
- **Scan** : déclenché par chaque appel `unread_summary` (donc au rythme du polling). Les scans concurrents d'un même projet sont sérialisés (mutex par projet) ; un appel qui arrive pendant un scan attend son résultat au lieu d'en relancer un.
- **Configuration** (variables d'environnement) :
- `LLR_DATABASE_URL` — défaut `sqlite://./lara_logs_reader.sqlite?mode=rwc`
- `LLR_ADDR` — défaut `127.0.0.1:3000`
### 3.1 API (server functions)
Chaque fonction est exposée en `POST /api/<nom>`.
| Fonction | Entrée | Sortie |
|---|---|---|
| `add_project` | `path: String`, `name: Option<String>` | `Project` |
| `remove_project` | `project_id` | `()` |
| `read_entries` | `file_id`, `limit` (≤ 2000), `levels: Vec<String>`, `query: String` | `EntriesPage { entries, has_more, scan_offset, read_offset, levels }` |
| `mark_read` | `file_id`, `up_to` | `()` |
| `mark_all_read` | `project_id: Option<_>` | `()` |
| `unread_summary` | — | `Summary { total, projects[{…, unread, files[{…, unread}]}] }` |
| `get_settings` / `set_refresh_interval` | `seconds: String` | `Settings { refresh_interval_seconds, file_sort }` |
| `set_file_sort` | `sort: "name" \| "modified"` | `()` |
---
## 4. Modèle de données
```sql
CREATE TABLE projects (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
root_path TEXT NOT NULL UNIQUE, -- chemin canonique
created_at TEXT NOT NULL
);
CREATE TABLE log_files (
id INTEGER PRIMARY KEY,
project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
relative_path TEXT NOT NULL, -- relatif à storage/logs
file_identity TEXT, -- inode+device (Unix) / file index (Windows)
size INTEGER NOT NULL DEFAULT 0,
modified_at INTEGER, -- mtime, secondes Unix (tri)
scan_offset INTEGER NOT NULL DEFAULT 0,
entries_count INTEGER NOT NULL DEFAULT 0, -- entrées complètes ≤ scan_offset
discovered_at TEXT NOT NULL,
missing_since TEXT, -- NULL si le fichier existe
last_error TEXT,
UNIQUE (project_id, relative_path)
);
CREATE TABLE log_entries_index ( -- index léger, pas le contenu
log_file_id INTEGER NOT NULL REFERENCES log_files(id) ON DELETE CASCADE,
start_offset INTEGER NOT NULL,
end_offset INTEGER NOT NULL,
logged_at TEXT NOT NULL,
level TEXT NOT NULL,
PRIMARY KEY (log_file_id, start_offset)
);
CREATE TABLE read_cursors (
log_file_id INTEGER PRIMARY KEY REFERENCES log_files(id) ON DELETE CASCADE,
read_offset INTEGER NOT NULL DEFAULT 0,
updated_at TEXT NOT NULL
);
CREATE TABLE settings (
key TEXT PRIMARY KEY,
value TEXT NOT NULL
);
-- valeurs initiales : ('refresh_interval_seconds', '5'), ('file_sort', 'name')
```
- Le **contenu** des entrées n'est pas stocké : il est relu dans le fichier à partir de `start_offset`/`end_offset`. L'index permet compteurs, filtres par niveau et pagination sans tout relire.
- `unread(file) = SELECT COUNT(*) FROM log_entries_index WHERE log_file_id = ? AND start_offset >= read_offset`.
---
## 5. Règles métier
### 5.1 Ajout d'un projet
1. Le chemin saisi est nettoyé (trim) ; `~` en tête est remplacé par `$HOME`.
2. Il est canonicalisé (`std::fs::canonicalize`).
3. Il est valide si : c'est un répertoire, il contient un fichier `artisan` **et** un répertoire `storage/logs` lisible.
4. Le nom par défaut est le nom du dernier segment du chemin.
5. Les fichiers de log existants sont découverts et indexés. **Leur curseur de lecture est placé à la fin** (`read_offset = scan_offset`) : l'historique n'est pas compté comme non-lu.
### 5.2 Découverte des fichiers
- Parcours récursif de `storage/logs`, à chaque scan.
- Retenus : fichiers réguliers dont le nom se termine par `.log`. Ignorés : fichiers cachés (`.gitignore`…), répertoires, autres extensions (`.gz`…).
- Liens symboliques : suivis uniquement si la cible canonique reste sous `storage/logs`.
- Un fichier **apparu après l'ajout du projet** (ex. nouveau `laravel-2026-10-22.log` en mode daily) est créé avec `read_offset = 0` : tout son contenu est non-lu.
- Un fichier disparu reçoit `missing_since` ; ses entrées ne comptent plus dans les non-lus ; il réapparaît normalement s'il revient (traité comme une rotation, cf. 5.4).
### 5.3 Lecture incrémentale et parsing
- Le fichier est ouvert en **lecture seule**, lu à partir de `scan_offset` par blocs (ex. 64 Kio), sans jamais le charger en entier.
- Les octets sont décodés en UTF-8 avec remplacement (`from_utf8_lossy`) ; les offsets restent des offsets d'octets.
- Une ligne d'en-tête ouvre une nouvelle entrée. Toute autre ligne est rattachée à l'entrée courante.
- Des lignes avant la première ligne d'en-tête du fichier forment une entrée de niveau `UNKNOWN`, horodatée à la date de modification du fichier.
- La dernière entrée du fichier n'est indexée que si elle est **complète** : elle se termine par `\n` **et** le fichier n'a pas été modifié depuis au moins 1 s (sinon une stack trace à moitié écrite serait coupée en deux). Sinon `scan_offset` reste à son début et elle sera relue au scan suivant.
- Taille maximale d'une entrée affichée : 1 Mio ; au-delà le contenu est tronqué à l'affichage avec la mention « entrée tronquée » (l'index garde les vrais offsets).
### 5.4 Rotation et troncature
Au scan, si `taille actuelle < scan_offset` **ou** `file_identity` a changé :
- l'index des entrées du fichier est purgé ;
- `scan_offset = 0`, `read_offset = 0` ;
- le fichier est relu depuis le début ; tout son contenu est non-lu.
### 5.5 Rafraîchissement et notification
- Le client appelle `unread_summary` au chargement de la page puis toutes les `refresh_interval_seconds` secondes.
- Le nouvel intervalle s'applique dès l'enregistrement, sans recharger la page (le timer est recréé).
- Le favicon est un SVG 32×32 généré côté client (URL `data:`) :
- `total = 0` → icône normale ;
- `total ≥ 1` → icône + pastille rouge avec le nombre (`99+` au-delà de 99) ;
- serveur injoignable → icône + pastille grise « ! ».
- Le titre de l'onglet devient `(N) Lara Logs Reader` quand `N ≥ 1`, `Lara Logs Reader` sinon.
- Le favicon change même si l'onglet est en arrière-plan (les timers en arrière-plan peuvent être ralentis par le navigateur jusqu'à 1 fois par minute : comportement accepté).
### 5.6 Marquage comme lu
- Ouvrir un fichier affiche ses entrées les plus récentes et appelle `mark_read(file, scan_offset_affiché)`.
- Si la vue d'un fichier est ouverte et que de nouvelles entrées arrivent, elles sont ajoutées en haut, surlignées, et marquées lues **seulement si l'onglet est visible** (`document.visibilityState == "visible"`).
- `mark_read` ne fait jamais reculer un curseur : `read_offset = max(read_offset, min(up_to_offset, scan_offset))`.
- Bouton « Tout marquer comme lu » par projet et global.
### 5.7 Interface
- **Barre latérale** : liste des projets, chacun dépliable en liste de fichiers (chemin relatif, taille, badge de non-lus). Fichiers manquants grisés. Un projet replié le reste aux rafraîchissements.
- **Tri des fichiers** : par nom (alphabétique, défaut) ou par date de dernière modification (le plus récent en premier, sans date en dernier, nom en départage). Trié par date, l'ancienneté (« il y a 3 h ») remplace la taille. Le choix s'applique à tous les projets et est enregistré dans `settings` (`file_sort`).
- **Formulaire d'ajout** : champ chemin + nom optionnel, message d'erreur sous le champ.
- **Vue fichier** : entrées triées du plus récent au plus ancien, 50 par page, bouton « Charger plus ». Chaque entrée : date, niveau (badge coloré), environnement, première ligne ; le reste (stack trace) est repliable. Filtres par niveau (cases à cocher ; les niveaux absents du fichier sont grisés et désactivés, et se réactivent dès qu'une entrée de ce niveau apparaît) et recherche texte (insensible à la casse, sur le contenu complet de l'entrée).
- **Réglages** : intervalle en secondes (champ numérique, 1–3600).
---
## 6. User stories et critères d'acceptation
Convention : `Given / When / Then`. « Écrire une entrée » signifie ajouter au fichier une ligne `[2026-10-21 10:00:00] local.ERROR: message\n`. Tous les délais s'entendent avec un intervalle de 1 s sauf mention contraire.
### US-01 — Ajouter un projet
> En tant que développeur, je veux ajouter un projet Laravel en saisissant son chemin, afin de surveiller ses logs.
- **AC-01.1** Given un répertoire `/tmp/app` avec `artisan` et `storage/logs/laravel.log`, When j'ajoute `/tmp/app`, Then le projet `app` apparaît dans la liste avec le fichier `laravel.log`.
- **AC-01.2** Given le même répertoire, When j'ajoute `/tmp/app/` puis `/tmp/../tmp/app`, Then la 2ᵉ et la 3ᵉ tentative sont refusées avec « Ce projet est déjà enregistré ».
- **AC-01.3** Given un lien `/tmp/link → /tmp/app` et `/tmp/app` déjà enregistré, When j'ajoute `/tmp/link`, Then l'ajout est refusé (même chemin canonique).
- **AC-01.4** Given `laravel.log` contient 10 entrées, When j'ajoute le projet, Then le compteur de non-lus du projet vaut 0.
- **AC-01.5** Given un nom saisi « Mon API », When j'ajoute le projet, Then il s'affiche sous le nom « Mon API ».
- **AC-01.6** Given `~/code/app` valide, When je saisis `~/code/app`, Then le projet est enregistré avec le chemin absolu.
### US-02 — Lister tous les fichiers de log d'un projet
> En tant que développeur, je veux voir tous les fichiers de log du projet, y compris les fichiers journaliers et les channels personnalisés.
- **AC-02.1** Given `storage/logs` contient `laravel.log`, `laravel-2026-10-20.log`, `jobs/worker.log`, `.gitignore`, `old.log.gz`, When le projet est affiché, Then exactement `laravel.log`, `laravel-2026-10-20.log` et `jobs/worker.log` sont listés.
- **AC-02.2** Given un projet enregistré, When un fichier `laravel-2026-10-22.log` est créé avec 2 entrées, Then il apparaît dans la liste avec 2 non-lus en ≤ 2 s.
- **AC-02.3** Given un fichier listé, When il est supprimé du disque, Then il est affiché grisé « manquant » en ≤ 2 s et ses non-lus ne comptent plus dans le total.
- **AC-02.4** Given `storage/logs/ext.log → /var/log/syslog` (lien hors de `storage/logs`), When le projet est scanné, Then `ext.log` n'est pas listé.
### US-03 — Consulter un fichier de log
> En tant que développeur, je veux lire les entrées d'un fichier, des plus récentes aux plus anciennes, avec leur stack trace.
- **AC-03.1** Given un fichier de 120 entrées, When je l'ouvre, Then les 50 plus récentes s'affichent, la première étant la dernière écrite ; « Charger plus » affiche les 50 suivantes puis les 20 dernières et disparaît.
- **AC-03.2** Given une entrée `ERROR` suivie de 30 lignes de stack trace, When elle s'affiche, Then elle compte pour **une** entrée, la première ligne est visible et les 30 lignes sont repliées par défaut.
- **AC-03.3** Given une entrée en cours d'écriture (sans `\n` final, ou fichier modifié il y a moins de 1 s), When le fichier est affiché, Then cette entrée n'apparaît pas ; When elle est terminée et le fichier inchangé depuis 1 s, Then elle apparaît au rafraîchissement suivant.
- **AC-03.4** Given un fichier contenant des octets non UTF-8, When il est affiché, Then les entrées s'affichent avec le caractère `�` à la place des octets invalides, sans erreur.
- **AC-03.5** Given un fichier de 1 Gio, When je l'ouvre, Then la première page s'affiche en < 2 s après l'indexation initiale et la mémoire du serveur reste < 200 Mio.
### US-04 — Configurer l'intervalle de rafraîchissement
> En tant que développeur, je veux choisir la fréquence de lecture des logs, pour arbitrer entre réactivité et charge.
- **AC-04.1** Given une première installation, When j'ouvre les réglages, Then l'intervalle vaut 5 s.
- **AC-04.2** Given l'intervalle à 5 s, When je saisis 30 et j'enregistre, Then le client n'appelle plus `unread_summary` qu'une fois toutes les 30 s (± 1 s), sans rechargement de page.
- **AC-04.3** When je saisis `0`, `3601`, `-5`, `abc` ou une valeur vide, Then l'enregistrement est refusé avec « L'intervalle doit être un entier entre 1 et 3600 secondes » et la valeur précédente est conservée.
- **AC-04.4** Given l'intervalle à 30 s, When je redémarre le serveur, Then l'intervalle vaut toujours 30 s.
### US-05 — Être notifié des nouvelles entrées par le favicon
> En tant que développeur, je veux voir dans l'onglet du navigateur s'il y a de nouveaux logs, sans avoir à regarder l'application.
- **AC-05.1** Given 0 non-lu, When 3 entrées sont écrites dans un fichier suivi, Then en ≤ intervalle + 1 s le favicon porte une pastille « 3 » et le titre est `(3) Lara Logs Reader`.
- **AC-05.2** Given 2 non-lus dans `a.log` et 1 dans `b.log` (même projet ou non), Then la pastille affiche « 3 ».
- **AC-05.3** Given 150 non-lus, Then la pastille affiche « 99+ » et le titre `(150) Lara Logs Reader`.
- **AC-05.4** Given des non-lus, When tout est marqué comme lu, Then le favicon redevient normal et le titre `Lara Logs Reader` sans attendre le prochain poll.
- **AC-05.5** Given le serveur arrêté, When un poll échoue, Then le favicon affiche la pastille grise « ! » ; When le serveur redémarre, Then au poll suivant le favicon reflète à nouveau le nombre de non-lus.
- **AC-05.6** Given `laravel.log` vidé (`> laravel.log`) puis 2 entrées écrites, Then le fichier compte 2 non-lus.
### US-06 — Marquer comme lu
> En tant que développeur, je veux que les entrées que j'ai consultées ne soient plus signalées.
- **AC-06.1** Given `a.log` avec 4 non-lus, When j'ouvre `a.log`, Then son badge passe à 0 et le total diminue de 4.
- **AC-06.2** Given `a.log` ouvert et l'onglet visible, When 2 entrées sont écrites, Then elles apparaissent surlignées en haut et le total reste à 0.
- **AC-06.3** Given `a.log` ouvert et l'onglet en arrière-plan, When 2 entrées sont écrites, Then le total passe à 2 ; When je reviens sur l'onglet, Then il repasse à 0.
- **AC-06.4** Given 2 projets avec des non-lus, When je clique « Tout marquer comme lu » sur le projet A, Then seuls les compteurs de A passent à 0.
- **AC-06.5** Given deux onglets ouverts, When je marque lu dans l'onglet 1, Then l'onglet 2 reflète 0 non-lu au poll suivant.
### US-07 — Supprimer un projet
> En tant que développeur, je veux retirer un projet que je ne surveille plus.
- **AC-07.1** Given un projet avec 5 non-lus, When je le supprime et confirme, Then il disparaît de la liste, le total diminue de 5, et aucune ligne liée ne reste dans `log_files`, `log_entries_index`, `read_cursors`.
- **AC-07.2** Given un projet supprimé, When je l'ajoute à nouveau, Then l'ajout réussit et les entrées existantes ne sont pas comptées comme non-lues (cf. AC-01.4).
- **AC-07.3** When je supprime un projet, Then aucun fichier du projet sur le disque n'est modifié (mtime et contenu identiques).
### US-08 — Filtrer et rechercher
> En tant que développeur, je veux isoler les erreurs ou retrouver un message précis.
- **AC-08.1** Given 10 `INFO` et 3 `ERROR`, When je ne coche que `ERROR`, Then 3 entrées s'affichent.
- **AC-08.2** Given une entrée contenant `SQLSTATE[23000]` dans sa stack trace, When je recherche `sqlstate`, Then elle est affichée.
- **AC-08.3** Given des filtres actifs, Then les compteurs de non-lus ne sont pas affectés par les filtres.
- **AC-08.4** Given `aaa.log` ne contient que des `INFO`, When je l'ouvre, Then seule la case `INFO` est active, les autres sont grisées et désactivées ; When une entrée `CRITICAL` y est écrite, Then la case `CRITICAL` devient active au rafraîchissement suivant.
- **AC-08.5** Given tous les niveaux cochés, When je double-clique sur `ERROR`, Then seule la case `ERROR` est cochée et seules les entrées `ERROR` s'affichent ; When je double-clique à nouveau sur `ERROR`, Then tous les niveaux sont recochés. Un double-clic sur un niveau désactivé est sans effet.
### US-10 — Trier les fichiers
> En tant que développeur, je veux trier les fichiers d'un projet par nom ou par date de modification, pour trouver vite le log actif.
- **AC-10.1** Given `aaa.log` (modifié il y a 2 j), `laravel.log` (3 h), `zzz.log` (10 s), When je choisis « Nom », Then l'ordre est `aaa.log`, `laravel.log`, `zzz.log`.
- **AC-10.2** Given les mêmes fichiers, When je choisis « Date », Then l'ordre est `zzz.log`, `laravel.log`, `aaa.log` et chaque ligne affiche son ancienneté.
- **AC-10.3** Given le tri « Date », When je recharge la page ou redémarre le serveur, Then le tri « Date » est conservé.
- **AC-10.4** Given un projet replié, When je change de tri, Then il reste replié.
### US-09 — Conserver l'état entre deux redémarrages
> En tant que développeur, je veux retrouver mes projets et mes compteurs après un redémarrage.
- **AC-09.1** Given 2 projets et 7 non-lus, When je redémarre le serveur, Then les 2 projets et les 7 non-lus sont retrouvés.
- **AC-09.2** Given le serveur arrêté, When 3 entrées sont écrites puis le serveur redémarré, Then le total vaut 7 + 3 = 10.
- **AC-09.3** Given le serveur arrêté, When `laravel.log` est roté (renommé puis recréé), Then au redémarrage la rotation est détectée et le nouveau fichier est relu depuis le début.
---
## 7. Cas d'erreur
| # | Cas | Détection | Comportement attendu | Message utilisateur |
|---|---|---|---|---|
| E01 | Chemin vide | Validation client et serveur | Refus | « Veuillez saisir un chemin. » |
| E02 | Chemin inexistant | `canonicalize` → `NotFound` | Refus, rien en base | « Le chemin `<p>` n'existe pas. » |
| E03 | Chemin vers un fichier | `!is_dir()` | Refus | « `<p>` n'est pas un répertoire. » |
| E04 | Pas un projet Laravel | `artisan` absent | Refus | « `<p>` ne semble pas être un projet Laravel (fichier `artisan` introuvable). » |
| E05 | `storage/logs` absent | Absence du répertoire | Refus | « Répertoire `storage/logs` introuvable. » |
| E06 | Permission refusée à l'ajout | `PermissionDenied` | Refus | « Accès refusé à `<p>`. » |
| E07 | Projet déjà enregistré | Contrainte `UNIQUE(root_path)` après canonicalisation | Refus, projet existant mis en évidence | « Ce projet est déjà enregistré. » |
| E08 | Aucun fichier `.log` | Découverte vide | Ajout accepté, liste vide | « Aucun fichier de log pour l'instant. » |
| E09 | Projet supprimé/déplacé du disque après ajout | Racine introuvable au scan | Projet conservé, marqué en erreur, ses fichiers ne comptent plus ; reprise automatique si le chemin revient | « Projet introuvable sur le disque. » |
| E10 | Fichier illisible (permissions changées) | `PermissionDenied` à l'ouverture | `last_error` renseigné, offsets inchangés, les autres fichiers continuent d'être scannés | Icône d'alerte sur le fichier + info-bulle |
| E11 | Fichier supprimé entre deux scans | `NotFound` | `missing_since` renseigné (cf. 5.2) | « Fichier manquant » |
| E12 | Fichier roté ou tronqué | Taille < `scan_offset` ou identité changée | Reset (cf. 5.4) | — |
| E13 | Entrée partielle en fin de fichier | Pas de `\n` final | Non indexée, relue au scan suivant | — |
| E14 | Octets non UTF-8 | Décodage | Remplacement par `�` | — |
| E15 | Texte sans ligne d'en-tête valide | Regex | Entrée `UNKNOWN` (cf. 5.3) | — |
| E16 | Fichier très volumineux | — | Lecture par blocs ; jamais de chargement complet | — |
| E17 | Entrée gigantesque (> 1 Mio) | Taille `end - start` | Affichage tronqué | « Entrée tronquée (X Mio). » |
| E18 | Intervalle invalide | Validation client et serveur | Refus, ancienne valeur conservée | cf. AC-04.3 |
| E19 | `log_file_id` / `project_id` inconnu | Requête vide | Erreur 404 de la server function | « Élément introuvable, la liste a été rafraîchie. » |
| E20 | Base SQLite inaccessible au démarrage | Échec de connexion/migration | Arrêt du processus, code de sortie ≠ 0 | Log console explicite avec le chemin |
| E21 | Base verrouillée en cours d'exécution | `SQLITE_BUSY` | `busy_timeout` de 5 s, puis erreur renvoyée au client ; aucun état partiel (transaction) | « Base de données occupée, nouvel essai au prochain rafraîchissement. » |
| E22 | Base corrompue | `PRAGMA quick_check` au démarrage | Arrêt du processus | Log console explicite |
| E23 | Port déjà utilisé | `bind` échoue | Arrêt, code de sortie ≠ 0 | « L'adresse `<addr>` est déjà utilisée. » |
| E24 | Serveur injoignable côté client | Échec réseau du poll | Favicon gris « ! », bandeau discret ; on continue de poller au même intervalle | « Serveur injoignable. » |
| E25 | Scans simultanés (plusieurs onglets) | Mutex par projet | Un seul scan à la fois, résultats partagés ; pas de double indexation | — |
---
## 8. Invariants
Ces propriétés doivent être vraies après toute opération et peuvent être vérifiées par tests (y compris tests de propriétés).
- **INV-01 Lecture seule** — L'application n'ouvre jamais un fichier de projet en écriture ; elle ne crée, ne renomme, ne supprime ni ne modifie aucun fichier hors de sa propre base.
- **INV-02 Ordre des offsets** — Pour tout fichier présent : `0 ≤ read_offset ≤ scan_offset ≤ size`.
- **INV-03 Index cohérent** — Les entrées indexées d'un fichier sont disjointes, contiguës et triées : pour deux entrées consécutives `e1, e2`, `e1.end_offset = e2.start_offset` ; la dernière se termine à `scan_offset` ; `entries_count` = nombre de lignes d'index.
- **INV-04 Aucune entrée partielle ni doublon** — Chaque entrée complète du fichier est indexée exactement une fois ; aucune entrée incomplète n'est indexée.
- **INV-05 Calcul des non-lus** — `unread(f)` = nombre d'entrées indexées de `f` avec `start_offset ≥ read_offset` ; `unread(f) ≥ 0` ; `unread(f) = 0` si `f` est manquant ; `total = Σ unread(f)` sur les fichiers présents des projets accessibles.
- **INV-06 Le curseur n'avance que par l'utilisateur** — Un scan ne fait jamais avancer `read_offset` ; seuls `mark_read`, `mark_all_read` et l'ajout initial d'un projet (5.1) le font avancer. Seule une rotation (5.4) le fait reculer (à 0).
- **INV-07 Monotonie hors rotation** — En l'absence de rotation, `scan_offset` et `read_offset` sont croissants dans le temps.
- **INV-08 Confinement** — Tout fichier suivi a un chemin canonique sous `<root_path>/storage/logs`.
- **INV-09 Unicité** — Un chemin canonique correspond à au plus un projet ; un couple (projet, chemin relatif) à au plus un fichier.
- **INV-10 Cascade** — Après suppression d'un projet, aucune ligne de `log_files`, `log_entries_index` ou `read_cursors` ne le référence.
- **INV-11 Bornes de l'intervalle** — `refresh_interval_seconds` stocké est toujours un entier dans `[1, 3600]`.
- **INV-12 Persistance** — Sans changement des fichiers sur le disque, un redémarrage ne change aucun compteur de non-lus.
- **INV-13 Idempotence du scan** — Deux scans successifs sans modification des fichiers produisent le même état en base.
- **INV-14 Atomicité** — Le scan d'un fichier (mise à jour de l'index + `scan_offset`) est fait dans une seule transaction : un crash au milieu laisse l'état précédent.
- **INV-15 Favicon fidèle** — Le nombre affiché par le favicon est égal au `total` de la dernière réponse `unread_summary` réussie (ou au résultat de la dernière action `mark_*`), borné à l'affichage à `99+`.
---
## 9. Exigences non fonctionnelles
| Domaine | Exigence |
|---|---|
| Sécurité | Écoute par défaut sur `127.0.0.1` uniquement. Aucun contenu de log n'est injecté en HTML brut (échappement systématique par Leptos). |
| Performance | `unread_summary` < 100 ms avec 10 projets / 50 fichiers sans nouvelle donnée. Indexation initiale d'un fichier de 1 Gio < 30 s, mémoire < 200 Mio. |
| Robustesse | L'erreur d'un fichier ou d'un projet n'empêche jamais le scan des autres. |
| Portabilité | Linux et macOS en priorité ; Windows : identité de fichier via file index, chemins non sensibles à la casse. |
| Accessibilité | Le nombre de non-lus est aussi exposé en texte (titre + badges) et pas seulement par la couleur. |
---
## 10. Stratégie de test
- **Unitaires** : parser (en-têtes valides/invalides, multi-lignes, entrée partielle, UTF-8 invalide, fuseaux horaires, microsecondes), détection de rotation, validation de chemin et d'intervalle, calcul de `mark_read` (non-régression du curseur).
- **Propriétés** (`proptest`) : écrire des séquences aléatoires d'entrées en morceaux arbitraires, scanner entre chaque morceau, vérifier INV-02 à INV-05 et INV-13.
- **Intégration** : serveur axum sur port aléatoire + SQLite temporaire + projet Laravel factice dans un `tempdir` ; dérouler les AC des US-01 à US-09 via les server functions.
- **E2E** (Playwright) : AC-04.2, AC-05.1, AC-05.3, AC-05.4, AC-05.5, AC-06.2, AC-06.3 — lecture de `document.title` et de l'attribut `href` du `<link rel="icon">`.
---
## 11. Questions ouvertes
1. Faut-il une vue agrégée « toutes les nouvelles entrées, tous projets confondus » ?
2. Faut-il filtrer les non-lus par niveau (ex. ne notifier que `ERROR` et au-dessus) ?
3. Faut-il ajouter les notifications natives du navigateur (Notification API) en plus du favicon ?
4. Faut-il purger l'index des fichiers manquants depuis plus de N jours ?
5. Faut-il supporter le format JSON de Monolog (`JsonFormatter`) ?