ObsiGate/docs/ISSUES_TODOLIST.md

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.

🐛 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. 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)

flowchart LR
    A[🔴 ouvert<br/>Découverte d'un bug] --> B[🟠 en cours<br/>IA travaille dessus]
    B --> C[🟢 corrigé<br/>Correctif écrit + tests OK]
    C --> D[✅ vérifié<br/>Re-validation par l'utilisateur]
    C --> E[⚪ abandonné<br/>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.
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 à 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 et les conventions du projet.
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
• Statut posé en 🟠 en cours avant de coder
• Correction conforme aux conventions du projet
• 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 (conventions de code)
• Structure du projet : README.fr.md
• Tests : répertoire tests/ — voir CONTRIBUTING
• Analyse/décisions complémentaires : IMPLEMENTATION_PLAN.md, ROADMAP.md