Rapport Technique Détaillé

Bot Telegram de Vocabulaire Français

avec Stockage Notion et Génération IA

Telegram
+
Python
+
IA

Projet d’apprentissage par la pratique

Migration de n8n vers Python

10 février 2026

Version 1.0
Table des matières

1 Vue d’ensemble du projet 7

1.1 Résumé exécutif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.1 Architecture en un coup d’œil . . . . . . . . . . . . . . . . . . . . . 7
1.2 Problématique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Solution proposée . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 Contexte et objectifs 9
2.1 Objectifs fonctionnels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Objectifs pédagogiques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Objectifs techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.1 Principes architecturaux . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.2 Exigences non fonctionnelles . . . . . . . . . . . . . . . . . . . . . . 10

3 Architecture technique 11
3.1 Vue d’ensemble architecturale . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Diagramme de séquence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Choix technologiques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Spécifications fonctionnelles 13
4.1 Cas d’utilisation principal . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1 Scénario nominal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.2 Préconditions et postconditions . . . . . . . . . . . . . . . . . . . . 13
4.2 Cas d’utilisation alternatifs . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.1 Mot invalide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.2 Erreur API IA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.3 Erreur Notion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3 Format de données . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Spécifications techniques 15
5.1 Structure du projet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Dépendances Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.1 Fichier [Link] . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3 Variables d’environnement . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6 Flux de données 17
6.1 Flux nominal détaillé . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1.1 Phase 1 : Réception . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1.2 Phase 2 : Validation . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1
TABLE DES MATIÈRES 2

6.1.3 Phase 3 : Génération . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.1.4 Phase 4 : Réponse utilisateur . . . . . . . . . . . . . . . . . . . . . 18
6.1.5 Phase 5 : Stockage . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2 Gestion des flux d’erreur . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

7 Modules et responsabilités 20
7.1 [Link] - Configuration centralisée . . . . . . . . . . . . . . . . . . . . . . 20
7.1.1 Responsabilité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1.2 Fonctions principales . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1.3 Principe SOLID appliqué . . . . . . . . . . . . . . . . . . . . . . . . 20
7.2 telegram_handler.py - Gestion Telegram . . . . . . . . . . . . . . . . . . . 21
7.2.1 Responsabilité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2.2 Architecture du module . . . . . . . . . . . . . . . . . . . . . . . . 21
7.3 [Link] - Orchestration . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.3.1 Responsabilité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.3.2 Logique de validation . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.3.3 Orchestration du flux . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4 [Link] - Génération IA . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.4.1 Responsabilité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.4.2 Construction du prompt . . . . . . . . . . . . . . . . . . . . . . . . 23
7.4.3 Appel API avec gestion d’erreurs . . . . . . . . . . . . . . . . . . . 23
7.5 notion_handler.py - Stockage Notion . . . . . . . . . . . . . . . . . . . . . 24
7.5.1 Responsabilité . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.5.2 Construction du payload . . . . . . . . . . . . . . . . . . . . . . . . 24

8 Gestion des erreurs 26

8.1 Stratégie globale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.2 Matrice des erreurs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.3 Système de logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.3.1 Configuration des logs . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.3.2 Niveaux de log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.4 Mécanisme de retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

9 Sécurité 29
9.1 Menaces identifiées . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2 Bonnes pratiques implémentées . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.1 Gestion sécurisée des secrets . . . . . . . . . . . . . . . . . . . . . . 29
9.2.2 Validation rigoureuse des inputs . . . . . . . . . . . . . . . . . . . . 29
9.2.3 Rate limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.3 Fichier .gitignore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

10 Déploiement 32
10.1 Options d’hébergement gratuit . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.2 Déploiement sur Railway (recommandé) . . . . . . . . . . . . . . . . . . . 32
10.2.1 Étapes de déploiement . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.2.2 Fichier Procfile (optionnel) . . . . . . . . . . . . . . . . . . . . . . . 33
10.3 Déploiement sur Replit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Bot Telegram - Rapport Technique

TABLE DES MATIÈRES 3

10.3.1 Avantages de Replit . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

10.3.2 Étapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
10.3.3 Workaround gratuit : UptimeRobot . . . . . . . . . . . . . . . . . . 33
10.4 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10.4.1 UptimeRobot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10.4.2 Logs en production . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

11 Tests et validation 35
11.1 Plan de tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11.1.1 Tests unitaires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11.1.2 Tests d’intégration . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
11.1.3 Tests de charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
11.2 Critères d’acceptation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
11.3 Commande de test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

12 Coûts et ressources 38
12.1 Estimation des coûts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
12.1.1 Scénario 1 : 1000 mots/mois . . . . . . . . . . . . . . . . . . . . . . 38
12.1.2 Scénario 2 : 10000 mots/mois . . . . . . . . . . . . . . . . . . . . . 38
12.2 Optimisations de coûts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
12.2.1 Cache des réponses . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
12.2.2 Modèles moins chers . . . . . . . . . . . . . . . . . . . . . . . . . . 39
12.2.3 Limitation utilisateur . . . . . . . . . . . . . . . . . . . . . . . . . . 39
12.3 Ressources humaines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

13 Évolutions futures 40
13.1 Court terme (1–3 mois) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
13.1.1 Commandes Telegram . . . . . . . . . . . . . . . . . . . . . . . . . 40
13.1.2 Enrichissement des données . . . . . . . . . . . . . . . . . . . . . . 40
13.1.3 Fonctionnalités d’export . . . . . . . . . . . . . . . . . . . . . . . . 40
13.2 Moyen terme (3–6 mois) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
13.2.1 Gamification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
13.2.2 Intelligence contextuelle . . . . . . . . . . . . . . . . . . . . . . . . 41
13.2.3 Multi-plateforme . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
13.3 Long terme (6–12 mois) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
13.3.1 Machine Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
13.3.2 Fonctionnalités audio . . . . . . . . . . . . . . . . . . . . . . . . . . 42
13.3.3 Aspects communautaires . . . . . . . . . . . . . . . . . . . . . . . . 42

14 Annexes 43
14.1 Glossaire technique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
14.2 Liens et ressources utiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
14.2.1 Documentation officielle . . . . . . . . . . . . . . . . . . . . . . . . 43
14.2.2 Tutoriels et guides . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
14.2.3 Communautés . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
14.3 Checklist de déploiement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
14.4 FAQ - Questions fréquentes . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Bot Telegram - Rapport Technique

TABLE DES MATIÈRES 4

14.4.1 Questions techniques . . . . . . . . . . . . . . . . . . . . . . . . . . 44

14.4.2 Questions de déploiement . . . . . . . . . . . . . . . . . . . . . . . 45

Conclusion 46

Bot Telegram - Rapport Technique

Table des figures

1.1 Architecture simplifiée du bot Telegram . . . . . . . . . . . . . . . . . . . . 7

3.1 Architecture détaillée du système . . . . . . . . . . . . . . . . . . . . . . . 11

3.2 Diagramme de séquence UML . . . . . . . . . . . . . . . . . . . . . . . . . 12

6.1 Phase 1 - Réception du message . . . . . . . . . . . . . . . . . . . . . . . . 17

6.2 Phase 2 - Validation du mot . . . . . . . . . . . . . . . . . . . . . . . . . . 18

13.1 Système de gamification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

5
Liste des tableaux

1.1 Caractéristiques de la solution Python . . . . . . . . . . . . . . . . . . . . 8

2.1 Matrice des objectifs fonctionnels . . . . . . . . . . . . . . . . . . . . . . . 9

2.2 Exigences non fonctionnelles . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.1 Matrice des choix technologiques . . . . . . . . . . . . . . . . . . . . . . . 12

4.1 Préconditions et postconditions . . . . . . . . . . . . . . . . . . . . . . . . 13

5.1 Dépendances Python du projet . . . . . . . . . . . . . . . . . . . . . . . . 16

6.1 Matrice des flux d’erreur . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

8.1 Matrice complète de gestion des erreurs . . . . . . . . . . . . . . . . . . . . 26

8.2 Niveaux de logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

9.1 Analyse des menaces de sécurité . . . . . . . . . . . . . . . . . . . . . . . . 29

10.1 Comparaison des services d’hébergement gratuit . . . . . . . . . . . . . . . 32

11.1 Tests d’intégration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

11.2 Critères d’acceptation du projet . . . . . . . . . . . . . . . . . . . . . . . . 37

12.1 Coûts mensuels pour 1000 mots . . . . . . . . . . . . . . . . . . . . . . . . 38

12.2 Coûts mensuels pour 10000 mots . . . . . . . . . . . . . . . . . . . . . . . 38
12.3 Comparaison des coûts des modèles IA . . . . . . . . . . . . . . . . . . . . 39
12.4 Estimation des ressources humaines . . . . . . . . . . . . . . . . . . . . . . 39

13.1 Nouvelles commandes Telegram . . . . . . . . . . . . . . . . . . . . . . . . 40

13.2 Extensions multi-plateformes . . . . . . . . . . . . . . . . . . . . . . . . . . 41

14.1 Checklist avant déploiement en production . . . . . . . . . . . . . . . . . . 44

14.2 Objectifs de performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6
Chapitre 1

Vue d’ensemble du projet

1.1 Résumé exécutif

Le projet consiste à développer un bot Telegram éducatif en Python qui permet aux
utilisateurs d’apprendre le vocabulaire français de manière interactive. Le bot reçoit un
mot en français, génère automatiquement une explication, un exemple d’utilisation, et des
traductions en anglais et arabe, puis stocke ces informations dans une base de données
Notion pour consultation ultérieure.

1.1.1 Architecture en un coup d’œil

Utilisateur

Mot français

Telegram API

Message

Processor
4 éléments Stockage
Validation

Réponse Generator IA Notion API

Figure 1.1 – Architecture simplifiée du bot Telegram

1.2 Problématique
L’utilisateur disposait d’un système fonctionnel développé avec n8n (plateforme no-
code), mais rencontrait les limitations suivantes :
— Coût récurrent : n8n nécessite un abonnement payant pour un usage continu

7
CHAPITRE 1. VUE D’ENSEMBLE DU PROJET 8

— Dépendance technologique : limitations imposées par les capacités de la plateforme

— Manque de flexibilité : difficultés pour personnaliser ou étendre les fonctionnalités
— Compétences limitées : absence de maîtrise technique approfondie du système

1.3 Solution proposée

Migration complète vers une solution Python professionnelle :

primarycolor !20 As- Caractéristique

pect
Architecture Modulaire, séparation des responsabilités (SRP)
Indépendance Contrôle total du code source
Déploiement Services cloud gratuits (Railway, Replit)
Évolutivité Facilité d’ajout de nouvelles fonctionnalités
Maintenance Code documenté et tests automatisés

Table 1.1 – Caractéristiques de la solution Python

Bot Telegram - Rapport Technique

Chapitre 2

Contexte et objectifs

2.1 Objectifs fonctionnels

primarycolor !20 Ob- Description Priorité

jectif
Réception de mots Recevoir des mots français via Tele- Critique
gram
Génération de contenu Produire explication, exemple, traduc- Critique
tions
Réponse utilisateur Envoyer les informations formatées Critique
Stockage Notion Persister les données dans Notion Haute
Validation Vérifier la validité des mots reçus Moyenne

Table 2.1 – Matrice des objectifs fonctionnels

2.2 Objectifs pédagogiques

Ce projet vise à développer les compétences suivantes :
1. Comprendre l’architecture d’un système distribué
2. Maîtriser les interactions avec des APIs externes
— Telegram Bot API
— APIs d’intelligence artificielle (OpenAI, Claude)
— Notion API
3. Apprendre les bonnes pratiques de développement Python
4. Acquérir une autonomie pour développer d’autres bots similaires

2.3 Objectifs techniques

2.3.1 Principes architecturaux
Stateless Le bot ne conserve pas d’état persistant entre les requêtes

9
CHAPITRE 2. CONTEXTE ET OBJECTIFS 10

Modulaire Séparation claire des responsabilités (SOLID principles)

Robuste Gestion complète des erreurs et cas limites
Économique Déploiement gratuit ou à coût minimal

2.3.2 Exigences non fonctionnelles

primarycolor !20 Exigence Spécification Priorité

Temps de réponse < 5 secondes en moyenne Haute
Disponibilité > 99% (tolérance aux pannes Notion) Moyenne
Scalabilité Support de 100 requêtes/heure minimum Moyenne
Sécurité Tokens chiffrés, validation des inputs Critique
Maintenabilité Code commenté, architecture modulaire Haute

Table 2.2 – Exigences non fonctionnelles

Bot Telegram - Rapport Technique

Chapitre 3

Architecture technique

3.1 Vue d’ensemble architecturale

Utilisateur
Telegram

Message texte

Telegram Bot API

(telegram_handler.py)

Extraction

Processeur Central
([Link])
Stockage
4Validation
éléments OK

Réponse Générateur IA Notion API

formatée ([Link]) (notion_handler.py)

Figure 3.1 – Architecture détaillée du système

11
CHAPITRE 3. ARCHITECTURE TECHNIQUE 12

3.2 Diagramme de séquence

Utilisateur Telegram Processor Generator Notion

Message

Texte

Validation
Mot

API IA
4 éléments

Réponse

Message

Données

Figure 3.2 – Diagramme de séquence UML

3.3 Choix technologiques

primarycolor !20 Justification Alternatives

Technologie
Python 3.9+ Simplicité, bibliothèques [Link], Go
riches, compatibilité
python-telegram- Abstraction solide de l’API requests (trop bas niveau)
bot Telegram
OpenAI API Qualité des réponses, multi- Claude API, Google Translate
lingue
Notion API Interface agréable, gratuit Airtable, Google Sheets
python-dotenv Gestion sécurisée des secrets Config files, hardcoded

Table 3.1 – Matrice des choix technologiques

Bot Telegram - Rapport Technique

Chapitre 4

Spécifications fonctionnelles

4.1 Cas d’utilisation principal

4.1.1 Scénario nominal
1. L’utilisateur envoie un mot français (ex : “bonjour”)
2. Le bot valide que c’est un mot valide
3. Le bot génère :
— Explication en français
— Exemple dans une phrase
— Traduction en anglais
— Traduction en arabe
4. Le bot envoie les 4 éléments à l’utilisateur
5. Le bot enregistre les données dans Notion

4.1.2 Préconditions et postconditions

primarycolor !20 Préconditions Postconditions

L’utilisateur a démarré le bot L’utilisateur a reçu les informations
Le bot est en ligne et actif Les données sont stockées dans Notion
Les APIs sont disponibles Le message est loggé

Table 4.1 – Préconditions et postconditions

4.2 Cas d’utilisation alternatifs

4.2.1 Mot invalide
Déclencheur L’utilisateur envoie un texte vide, des chiffres, ou des caractères spéciaux
Réponse Message d’erreur poli : “ Mot invalide. Veuillez envoyer un mot en français.”
Action Pas d’appel API, pas de stockage

13
 CHAPITRE 4. SPÉCIFICATIONS FONCTIONNELLES 14

4.2.2 Erreur API IA

Déclencheur L’API IA ne répond pas ou retourne une erreur
Réponse “ Erreur lors de la génération. Réessayez.”
Action Log de l’erreur, pas de stockage Notion

4.2.3 Erreur Notion

Déclencheur L’API Notion est indisponible
Réponse L’utilisateur reçoit quand même sa réponse
Action Log de l’erreur, continuité du service

4.3 Format de données

Le bot génère et stocke des données structurées au format JSON :
1 {
2 " word " : " bonjour " ,
3 " explanation " : " Salutation utilisee pour dire ... " ,
4 " example " : " Bonjour , comment allez - vous ? " ,
5 " translation_en " : " hello " ,
6 " translation_ar " : " ",
7 " timestamp " : " 2026 -02 -10 T14 :30:00 Z " ,
8 " user_id " : 123456789
9 }
Listing 4.1 – Structure de données JSON

Bot Telegram - Rapport Technique

 Chapitre 5

Spécifications techniques

5.1 Structure du projet

1 telegram_bot /
2 bot_main . py # Point d ’ entree (30 lignes )
3 config . py # Configuration (40 lignes )
4 telegram_handler . py # Gestion Telegram (80 lignes )
5 processor . py # Orchestration (100 lignes )
6 generator . py # Generation IA (120 lignes )
7 notion_handler . py # Stockage Notion (90 lignes )
8

9 . env # Variables d ’ environnement

10 . gitignore # Fichiers a ignorer
11 requirements . txt # Dependances Python
12 README . md # Documentation utilisateur
13

14 tests / # Tests unitaires

15 test_processor . py
16 test_generator . py
17 test_notion . py
18

19 docs / # Documentation technique

20 architecture . md
21 deployment . md
Listing 5.1 – Arborescence du projet

15
 CHAPITRE 5. SPÉCIFICATIONS TECHNIQUES 16

5.2 Dépendances Python

primarycolor !20 Package Version Usage

python-telegram-bot 13.15 Communication avec Telegram
openai 0.27.0 Génération de contenu IA
requests 2.31.0 Appels HTTP génériques
python-dotenv 1.0.0 Gestion des variables d’environ-
nement
notion-client 2.2.1 Communication avec Notion

Table 5.1 – Dépendances Python du projet

5.2.1 Fichier [Link]

1 python - telegram - bot ==13.15
2 openai ==0.27.0
3 requests ==2.31.0
4 python - dotenv ==1.0.0
5 notion - client ==2.2.1
Listing 5.2 – [Link]

5.3 Variables d’environnement

1 # Telegram
2 TELEGRAM_BOT_TOKEN =1234567890: AB C de fG HI j kl MN Op q rs tU VW x yz
3

4 # API IA ( OpenAI , Claude , etc .)

5 OPENAI_API_KEY = sk - xxxx xxx xxxx xxxx xxxx xxx xx
6

7 # Notion
8 NOTION_TOKEN = s e c r e t _ x x x x x x x x x x x x x x x x x x x x x x x x
9 NOTION_DATABASE_ID = xx xxxx xxxx xxx xxxx xxxx xxx
10

11 # Configuration optionnelle
12 LOG_LEVEL = INFO
13 MAX_RETRIES =3
14 TIMEOUT_SECONDS =30
Listing 5.3 – Fichier .env

Bot Telegram - Rapport Technique

Chapitre 6

Flux de données

6.1 Flux nominal détaillé

6.1.1 Phase 1 : Réception

Telegram
Message reçu
Extraction données
user_id, chat_id, text
Passage à processor

Figure 6.1 – Phase 1 - Réception du message

17
 CHAPITRE 6. FLUX DE DONNÉES 18

6.1.2 Phase 2 : Validation

Réception mot

Non
Valide ? Message erreur

Oui

Générateur

Figure 6.2 – Phase 2 - Validation du mot

6.1.3 Phase 3 : Génération

La génération se fait via un appel API à un service d’intelligence artificielle :
1. Construction du prompt structuré
2. Appel API avec retry en cas d’échec
3. Parsing de la réponse JSON
4. Validation des 4 éléments
5. Retour des données au processeur

6.1.4 Phase 4 : Réponse utilisateur

1 response = f " " "
2 **{ word }**
3

4 ** Explication :** { data [ ’ explanation ’]}

5

6 ** Exemple :** { data [ ’ example ’]}

7

8 ** Anglais :** { data [ ’ translation_en ’]}

9

10 ** Arabe :** { data [ ’ translation_ar ’]}

11 """
Listing 6.1 – Formatage de la réponse

Bot Telegram - Rapport Technique

 CHAPITRE 6. FLUX DE DONNÉES 19

6.1.5 Phase 5 : Stockage

Le bot construit une requête Notion et insère les données dans la base de données :
1 payload = {
2 " parent " : { " database_id " : NOTION_DATABASE_ID } ,
3 " properties " : {
4 " Mot " : { " title " : [{ " text " : { " content " : word }}]} ,
5 " Explication " : { " rich_text " : [...]} ,
6 " Exemple " : { " rich_text " : [...]} ,
7 " Anglais " : { " rich_text " : [...]} ,
8 " Arabe " : { " rich_text " : [...]}
9 }
10 }
Listing 6.2 – Payload Notion

6.2 Gestion des flux d’erreur

primarycolor !20 Point Impact Action

de défaillance
Message Telegram mal- Faible Validation + message d’erreur
formé
API IA timeout Moyen Retry + message d’erreur
API IA quota dépassé Élevé Log critique + notification admin
Notion indisponible Faible Log + continuer (pas de blocage)
Telegram API down Critique Impossible de répondre (bot inactif)

Table 6.1 – Matrice des flux d’erreur

Bot Telegram - Rapport Technique

 Chapitre 7

Modules et responsabilités

7.1 [Link] - Configuration centralisée

7.1.1 Responsabilité
Centraliser toute la configuration du bot et gérer les variables d’environnement de
manière sécurisée.

7.1.2 Fonctions principales

1 import os
2 from dotenv import load_dotenv
3

4 # Charger les variables d ’ environnement

5 load_dotenv ()
6

7 # Tokens
8 TELEGRAM_BOT_TOKEN = os . getenv ( " TELEGRAM_BOT_TOKEN " )
9 OPENAI_API_KEY = os . getenv ( " OPENAI_API_KEY " )
10 NOTION_TOKEN = os . getenv ( " NOTION_TOKEN " )
11 NOTION_DATABASE_ID = os . getenv ( " NOTION_DATABASE_ID " )
12

13 # Validation
14 if not TELEGRAM_BOT_TOKEN :
15 raise ValueError ( " TELEGRAM_BOT_TOKEN manquant " )
Listing 7.1 – Module [Link]

7.1.3 Principe SOLID appliqué

Single Responsibility Principle (SRP) : Ce module a une seule responsabilité -
gérer la configuration.

20
 CHAPITRE 7. MODULES ET RESPONSABILITÉS 21

7.2 telegram_handler.py - Gestion Telegram

7.2.1 Responsabilité
Gérer la communication bidirectionnelle avec l’API Telegram (réception et envoi de
messages).

7.2.2 Architecture du module

1 from telegram import Update , Bot
2 from telegram . ext import Updater , MessageHandler , Filters
3 import config
4

5 def send_message ( chat_id : int , text : str ) :

6 " " " Envoie un message a l ’ utilisateur " " "
7 bot = Bot ( token = config . TELEGRAM_BOT_TOKEN )
8 bot . send_message ( chat_id = chat_id , text = text )
9

10 def handle_message ( update : Update , context ) :

11 " " " Recoit et traite le message " " "
12 from processor import process_word
13

14 user_text = update . message . text

15 chat_id = update . message . chat . id
16

17 process_word ( user_text , chat_id )

18

19 def start_bot () :
20 " " " Demarre le bot en mode polling " " "
21 updater = Updater ( config . TELEGRAM_BOT_TOKEN )
22 dp = updater . dispatcher
23

24 dp . add_handler ( MessageHandler (
25 Filters . text & ~ Filters . command ,
26 handle_message
27 ))
28

29 updater . start_polling ()
30 updater . idle ()
Listing 7.2 – telegram_handler.py (extrait)

7.3 [Link] - Orchestration

7.3.1 Responsabilité
Orchestrer le flux de traitement, valider les entrées et coordonner les autres modules.

Bot Telegram - Rapport Technique

 CHAPITRE 7. MODULES ET RESPONSABILITÉS 22

7.3.2 Logique de validation

1 def is_valid_word ( word : str ) -> bool :
2 " " " Verifie si le mot est valide " " "
3

4 # Longueur
5 if not word or len ( word ) > 50:
6 return False
7

8 # Caracteres autorises seulement

9 if not word . replace ( " " , " " ) . replace ( " -" , " " ) . isalpha () :
10 return False
11

12 # Pas de caracteres dangereux

13 dangerous_chars = [ ’ < ’ , ’ > ’ , ’& ’ , ’; ’ , ’| ’]
14 if any ( c in word for c in dangerous_chars ) :
15 return False
16

17 return True
Listing 7.3 – Validation dans [Link]

7.3.3 Orchestration du flux

1 def process_word ( word : str , chat_id : int ) :
2 " " " Traite le mot : validation -> generation -> stockage " " "
3

4 # 1. Validation
5 if not is_valid_word ( word ) :
6 send_message ( chat_id , " Mot invalide " )
7 return
8

9 # 2. Generation
10 try :
11 data = generate_word_data ( word )
12 except Exception as e :
13 send_message ( chat_id , " Erreur generation " )
14 return
15

16 # 3. Reponse utilisateur
17 response = format_response ( data )
18 send_message ( chat_id , response )
19

20 # 4. Stockage Notion
21 try :
22 save_to_notion ( data )
23 except Exception as e :
24 logging . error ( f " Erreur Notion : { e } " )

Bot Telegram - Rapport Technique

 CHAPITRE 7. MODULES ET RESPONSABILITÉS 23

Listing 7.4 – Fonction process_word

7.4 [Link] - Génération IA

7.4.1 Responsabilité
Générer les 4 éléments linguistiques via une API d’intelligence artificielle.

7.4.2 Construction du prompt

1 def build_prompt ( word : str ) -> str :
2 " " " Construit le prompt pour l ’ API IA " " "
3 return f " " "
4 Tu es un assistant linguistique . Pour le mot francais " { word } " ,
5 fournis :
6 1. Une explication claire en francais
7 2. Un exemple de phrase en francais
8 3. La traduction en anglais
9 4. La traduction en arabe
10

11 Format de reponse ( JSON ) :

12 {{
13 " word " : " { word } " ,
14 " explanation " : " ... " ,
15 " example " : " ... " ,
16 " translation_en " : " ... " ,
17 " translation_ar " : " ... "
18 }}
19 """
Listing 7.5 – Prompt pour l’API IA

7.4.3 Appel API avec gestion d’erreurs

1 import openai
2 import json
3

4 def generate_word_data ( word : str ) -> dict :

5 " " " Genere les 4 elements via API IA " " "
6

7 prompt = build_prompt ( word )

8

9 response = openai . ChatCompletion . create (

10 model = " gpt -3.5 - turbo " ,
11 messages =[{ " role " : " user " , " content " : prompt }] ,

Bot Telegram - Rapport Technique

 CHAPITRE 7. MODULES ET RESPONSABILITÉS 24

12 temperature =0.7
13 )
14

15 # Parser la reponse JSON

16 result = json . loads (
17 response . choices [0]. message . content
18 )
19

20 return result
Listing 7.6 – Génération avec OpenAI

7.5 notion_handler.py - Stockage Notion

7.5.1 Responsabilité
Persister les données dans une base de données Notion.

7.5.2 Construction du payload

1 import requests
2 import config
3

4 def save_to_notion ( data : dict ) :

5 " " " Enregistre les donnees dans Notion " " "
6

7 url = " https :// api . notion . com / v1 / pages "

8

9 headers = {
10 " Authorization " : f " Bearer { config . NOTION_TOKEN } " ,
11 " Content - Type " : " application / json " ,
12 " Notion - Version " : " 2022 -06 -28 "
13 }
14

15 payload = {
16 " parent " : { " database_id " : config . NOTION_DATABASE_ID } ,
17 " properties " : {
18 " Mot " : {
19 " title " : [{ " text " : { " content " : data [ " word " ]}}]
20 },
21 " Explication " : {
22 " rich_text " : [{ " text " : { " content " : data [ "
explanation " ]}}]
23 },
24 " Exemple " : {
25 " rich_text " : [{ " text " : { " content " : data [ " example "
]}}]
26 },

Bot Telegram - Rapport Technique

 CHAPITRE 7. MODULES ET RESPONSABILITÉS 25

27 " Anglais " : {

28 " rich_text " : [{ " text " : { " content " : data [ "
translation_en " ]}}]
29 },
30 " Arabe " : {
31 " rich_text " : [{ " text " : { " content " : data [ "
translation_ar " ]}}]
32 }
33 }
34 }
35

36 response = requests . post ( url , json = payload , headers = headers )

37

38 if response . status_code != 200:

39 raise Exception ( f " Erreur Notion : { response . text } " )
Listing 7.7 – Stockage dans Notion

Bot Telegram - Rapport Technique

 Chapitre 8

Gestion des erreurs

8.1 Stratégie globale

PRINCIPE : FAIL GRACEFULLY
Le bot continue de fonctionner même si un module échoue,
en informant l’utilisateur de manière appropriée.

8.2 Matrice des erreurs

primarycolor !20 Impact Réaction Priorité

Erreur
Mot invalide Faible Message poli Basse
API IA timeout Moyen Message d’erreur + re- Haute
try
API IA quota dé- Élevé Message + log critique Critique
passé
Notion indisponible Faible Log + continuer Moyenne
Telegram API Critique Impossible de ré- Critique
down pondre
Token invalide Critique Arrêt du bot Critique

Table 8.1 – Matrice complète de gestion des erreurs

8.3 Système de logging

8.3.1 Configuration des logs
1 import logging
2

3 logging . basicConfig (
4 level = logging . INFO ,

26
 CHAPITRE 8. GESTION DES ERREURS 27

5 format = ’ %( asctime ) s - %( name ) s - %( levelname ) s - %( message ) s ’ ,

6 handlers =[
7 logging . FileHandler ( ’ bot . log ’) ,
8 logging . StreamHandler ()
9 ]
10 )
11

12 # Exemples d ’ utilisation
13 logging . info ( " Bot demarre " )
14 logging . warning ( " Notion indisponible , retry ... " )
15 logging . error ( " Erreur API IA " , exc_info = True )
16 logging . critical ( " Token Telegram invalide " )
Listing 8.1 – Configuration du logging

8.3.2 Niveaux de log

primarycolor !20 Niveau Usage

DEBUG Informations détaillées pour le débogage
INFO Événements normaux (démarrage, réception message)
WARNING Événements inhabituels mais gérés (retry, API lente)
ERROR Erreurs mais le bot continue (Notion indisponible)
CRITICAL Erreurs fatales (token invalide, impossible de démarrer)

Table 8.2 – Niveaux de logging

8.4 Mécanisme de retry

1 import time
2 import logging
3

4 def retry_on_failure ( func , max_retries =3 , delay =2) :

5 " " " Retry une fonction en cas d ’ echec " " "
6 for attempt in range ( max_retries ) :
7 try :
8 return func ()
9 except Exception as e :
10 if attempt == max_retries - 1:
11 raise
12

13 wait_time = delay * (2 ** attempt )

14 logging . warning (
15 f " Tentative { attempt +1} echouee , "
16 f " retry dans { wait_time } s ... "
17 )
18 time . sleep ( wait_time )

Bot Telegram - Rapport Technique

CHAPITRE 8. GESTION DES ERREURS 28

Listing 8.2 – Retry avec backoff exponentiel

Bot Telegram - Rapport Technique

 Chapitre 9

Sécurité

9.1 Menaces identifiées

primarycolor !20 Probabilité Impact Mitigation

Menace
Exposition des to- Moyenne Critique Variables d’environnement,
kens .gitignore
Injection de com- Faible Moyen Validation stricte des inputs
mandes
Abus API (spam) Moyenne Moyen Rate limiting, whitelist
Man-in-the-middle Faible Élevé HTTPS obligatoire, certifi-
cats

Table 9.1 – Analyse des menaces de sécurité

9.2 Bonnes pratiques implémentées

9.2.1 Gestion sécurisée des secrets
1 # MAUVAIS
2 TELEGRAM_TOKEN = " 123456: ABC ... "
3

4 # BON
5 import os
6 TELEGRAM_TOKEN = os . getenv ( " TELEGRAM_BOT_TOKEN " )
7 if not TELEGRAM_TOKEN :
8 raise ValueError ( " Token manquant " )
Listing 9.1 – Bonne pratique - Secrets

9.2.2 Validation rigoureuse des inputs

29
 CHAPITRE 9. SÉCURITÉ 30

1 def is_valid_word ( word : str ) -> bool :

2 " " " Verifie si le mot est valide et sur " " "
3

4 # Longueur
5 if not word or len ( word ) > 50:
6 return False
7

8 # Caracteres autorises seulement

9 if not word . replace ( " " , " " ) . replace ( " -" , " " ) . isalpha () :
10 return False
11

12 # Pas de caracteres dangereux

13 dangerous_chars = [ ’ < ’ , ’ > ’ , ’& ’ , ’; ’ , ’| ’ , ’{ ’ , ’} ’]
14 if any ( c in word for c in dangerous_chars ) :
15 return False
16

17 return True
Listing 9.2 – Validation sécurisée

9.2.3 Rate limiting

1 from collections import defaultdict
2 import time
3

4 user_requests = defaultdict ( list )

5 MAX_REQUESTS_ PER_MINUTE = 10
6

7 def is_rate_limited ( user_id : int ) -> bool :

8 " " " Verifie si l ’ utilisateur a depasse la limite " " "
9 now = time . time ()
10

11 # Nettoyer les anciennes requetes

12 user_requests [ user_id ] = [
13 req_time for req_time in user_requests [ user_id ]
14 if now - req_time < 60
15 ]
16

17 if len ( user_requests [ user_id ]) >= MA X_REQUESTS _PER_MINUTE :

18 return True
19

20 user_requests [ user_id ]. append ( now )

21 return False
Listing 9.3 – Limitation du taux de requêtes

Bot Telegram - Rapport Technique

 CHAPITRE 9. SÉCURITÉ 31

9.3 Fichier .gitignore

1 # Variables d ’ environnement
2 . env
3 . env . local
4 . env . production
5

6 # Logs
7 *. log
8 logs /
9

10 # Python
11 __pycache__ /
12 *. pyc
13 *. pyo
14 . pytest_cache /
15 venv /
16 env /
17

18 # IDE
19 . vscode /
20 . idea /
21 *. swp
22

23 # Secrets
24 secrets /
25 credentials /
26 *. key
27 *. pem
Listing 9.4 – .gitignore pour la sécurité

Bot Telegram - Rapport Technique

Chapitre 10

Déploiement

10.1 Options d’hébergement gratuit

primarycolor !20 Avantages Inconvénients Note

Service
Replit Très simple, IDE intégré Peut s’endormir après in-
activité
Railway 500h/mois gratuit, pas Complexe pour débu-
de sleep tants
PythonAnywhereSpécialisé Python Interface moins moderne
Heroku Robuste Gratuit très limité
Render Moderne, facile Sleep après 15min

Table 10.1 – Comparaison des services d’hébergement gratuit

10.2 Déploiement sur Railway (recommandé)

10.2.1 Étapes de déploiement
1. Créer un compte sur [Link]
2. Nouveau projet → Deploy from GitHub
3. Connecter le dépôt Git du projet
4. Configurer les variables d’environnement :
— TELEGRAM_BOT_TOKEN
— OPENAI_API_KEY
— NOTION_TOKEN
— NOTION_DATABASE_ID
5. Railway détecte automatiquement bot_main.py
6. Cliquer sur “Deploy”
7. Le bot est en ligne 24/7

32
 CHAPITRE 10. DÉPLOIEMENT 33

10.2.2 Fichier Procfile (optionnel)

1 worker : python bot_main . py
Listing 10.1 – Procfile pour Railway

10.3 Déploiement sur Replit

10.3.1 Avantages de Replit
— Interface très simple
— IDE intégré dans le navigateur
— Aucune configuration complexe
— Idéal pour l’apprentissage

10.3.2 Étapes
1. Créer un nouveau Repl Python
2. Copier tous les fichiers du projet
3. Onglet “Secrets” → ajouter les variables d’environnement
4. Cliquer sur “Run”
5. (Optionnel) Activer “Always On” (version payante)

10.3.3 Workaround gratuit : UptimeRobot

Pour éviter que Replit s’endorme :
1. Ajouter un endpoint de health check dans le bot
2. Utiliser [Link] (gratuit)
3. Configurer un ping toutes les 5 minutes

1 from flask import Flask

2 import threading
3

4 app = Flask ( __name__ )

5

6 @app . route ( ’/ health ’)

7 def health () :
8 return { " status " : " ok " , " bot " : " running " }
9

10 def run_flask () :
11 app . run ( host = ’ [Link] ’ , port =8080)
12

13 # Dans bot_main . py
14 threading . Thread ( target = run_flask ) . start ()

Bot Telegram - Rapport Technique

 CHAPITRE 10. DÉPLOIEMENT 34

15 start_bot ()
Listing 10.2 – Health check endpoint

10.4 Monitoring
10.4.1 UptimeRobot
— Ping l’endpoint /health toutes les 5 minutes
— Alertes par email si le bot est down
— Statistiques de disponibilité
— 100% gratuit pour usage basique

10.4.2 Logs en production

1 import logging
2 import sys
3

4 # Logs vers stdout pour Railway / Heroku

5 logging . basicConfig (
6 level = logging . INFO ,
7 format = ’ %( asctime ) s - %( name ) s - %( levelname ) s - %( message ) s ’ ,
8 handlers =[
9 logging . StreamHandler ( sys . stdout )
10 ]
11 )
Listing 10.3 – Configuration des logs en production

Bot Telegram - Rapport Technique

 Chapitre 11

Tests et validation

11.1 Plan de tests

11.1.1 Tests unitaires
1 import pytest
2 from processor import is_valid_word
3

4 def test_valid_words () :
5 assert is_valid_word ( " bonjour " ) == True
6 assert is_valid_word ( " apres - midi " ) == True
7 assert is_valid_word ( " rendez - vous " ) == True
8

9 def test_invalid_words () :
10 assert is_valid_word ( " " ) == False
11 assert is_valid_word ( " 123 " ) == False
12 assert is_valid_word ( " abc123 " ) == False
13 assert is_valid_word ( " a " * 100) == False
14 assert is_valid_word ( " < script > " ) == False
15

16 def test_edge_cases () :
17 assert is_valid_word ( " " ) == False
18 assert is_valid_word ( " a " ) == True
19 assert is_valid_word ( " bon - jour " ) == True
Listing 11.1 – test_processor.py

1 import pytest
2 from generator import generate_word_data
3

4 def test_gener ate_word_da ta ( mocker ) :

5 # Mock de l ’ API OpenAI
6 mock_response = {
7 " word " : " test " ,
8 " explanation " : " Verification de fonctionnement " ,
9 " example " : " Ceci est un test . " ,

35
 CHAPITRE 11. TESTS ET VALIDATION 36

10 " translation_en " : " test " ,

11 " translation_ar " : " "
12 }
13

14 mocker . patch (
15 ’ generator . openai . ChatCompletion . create ’ ,
16 return_value = mock_response
17 )
18

19 result = generate_word_data ( " test " )

20

21 assert " explanation " in result

22 assert " translation_ar " in result
23 assert result [ " word " ] == " test "
Listing 11.2 – test_generator.py

11.1.2 Tests d’intégration

primarycolor !20 Test Description

Test Telegram Envoyer un message réel et vérifier la réponse
Test IA Vérifier que l’API répond avec les 4 éléments
Test Notion Vérifier l’insertion dans la base de données
Test End-to-End Flux complet de bout en bout

Table 11.1 – Tests d’intégration

11.1.3 Tests de charge

1 import concurrent . futures
2 import time
3

4 def send_test_message () :
5 " " " Simuler l ’ envoi d ’ un message " " "
6 process_word ( " test " , chat_id =123)
7

8 # Test : 100 requetes en parallele

9 with concurrent . futures . ThreadPoolExecutor ( max_workers =10) as
executor :
10 futures = [
11 executor . submit ( send_test_message )
12 for _ in range (100)
13 ]
14 concurrent . futures . wait ( futures )
15

16 print ( " Test de charge termine " )

Listing 11.3 – Test de charge simple

Bot Telegram - Rapport Technique

 CHAPITRE 11. TESTS ET VALIDATION 37

11.2 Critères d’acceptation

primarycolor !20 Cri- Objectif Validation

tère
Taux de succès > 95% Logs sur 1000 messages
Temps de réponse < 5s moyenne Monitoring temps réel
Disponibilité > 99% Uptime monitoring 30 jours
Erreur Notion < 5% Logs d’erreur

Table 11.2 – Critères d’acceptation du projet

11.3 Commande de test

1 # Installer pytest
2 pip install pytest pytest - mock
3

4 # Executer tous les tests

5 pytest tests /
6

7 # Executer avec couverture de code

8 pytest -- cov =. tests /
9

10 # Executer un test specifique

11 pytest tests / test_processor . py :: test_valid_words
Listing 11.4 – Exécution des tests

Bot Telegram - Rapport Technique

 Chapitre 12

Coûts et ressources

12.1 Estimation des coûts

12.1.1 Scénario 1 : 1000 mots/mois

primarycolor !20 Service Coût mensuel Notes

Telegram API 0€ Gratuit illimité
OpenAI API 5–10 € 1000 requêtes × 0.005 €
Claude API 3–7 € Alternative similaire
Notion API 0€ Gratuit jusqu’à 1000 blocs
Hébergement Railway 0€ 500h/mois gratuit
primarycolor !10 TOTAL 5–10 € Principalement API IA

Table 12.1 – Coûts mensuels pour 1000 mots

12.1.2 Scénario 2 : 10000 mots/mois

primarycolor !20 Service Coût mensuel

OpenAI API 50–100 €
Notion API 0–8 € (si > 1000 blocs)
Hébergement 0–5 €
primarycolor !10 TOTAL 50–105 €

Table 12.2 – Coûts mensuels pour 10000 mots

12.2 Optimisations de coûts

12.2.1 Cache des réponses
1 # Cache simple en memoire
2 cache = {}
3

38
 CHAPITRE 12. COÛTS ET RESSOURCES 39

4 def generat e_ wo rd_ da ta _ca ch ed ( word : str ) :

5 " " " Genere avec cache pour eviter les appels API " " "
6

7 if word in cache :
8 logging . info ( f " Cache hit pour : { word } " )
9 return cache [ word ]
10

11 logging . info ( f " Cache miss pour : { word } " )

12 data = generate_word_data ( word )
13 cache [ word ] = data
14

15 return data
Listing 12.1 – Système de cache

12.2.2 Modèles moins chers

primarycolor !20 Modèle Coût/1000 tokens Qualité

GPT-4 0.03 €
GPT-3.5-turbo 0.002 €
Claude Sonnet 0.003 €
Claude Haiku 0.00025 €

Table 12.3 – Comparaison des coûts des modèles IA

12.2.3 Limitation utilisateur

— Version gratuite : 10 mots/jour
— Version premium : 100 mots/jour pour 2 €/mois
— Version illimitée : pour 5 €/mois

12.3 Ressources humaines

primarycolor !20 Phase Durée Compétences

Développement initial 2–3 jours Python intermédiaire
Tests 1 jour Python, debugging
Déploiement 0.5 jour DevOps basique
Maintenance 2h/mois Support, monitoring

Table 12.4 – Estimation des ressources humaines

Bot Telegram - Rapport Technique

Chapitre 13

Évolutions futures

13.1 Court terme (1–3 mois)

13.1.1 Commandes Telegram

primarycolor !20 Commande Fonctionnalité

/start Message de bienvenue et instructions
/stats Statistiques personnelles (mots appris, progres-
sion)
/history Affichage des 10 derniers mots consultés
/random Mot aléatoire du jour pour révision
/help Aide et documentation

Table 13.1 – Nouvelles commandes Telegram

13.1.2 Enrichissement des données

— Prononciation phonétique (API IPA)
— Synonymes et antonymes
— Niveau de difficulté (A1, A2, B1, B2, C1, C2)
— Catégorie grammaticale (nom, verbe, adjectif)
— Genre et nombre (masculin/féminin, singulier/pluriel)

13.1.3 Fonctionnalités d’export

— Export PDF des 100 derniers mots
— Génération de flashcards Anki
— Export CSV pour Excel/Google Sheets
— Partage de listes entre utilisateurs

40
CHAPITRE 13. ÉVOLUTIONS FUTURES 41

13.2 Moyen terme (3–6 mois)

13.2.1 Gamification

Système de points

Badges d’achievement

Classement utilisateurs

Séries quotidiennes

Figure 13.1 – Système de gamification

13.2.2 Intelligence contextuelle

— Détection automatique de la langue source
— Suggestions de mots similaires ou apparentés
— Quiz interactifs personnalisés
— Recommandations basées sur l’historique

13.2.3 Multi-plateforme

primarycolor !20 Plateforme Fonctionnalité

Discord Bot Discord avec mêmes fonctionnalités
Slack Intégration pour équipes d’apprentissage
WhatsApp Via Twilio API
Application web Interface web responsive

Table 13.2 – Extensions multi-plateformes

13.3 Long terme (6–12 mois)

13.3.1 Machine Learning
1. Recommandations personnalisées
— Analyse du niveau de l’utilisateur

Bot Telegram - Rapport Technique

CHAPITRE 13. ÉVOLUTIONS FUTURES 42

— Suggestions de mots adaptés

— Progression optimisée
2. Prédiction de difficulté
— Identification des mots difficiles pour chaque utilisateur
— Adaptation du rythme d’apprentissage
3. Spaced Repetition
— Algorithme de révision espacée
— Rappels automatiques au moment optimal
— Maximisation de la rétention

13.3.2 Fonctionnalités audio

— Text-to-Speech pour la prononciation
— Speech-to-Text pour l’entraînement oral
— Évaluation de la prononciation
— Exercices de compréhension orale

13.3.3 Aspects communautaires

— Partage de listes personnalisées
— Forums de discussion par niveau
— Groupes d’étude collaboratifs
— Défis communautaires hebdomadaires

Bot Telegram - Rapport Technique

Chapitre 14

Annexes

14.1 Glossaire technique

API Application Programming Interface - Interface de programmation permettant la
communication entre applications
Stateless Architecture sans état - Le système ne conserve pas de mémoire entre les
requêtes
Polling Interrogation régulière - Le client demande périodiquement au serveur s’il y a
des nouveautés
Webhook Notification push - Le serveur envoie directement les données au client lors
d’un événement
Token Clé d’accès sécurisée permettant l’authentification auprès d’une API
Retry Mécanisme de réessai automatique en cas d’échec d’une opération
Rate limiting Limitation du nombre de requêtes autorisées par unité de temps
Backoff exponentiel Stratégie d’attente progressive entre les tentatives (2s, 4s, 8s, etc.)
JSON JavaScript Object Notation - Format de données structurées textuelles
SOLID Ensemble de 5 principes de conception orientée objet

14.2 Liens et ressources utiles

14.2.1 Documentation officielle
— Telegram Bot API : [Link]
— python-telegram-bot : [Link]
— OpenAI API : [Link]
— Anthropic API : [Link]
— Notion API : [Link]
— Python dotenv : [Link]

43
CHAPITRE 14. ANNEXES 44

14.2.2 Tutoriels et guides

— Créer un bot Telegram : [Link]
— Notion API quickstart : [Link]
— Railway deployment : [Link]

14.2.3 Communautés
— r/TelegramBots (Reddit)
— Stack Overflow (tag : python-telegram-bot)
— Discord - Python Programming
— GitHub Discussions

14.3 Checklist de déploiement

primarycolor !20 Tâche

Code testé localement
Tests unitaires passent (> 80% couverture)
Variables d’environnement configurées
.gitignore configuré (pas de secrets dans Git)
Documentation à jour ([Link])
Système de logs configuré
Monitoring activé (UptimeRobot)
Health check endpoint fonctionnel
Plan de backup (export Notion régulier)
Contact support défini
Gestion des erreurs testée
Rate limiting implémenté

Table 14.1 – Checklist avant déploiement en production

14.4 FAQ - Questions fréquentes

14.4.1 Questions techniques
Q : Pourquoi Python et pas JavaScript/[Link] ?
R : Python est plus simple pour les débutants, avec des bibliothèques très matures
pour l’IA et une syntaxe claire. [Link] est excellent mais plus verbeux pour ce type de
projet.

Q : Peut-on utiliser d’autres APIs IA que OpenAI ?

R : Oui, absolument. Claude API (Anthropic), Google Gemini, ou même des modèles
locaux comme Ollama sont compatibles avec l’architecture modulaire du bot.

Bot Telegram - Rapport Technique

CHAPITRE 14. ANNEXES 45

Q : Combien coûte réellement le bot par mois ?

R : Environ 5–10 €/mois pour 1000 mots (principalement l’API IA). L’hébergement
peut être totalement gratuit sur Railway ou Replit.

Q : Le bot peut-il gérer plusieurs utilisateurs simultanément ?

R : Oui, python-telegram-bot gère automatiquement le multi-threading et peut servir
des centaines d’utilisateurs en parallèle.

Q : Comment sauvegarder les données Notion ?

R : Export CSV régulier via l’interface Notion, ou script Python d’export automatique
toutes les semaines.

14.4.2 Questions de déploiement

Q : Quelle plateforme choisir pour débuter ?
R : Replit pour la simplicité absolue, Railway pour une solution plus professionnelle
et stable.

Q : Que faire si le bot s’arrête sur Replit ?

R : Utiliser UptimeRobot pour pinger le bot toutes les 5 minutes, ou passer à Railway
qui ne s’endort pas.

Q : Comment mettre à jour le bot en production ?

R : Sur Railway : git push suffit (déploiement automatique). Sur Replit : modifier les
fichiers directement dans l’IDE.

Bot Telegram - Rapport Technique

Conclusion

Résumé du projet
Ce rapport a présenté en détail l’architecture, le développement et le déploiement
d’un bot Telegram éducatif pour l’apprentissage du vocabulaire français. Le projet dé-
montre une migration réussie d’une solution no-code (n8n) vers une architecture Python
professionnelle, modulaire et évolutive.

Points clés
— Architecture modulaire : 6 modules Python distincts et testables
— Coût maîtrisé : 5–10 €/mois pour usage modéré
— Déploiement gratuit : Railway, Replit, ou PythonAnywhere
— Scalabilité : Support de centaines d’utilisateurs simultanés
— Maintenabilité : Code clair, commenté, documenté
— Sécurité : Tokens en variables d’environnement, validation des inputs
— Robustesse : Gestion des erreurs, logging, retry mechanism

Métriques de succès

primarycolor !20 Indicateur Objectif

Taux de succès > 95%
Temps de réponse moyen < 5 secondes
Disponibilité > 99%
Satisfaction utilisateur > 4/5

Table 14.2 – Objectifs de performance

Prochaines étapes immédiates

1. Développer les 6 modules Python selon l’architecture définie
2. Tester localement avec des données réelles

46
CHAPITRE 14. ANNEXES 47

3. Configurer les APIs (Telegram, OpenAI, Notion)

4. Déployer sur Railway ou Replit
5. Monitorer pendant 1 semaine
6. Itérer selon les retours utilisateurs

Vision à long terme

Ce projet constitue une base solide pour développer un écosystème complet d’appren-
tissage linguistique :
— Extension à d’autres langues (espagnol, allemand, etc.)
— Intégration de fonctionnalités avancées (audio, ML, gamification)
— Création d’une communauté d’apprenants
— Monétisation via un modèle freemium

Document vivant
Ce rapport sera mis à jour au fur et à mesure de l’évolution du projet.
Version actuelle : 1.0 - 10 février 2026

Bot Telegram - Rapport Technique