> **IMPORTANT — Lire d'abord** > Ce document utilise un **format tabulaire simple et rigoureux** conçu pour être > maintenu à la fois par un humain (éditeur texte) et par un agent IA. Les règles > exactes sont définies dans la section **« Comment fonctionne ce document »**. > La procédure de livraison obligatoire (tests, docs, commit, push, CI) est définie > dans [`DELIVERY_WORKFLOW.md`](./DELIVERY_WORKFLOW.md). # 🐛 ObsiGate — Suivi des Bugs / TODO de Correction > **Rôle du document** : registre unique et vivant des bugs découverts et des corrections > à apporter au projet **ObsiGate** (application Web + desktop Tauri). > C'est l'**outil de communication commun** entre l'utilisateur humain et l'IA > qui effectue les corrections dans le code. - **Projet** : ObsiGate — Porte d'entrée web pour vaults Obsidian - **Stack** : Python 3.11+ (backend FastAPI) · JavaScript/Vanilla (frontend) · Tauri/Rust (desktop) - **Dernière mise à jour** : 2026-09-11 --- ## ⚙️ Comment fonctionne ce document (À LIRE ABSOLUMENT) Ce document est un **contrat de travail partagé**. Suivez les règles ci-dessous pour qu'un humain OU un agent IA puisse le lire, le modifier et l'exploiter sans ambiguïté. ### 1. Une table = un état (workflow par rangée) Chaque bug/TODO est une **rangée** dans la section [📋 Registre des bugs / TODOs](#-registre-des-bugs--todos). Une rangée ne change **jamais de table** au fil de sa vie ; c'est la **colonne « Statut »** qui encode son avancement : | Statut (colonne) | Signification | Qui peut le poser | |---|---|---| | `🔴 ouvert` | Bug confirmé / tâche à faire, en attente de traitement | Utilisateur **ou** IA | | `🟠 en cours` | Un agent IA a **commencé** à corriger | IA uniquement | | `🟢 corrigé` | La correction est écrite **et** vérifiée (tests OK) | IA uniquement | | `✅ vérifié` | L'utilisateur (ou les tests) a **validé** le correctif | Utilisateur uniquement | | `⚪ abandonné` | Décision de ne pas corriger (documentée dans notes) | Utilisateur ou IA | ### 2. Cycle de vie d'un bug (workflow) ```mermaid flowchart LR A[🔴 ouvert
Découverte d'un bug] --> B[🟠 en cours
IA travaille dessus] B --> C[🟢 corrigé
Correctif écrit + tests OK] C --> D[✅ vérifié
Re-validation par l'utilisateur] C --> E[⚪ abandonné
Refus / hors périmètre] D --> F[✅ Fermé : lignée conservée en historique] ``` 1. **Un bug est signalé** → posé en `🔴 ouvert` par l'utilisateur **ou** l'IA (à l'issue d'une investigation ou d'une session de test). 2. **L'IA prend en charge** → passe le statut en `🟠 en cours` **avant** de commencer à coder, et crée une entrée dans [🛠️ Journal des interventions AI](#-journal-des-interventions-ai). 3. **La correction est terminée** → l'IA exécute les tests pertinents, passe le statut en `🟢 corrigé` et remplit la colonne « Correctif / Commit ». 4. **Validation finale** → c'est l'utilisateur qui passe en `✅ vérifié` une fois le correctif contrôlé. Les rangées `✅ vérifié` sont **déplacées dans l'historique** périodiquement. 5. **Abandon** → justifié obligatoirement dans la colonne « Notes / Scope ». > ⚠️ **Ne JAMAIS supprimer** une rangée terminée : déplacez-la dans la section > [📜 Historique des bugs résolus](#-historique-des-bugs-résolus) à la place. ### 3. Ordre de lecture pour un agent IA Avant de corriger quoi que ce soit, un agent IA doit : 1. **Lire ce fichier en entier** (en particulier ce guide et le registre). 2. **Identifier** les rangées de statut `🔴 ouvert` avec un **scope `IA`** et une **priorité** élevée qui lui sont attribuées (colonne « Assigné »). 3. **Poser le statut `🟠 en cours`** sur la rangée choisie **avant** toute modification de code. 4. Corriger en respectant la [checklist de vérification](#-checklist-de-traitement-dun-bug-rappel-pour-toute-ia) et les [conventions du projet](CONTRIBUTING.md). 5. Revenir mettre le statut à `🟢 corrigé`, documenter le correctif, et **journaliser** son passage. 6. Ne pas marquer `✅ vérifié` lui-même (c'est un droit utilisateur, sauf mention contraire explicite). ### 4. Identifiants uniques (ID) - Chaque bug porte un **ID stable** `BUG-###` ou `TODO-###` (voir le format dans le registre). - L'ID **ne change jamais**, même après résolution. Il permet de retrouver le bug dans l'historique et dans le journal d'interventions. - Le format du numéro est `###` = 3 chiffres incrémental (001, 002, 003…). - Si vous (IA) créez un nouveau bug, **reprenez le plus grand numéro existant + 1** dans le registre, quel que soit l'ordre des lignes. ### 5. Comment mettre à jour ce document (bonnes pratiques) - **Formatage** : garder les colonnes alignées par des espaces pour la lisibilité brute. Une rangée = une seule ligne de tableau Markdown. - **Copier-coller** : pour ajouter un bug, dupliquez une ligne existante puis modifiez les champs. - **Ne pas casser** : conservez le séparateur d'en-tête `|---|---|…|` et les **champs fixes** (#, Titre, Statut, Priorité, Scope, Assigné, Zone, Cmd de repro, Correctif/Commit, Notes). - **Frontière des rôles** : un agent IA ne doit **jamais** se passer à lui-même une rangée en `✅ vérifié` ; il s'arrête à `🟢 corrigé` (sauf si l'utilisateur l'y autorise explicitement). --- ## 📋 Registre des bugs / TODOs > **Légende colonnes :** > - **Statut** : `🔴 ouvert` | `🟠 en cours` | `🟢 corrigé` | `✅ vérifié` | `⚪ abandonné` > - **Priorité** : `P0` (critique/bloquant) · `P1` (élevée) · `P2` (normale) · `P3` (basse/cosmétique) > - **Scope** : `📱 frontend` · `⚙️ backend` · `🔌 api` · `🧩 tests` · `🖥️ desktop` · `📦 build` · `📄 docs` · `🤖 ia` · `❓ inconnu` (À affiner par l'IA) > - **Assigné** : `IA` (à traiter par un agent) · `USER` (à traiter par l'utilisateur) · `—` (non attribué) > - **Zone** : chemin/nom de fichier concerné (ex. `frontend/app.js`, `backend/search.py`) > - **Cmd de repro** : commande ou scénario permettant de reproduire / vérifier (vide si N/C) ### Bugs ouverts (à traiter) | # | Titre | Statut | Priorité | Scope | Assigné | Zone (fichier) | Cmd de repro | Correctif / Commit | Notes | |---|---|---|---|---|---|---|---|---|---| | *BUG-001* | L'ouverture des fichier PDF ne fonctionne pas et donne l'erreur Internal Server Error | 🟢 corrigé | P1 | fichier PDF | IA | `backend/main.py` | `GET /api/file/{vault}/pdf/stream?path=…(pdf à nom accentué)` | `backend/main.py` : Content-Disposition encodé RFC 5987 (helper `_content_disposition`) | 500 car nom Unicode brut dans l'en-tête → header invalide. Vérifié: stream 200 / Range 206 + test `tests/test_pdf_stream.py` | | *BUG-002* | l'ouverture d'un fichier .excalidraw ne fonctionne pas et affiche toujours Loading *Excalidraw…* | 🟢 corrigé | P1 | fichier .excalidraw | IA | `frontend/excalidraw-editor.html` | Ouvrir un fichier `.excalidraw` | `frontend/excalidraw-editor.html` : alias esm.sh supprimé (408 jotai) + React 19 cohérent + prop `excalidrawAPI` | 2 causes: 408 esm.sh sur `?alias` + prop legacy `excalidrawRef` inopérante en 0.18. Vérifié navigateur: Loading masqué + cycle save OK | | | | | | | | | | | | | *BUG-003* | `mypy` : 33 erreurs de typage (étape CI en mode advisory → bloquante) | 🟢 corrigé | P2 | ⚙️ backend | IA | `backend/{main,indexer,export,pdf_reader,bookslm_routes}.py`, `backend/auth/router.py`, `.gitea/workflows/ci.yml` | `mypy backend/ --ignore-missing-imports` | Annotations de types, gardes `None` (auth/router), import `PROVIDERS` manquant (bug latent `main.py:4523`), `PdfReader: Any` ; CI mypy rendu bloquant | 0 erreur après correction. `PROVIDERS` non importé → `NameError` avalé par le `except` (le modèle par défaut n'était jamais prépendé). Tests : 728 passed | | *BUG-004* | Lien cassé vers `CONTRIBUTING.md` dans `README.md` | 🟢 corrigé | P3 | 📄 docs | IA | `README.md` | Cliquer le lien « Contributing » | `README.md` : lien → `docs/CONTRIBUTING.md` (+ `DELIVERY_WORKFLOW.md`) ; arbre du projet corrigé | `README.fr.md` pointait déjà correctement vers `./docs/CONTRIBUTING.md` | ### TODOs techniques (améliorations / nouvelles tâches) | # | Titre | Statut | Priorité | Scope | Assigné | Zone (fichier) | Cmd de repro | Correctif / Commit | Notes | |---|---|---|---|---|---|---|---|---|---| | *(exemple)* TODO-002 | Rendre l'index inversé incrémental (40k+ fichiers) | 🔴 ouvert | P1 | ⚙️ backend | IA | `backend/indexer.py`, `backend/search.py` | Recherche sur très gros vault | — | Exemple à remplacer. Cf. plan.md | | *(À remplir)* | | | | | | | | | | --- ## 🛠️ Journal des interventions AI > Chaque passage d'un agent IA qui modifie du code ou l'état du registre est journalisé. > **Règle** : l'IA ajoute **une ligne** à la fin de ce tableau à chaque session de correction. > Colonnes : `Date` (YYYY-MM-DD) · `ID(s) traité(s)` · `Action` · `Fichiers modifiés` · `Résumé` · `Statut après`. | Date | ID(s) traité(s) | Action | Fichiers modifiés | Résumé | Statut après | |---|---|---|---|---|---| | *(exemple)* 2026-06-15 | BUG-001 | Correction | `frontend/app.js` | Réécriture de `renderFile()` pour préserver le DOM dashboard | 🟢 corrigé (en attente vérif) | | 2026-09-09 | BUG-001, BUG-002 | Correction | `backend/main.py`, `frontend/excalidraw-editor.html`, `tests/test_pdf_stream.py` | BUG-001: Content-Disposition RFC 5987 (nom PDF accentué ne casse plus l'en-tête → plus de 500). BUG-002: suppression alias esm.sh (408 jotai) + React 19 cohérent + prop `excalidrawAPI` → Loading masqué, save OK. Vérifié: 534 tests backend verts + E2E navigateur. | 🟢 corrigé (en attente vérif utilisateur) | | 2026-09-11 | BUG-003, BUG-004 | Correction | `backend/{main,indexer,export,pdf_reader,bookslm_routes}.py`, `backend/auth/router.py`, `.gitea/workflows/ci.yml`, `README.md`, `README.fr.md` | BUG-003: 33 erreurs mypy corrigées (annotations, gardes `None`, import `PROVIDERS` manquant → bug latent) + étape CI mypy rendue bloquante. BUG-004: lien `README.md` → `docs/CONTRIBUTING.md`. Vérifié: mypy 0 erreur, ruff OK, pytest 728 passed, frontend OK. | 🟢 corrigé (en attente vérif utilisateur) | --- ## 📜 Historique des bugs résolus > Les rangées `✅ vérifié` (ou `⚪ abandonné`) sont déplacées ici régulièrement pour garder > le **registre actuel** court et lisible. Conservez l'ID d'origine pour la traçabilité. | # | Titre | Date résolution | Résolu par | Correctif / Commit | Notes | |---|---|---|---|---|---| | *(aucun pour l'instant)* | | | | | | --- ## 🧪 Procédure de vérification d'une correction (pour l'IA) Quand une correction est écrite, l'agent IA doit **avant** de passer en `🟢 corrigé` : 1. **Exécuter les tests** du projet : - Backend : `python -m pytest tests/ -v` (ou `pytest`) - S'il existe des tests ciblés sur la zone modifiée, les lancer en priorité. 2. **Vérifier le lancement** du module concerné (import sans erreur, endpoint répond). 3. **Relire sa propre diff** pour éviter les régressions. 4. Mettre la colonne « Correctif / Commit » à jour **puis** le statut en `🟢 corrigé`. 5. Si un test échoue ou que la correction est incomplète, **rester en `🟠 en cours`** et le noter. --- ## ✔️ Checklist de traitement d'un bug (rappel pour toute IA) - [ ] Bug identifié avec un **ID** et repris dans le [registre](#-registre-des-bugs--todos) - [ ] Statut posé en `🟠 en cours` avant de coder - [ ] Correction conforme aux [conventions du projet](CONTRIBUTING.md) - [ ] Tests exécutés et **vert** (colonne « Correctif / Commit » renseignée) - [ ] Journal des interventions AI mis à jour - [ ] Statut passé en `🟢 corrigé` (pas `✅ vérifié` sauf autorisation) - [ ] (Après validation utilisateur) rangée déplacée dans l'historique --- ## 📚 Liens utiles - **Guide de contribution** : [CONTRIBUTING.md](CONTRIBUTING.md) (conventions de code) - **Structure du projet** : [README.fr.md](../README.fr.md) - **Tests** : répertoire `tests/` — voir CONTRIBUTING - **Analyse/décisions complémentaires** : [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md), [ROADMAP.md](ROADMAP.md)