201 lines
5.8 KiB
Markdown
201 lines
5.8 KiB
Markdown
# 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
|