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-12

---

⚙️ 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
BUG-005	Sur mobile via Cloudflare (og.dracodev.net), le site ne charge pas complètement même après purge des caches (téléphone + Cloudflare)	🟢 corrigé	P1	📱 frontend + ⚙️ backend	IA	frontend/sw.js, frontend/index.html, frontend/js/sync.js, backend/main.py	Ouvrir og.dracodev.net sur mobile (PWA installée), purger les caches, recharger	SW network-first pour le code + caches versionnés (SW_VERSION) ; précache corrigé (/static/js/…) ; migration ponctuelle localStorage ; Cache-Control: no-cache (le middleware renvoyait immutable 1 an sur /static) ; tests tests/frontend/sw.test.mjs + TestStaticCaching	Cause : SW cache-first à nom fixe + en-têtes immutable non fingerprinted → ancien build servi indéfiniment (Cache Storage ≠ cache navigateur/CF). Vérifié : 754 tests backend, frontend OK
BUG-006	Clé API DeepSeek réelle commitée en clair dans .env.example	🟢 corrigé	P0	📄 docs + 🔐 sécurité	IA	.env.example	git grep "sk-" .env.example	.env.example : clé remplacée par un placeholder (sk-xxx…) + modèle deepseek-chat	⚠️ Rotation de la clé requise : elle reste dans l'historique Git → révoquer/régénérer côté DeepSeek. Le fichier .env (réel) est bien gitignoré
BUG-007	Assistant IA : menus / et @ — navigation clavier ↑/↓ inopérante et filtrage des skills cassé par les accents	🟢 corrigé	P1	📱 frontend	IA	frontend/js/bookslm.js	Taper /résumé ou @café, puis ↑/↓	bookslm.js : motifs Unicode \p{L} (détection + sélection), recherche normalisée NFD (insensible aux accents), jeton _menuSeq (rendus async obsolètes), scrollIntoView de l'élément actif	Le menu se fermait dès la saisie d'un accent ; la frappe rapide pouvait écraser le menu avec un résultat obsolète. Tests : tests/frontend/ai.test.mjs (+3)
BUG-008	Assistant IA : commande @ — chemins accentués + contexte ad-hoc ignoré en mode Général	🟢 corrigé	P1	📱 frontend + ⚙️ backend	IA	frontend/js/bookslm.js, backend/bookslm_routes.py	@fichier-accentué puis envoyer en mode Général	Frontend : détection Unicode + repli vault=all sans vault courant. Backend : _resolve_system_prompt résout le vault optionnel dès qu'un contexte @ est présent (mode Général)	Le backend ignorait extra_files/extra_directories en mode Général (vault_path is None). Tests : tests/test_bookslm.py (+2) et tests/frontend/ai.test.mjs
BUG-009	Assistant IA : liste de modèles corrompue (art ASCII) et clés i18n brutes (ai.model_search) sous OpenRouter	🟢 corrigé	P1	📱 frontend	IA	frontend/js/ai.js, frontend/js/i18n.js, frontend/sw.js, frontend/style.css	Ouvrir le menu modèle sous « openrouter »	Locale non content-hashée en cache HTTP → cache:'no-store' + bump SW_VERSION v4 ; styles critiques du picker appliqués en ligne (popover absolu, liste en colonne, options display:block) ; rendu plafonné à 200 modèles + indicateur « … N autres »	OpenRouter expose plusieurs centaines de modèles ; si style.css est en cache, la liste s'affichait en bloc inline (art ASCII) et les clés i18n brutes provenaient d'un fr.json obsolète. Tests : tests/frontend/ai.test.mjs (+1)
BUG-010	Assistant IA : la commande @ n'ajoute pas le contexte à la requête en mode Général	🟢 corrigé	P1	📱 frontend	IA	frontend/js/bookslm.js	Assistant en mode Général, taper @fichier, sélectionner, envoyer	Capture du vault renvoyé par /api/tree-search dans la sélection @ ; _contextVault() propage ce vault aux requêtes /context et /chat ; recherches @ suivantes limitées à ce vault	En mode Général, _vault est nul : la requête partait sans vault et le backend ignorait extra_files. Tests : tests/frontend/ai.test.mjs (+1)
BUG-011	Assistant IA : noms de modèles illisibles dans la liste déroulante	🟢 corrigé	P2	📱 frontend	IA	frontend/js/ai.js, frontend/style.css	Ouvrir le menu modèle dans la barre latérale de l'assistant	Popover aligné à droite du déclencheur (right:0), largeur 340 px bornée à 100vw - 24px, noms sur plusieurs lignes (overflow-wrap:anywhere, police 0,78 rem) + title	La liste s'ouvrait vers la droite et dépassait le bord de la sidebar ancrée à droite ; noms tronqués. Tests : tests/frontend/ai.test.mjs

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)
2026-09-11	BUG-005	Correction	frontend/sw.js, frontend/index.html, frontend/js/sync.js, backend/main.py, .gitea/workflows/ci.yml, tests/frontend/sw.test.mjs, tests/test_api_main.py	BUG-005: chargement mobile incomplet via Cloudflare. SW réécrit en network-first pour HTML/JS/CSS + caches versionnés ; précache corrigé (/static/js/…) ; kill-switch de session remplacé par une migration localStorage ponctuelle ; en-têtes /static passés de immutable 1 an à no-cache ; index.html/manifest/SPA en no-cache ; reload unique sur controllerchange. Vérifié: 754 tests backend, frontend 9+28+8 OK, ruff/mypy OK.	🟢 corrigé (en attente vérif utilisateur)
2026-09-11	BUG-006	Correction sécurité	.env.example	Clé API DeepSeek réelle exposée dans .env.example → remplacée par un placeholder. Rotation de la clé à faire côté DeepSeek (présente dans l'historique Git).	🟢 corrigé (rotation à confirmer par l'utilisateur)
2026-09-12	BUG-007, BUG-008, #82	Correction + refonte UI	frontend/js/bookslm.js, frontend/js/ai.js, frontend/style.css, frontend/locales/{fr,en}.json, backend/bookslm_routes.py, tests/frontend/ai.test.mjs, tests/test_bookslm.py	BUG-007 : motifs Unicode + recherche NFD insensible aux accents + navigation ↑/↓ fiabilisée (jeton de séquence, scrollIntoView). BUG-008 : contexte ad-hoc @ pris en compte en mode Général (backend) + repli vault=all. #82 : section « Fournisseur & modèle » compacte (recherche modèle + bulle capacités ℹ️ au survol/clic/appui long). Vérifié : tests frontend 41/41, tests/test_bookslm.py 47 passed.	🟢 corrigé (en attente vérif utilisateur)
2026-09-12	BUG-009	Correction	frontend/js/ai.js, frontend/js/i18n.js, frontend/sw.js, frontend/style.css, frontend/locales/{fr,en}.json, tests/frontend/ai.test.mjs	BUG-009 : locale non content-hashée servie depuis le cache HTTP → clés i18n brutes ; passage en cache:'no-store' + SW_VERSION v4. Liste de modèles corrompue (OpenRouter, styles en cache) → styles critiques en ligne, options display:block, plafond 200 + indicateur. Vérifié : tests frontend 42/42.	🟢 corrigé (en attente vérif utilisateur)
2026-09-12	BUG-010, BUG-011	Correction	frontend/js/bookslm.js, frontend/js/ai.js, frontend/style.css, tests/frontend/ai.test.mjs	BUG-010 : capture du vault des résultats @ + _contextVault() propagé aux requêtes /context//chat (mode Général). BUG-011 : popover modèle aligné à droite, largeur 340 px, noms multi-lignes + title. Vérifié en navigateur (Playwright) et tests frontend 43/43.	🟢 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