etm-terrain/CLAUDE_documentation.md

ETM Bot — Documentation complète du code

Contexte

Tu vas documenter le bot Telegram Python ETM-Schurig de façon complète. Cette documentation sera stockée dans Git et le Wiki Git (Gitea).

Avant de commencer, lire tout le code :

find . -name "*.py" | sort
find . -name "*.md" | sort
cat requirements.txt
cat .env.example  # ou .env si disponible

---

Ce que tu dois produire

1. README.md (racine du projet)

# ETM Bot — Bot Terrain Telegram

## Vue d'ensemble
[Description en 3-4 phrases : ce que fait le bot, pour qui, pourquoi]

## Architecture
[Schéma ASCII du projet — dossiers et fichiers clés avec leur rôle en une ligne]

## Prérequis
[Python version, dépendances système, services externes requis]

## Installation
[Étapes pas à pas — clone, pip install, .env, lancement]

## Configuration (.env)
[Tableau de toutes les variables avec description et exemple]

## Déploiement
[Systemd service, nginx si applicable]

## Utilisation
[Les 5 actions du bot avec exemple de conversation]

---

2. ARCHITECTURE.md

Document technique expliquant la structure globale :

• Schéma du flux de données — de la réception d'un message Telegram jusqu'à la notification finale, en passant par WebDAV Nextcloud
• Diagramme des états ConversationHandler — tous les états et transitions
• Interactions entre modules — qui appelle qui
• Schéma base de données SQLite — toutes les tables, colonnes, relations
• Structure ChromaDB — collections, métadonnées, format des documents indexés

Format : texte + diagrammes ASCII ou Mermaid si possible.

---

3. Documentation par module (un fichier par dossier)

docs/handlers.md

Pour chaque handler (fin_chantier.py, sav.py, materiel.py, maintenance.py, faq.py, menu.py, edit_handler.py) :

• Rôle : ce que fait ce handler en une phrase
• États gérés : quels états ConversationHandler il couvre
• Fonctions : signature + description + paramètres + retour
• Exemple de conversation : ce que voit l'utilisateur étape par étape
• Dépendances : quels services il appelle

docs/services.md

Pour chaque service (nextcloud.py, faq_service.py, chantier_selector.py, notifications.py) :

• Rôle du service
• Classe principale : attributs, méthodes publiques
• Chaque méthode : signature, description, paramètres, retour, erreurs possibles
• Exemple d'utilisation

docs/database.md

• Schéma complet de toutes les tables SQLite
• Rôle de chaque table et de chaque colonne
• Requêtes types utilisées dans le code
• Politique de rétention des données

docs/faq_rag.md

Document dédié au système FAQ/RAG :

• Comment fonctionne ChromaDB dans ce projet
• Format des documents indexés (SAV résolus vs documentation)
• Pipeline d'indexation : de /resolu → ChromaDB
• Pipeline de recherche : de /faq question → réponse
• Intégration Ollama : modèle utilisé, prompt système, fallback
• Comment ajouter des documents (notices constructeurs)
• Comment vider / réindexer la base

docs/deployment.md

• Prérequis VM (RAM, disque, OS)
• Installation complète pas à pas
• Configuration systemd avec explications de chaque directive
• Configuration nginx si applicable
• Variables d'environnement — toutes décrites
• Logs — où les trouver, comment les lire
• Mise à jour — procédure pour déployer une nouvelle version
• Backup — quoi sauvegarder (ChromaDB, SQLite, .env)

---

4. docs/guide_patrick.md — Guide administrateur

Pour Patrick uniquement — les commandes de gestion :

## Commandes bot disponibles pour Patrick

### /resolu — Clôturer un SAV
/resolu #2026-047 cause | solution | durée

### /faq — Tester la base de connaissances
/faq Fronius erreur 567

### Comment ajouter une notice constructeur à la FAQ
[Procédure pas à pas]

### Comment voir les tickets SAV ouverts
[Commande ou requête SQLite]

### Comment sauvegarder la base FAQ
[Commande backup ChromaDB]

---

5. CHANGELOG.md

Historique des versions avec les fonctionnalités implémentées :

## [1.0.0] — 2026-03-25
### Ajouté
- Menu 3 boutons : Fin de Chantier / SAV / Matériel Manquant
- Upload photos Nextcloud
- Notifications groupes Telegram
...

## [1.1.0] — date
### Ajouté
- Dropdown chantiers depuis Nextcloud
- Gestion albums multi-photos
- Bouton FAQ
- Commande /resolu + indexation ChromaDB
...

---

Règles de rédaction

• Langue : français pour tout (commentaires, docs, descriptions)
• Ton : technique mais accessible — un développeur junior doit comprendre
• Code : inclure des exemples concrets tirés du vrai code, pas inventés
• Diagrammes : préférer ASCII ou Mermaid (compatible Git Wiki)
• Exhaustivité : documenter TOUTES les fonctions publiques, même les simples utilitaires
• Exemples : chaque fonctionnalité doit avoir un exemple de conversation ou d'appel concret

---

Format de sortie attendu

Créer les fichiers directement dans le projet :

README.md                  ← remplacer ou créer
ARCHITECTURE.md            ← nouveau
CHANGELOG.md               ← nouveau
docs/
├── handlers.md
├── services.md
├── database.md
├── faq_rag.md
├── deployment.md
└── guide_patrick.md

---

Ordre de travail

1. Lire tout le code source en premier
2. Écrire README.md — vue d'ensemble
3. Écrire ARCHITECTURE.md — flux et schémas
4. Écrire docs/handlers.md — tous les handlers
5. Écrire docs/services.md — tous les services
6. Écrire docs/database.md — SQLite + ChromaDB
7. Écrire docs/faq_rag.md — système FAQ détaillé
8. Écrire docs/deployment.md — déploiement VM
9. Écrire docs/guide_patrick.md — guide admin
10. Écrire CHANGELOG.md — historique versions