# 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 :**
```bash
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)

```markdown
# 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 :

```markdown
## 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 :

```markdown
## [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