couple-repo/Projects/CONCEPT/wechat_homework_bot.md
2025-12-04 20:14:23 +08:00

29 KiB
Raw Blame History

WeChat Homework Bot - Auto-Correction System

Status: CONCEPT Created: 2025-11-29 Use Case: Bot WeChat pour récolter automatiquement les devoirs (mp3/mp4/audio) et les corriger automatiquement Target: Cours particuliers d'Alexis (2 classes, usage non-officiel)


📋 Table des matières

  1. Vue d'ensemble
  2. Faisabilité technique
  3. Architecture système
  4. Stack technique
  5. Workflow détaillé
  6. Risques et mitigations
  7. Plan d'implémentation
  8. Coûts
  9. Alternatives
  10. Ressources

🎯 Vue d'ensemble

Problème

  • Étudiants envoient devoirs audio/vidéo (mp3, mp4, messages vocaux WeChat)
  • Collecte manuelle chronophage
  • Correction manuelle répétitive
  • Pas de tracking automatique qui a rendu/pas rendu

Solution proposée

Bot WeChat automatisé qui :

  1. Écoute messages entrants (audio/vidéo)
  2. Télécharge fichiers média automatiquement
  3. Transcrit audio → texte (Speech-to-Text)
  4. Corrige selon critères définis (GPT-4 ou règles custom)
  5. Renvoie feedback automatique à l'étudiant
  6. Track statistiques (taux de rendu, progression, etc.)

Bénéfices

  • ⏱️ Gain de temps : ~70-80% du temps de correction
  • 📊 Tracking automatique
  • Feedback instantané aux étudiants
  • 🔄 Process reproductible et scalable

Faisabilité technique

Verdict : 100% FAISABLE

Capacités Wechaty confirmées

Wechaty (framework open-source bot WeChat) supporte :

  • Audio : mp3, messages vocaux WeChat (.silk)
  • Video : mp4, fichiers vidéo WeChat
  • Images : jpg, png
  • ⚠️ Autres attachments : .zip, .docx (bug connu - 0 bytes)

Source : Wechaty Media File Bot Documentation

Pattern de base

import { WechatyBuilder } from 'wechaty'

const bot = WechatyBuilder.build()

bot.on('message', async (message) => {
  const type = message.type()
  const contact = message.talker()

  // Détection média
  if (type === bot.Message.Type.Audio ||
      type === bot.Message.Type.Video) {

    console.log(`📥 Média reçu de ${contact.name()}`)

    // Téléchargement
    const fileBox = await message.toFileBox()
    const filename = `${Date.now()}_${contact.id()}_${fileBox.name}`
    await fileBox.toFile(`./uploads/${filename}`)

    // Traitement (STT + Correction)
    await processHomework(filename, contact)
  }
})

bot.start()

🏗️ Architecture système

┌─────────────────────────────────────────────────────────────┐
│                    ÉTUDIANT (WeChat)                        │
│              Envoie mp3/mp4/message vocal                   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  BOT WECHAT (Wechaty)                       │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  1. Écoute messages (event listener)                 │   │
│  │  2. Détecte type (Audio/Video)                       │   │
│  │  3. Télécharge fichier (message.toFileBox())         │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│               STOCKAGE LOCAL (./uploads/)                   │
│     Format: timestamp_userId_filename.mp3/mp4               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│          TRANSCRIPTION (Speech-to-Text)                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Option 1: OpenAI Whisper API (multi-langue)        │   │
│  │  Option 2: Baidu STT (optimisé Chine)               │   │
│  │  Option 3: Tencent Cloud ASR (local Chine)          │   │
│  └──────────────────────────────────────────────────────┘   │
│              Output: Texte transcrit                        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              CORRECTION AUTOMATIQUE                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  GPT-4 API avec prompt de correction                │   │
│  │  - Grammaire                                         │   │
│  │  - Prononciation (via transcription)                │   │
│  │  - Vocabulaire                                       │   │
│  │  - Score /10 + feedback détaillé                    │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              BASE DE DONNÉES (SQLite)                       │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Tables:                                             │   │
│  │  - students (id, name, wechat_id)                   │   │
│  │  - submissions (id, student_id, file, timestamp)    │   │
│  │  - corrections (id, submission_id, score, feedback) │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│               FEEDBACK AUTOMATIQUE                          │
│  Bot renvoie message WeChat avec:                           │
│  - Score                                                    │
│  - Points positifs                                          │
│  - Points à améliorer                                       │
│  - Recommandations                                          │
└─────────────────────────────────────────────────────────────┘

🛠️ Stack technique

1. Bot WeChat

  • Framework : Wechaty (Node.js/TypeScript)
  • Puppet (protocole WeChat) :
    • padlocal : Payant (~8$/mois), stable, maintenu
    • wechat4u : Gratuit, moins stable, peut casser avec updates WeChat
    • Recommandation : padlocal pour production

2. Speech-to-Text (STT)

Option 1 : OpenAI Whisper API (Recommandé)

import OpenAI from 'openai'
import fs from 'fs'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

async function transcribe(audioPath) {
  const transcription = await openai.audio.transcriptions.create({
    file: fs.createReadStream(audioPath),
    model: "whisper-1",
    language: "zh", // ou "fr", "en"
  })
  return transcription.text
}

Avantages :

  • Multi-langue (FR/EN/CN/JP)
  • Précision excellente (~95%+)
  • Simple à intégrer
  • Gère mp3, mp4, mpeg, mpga, m4a, wav, webm

Inconvénients :

  • Nécessite accès internet stable
  • Coût : $0.006/minute (~¥0.04/minute)
  • Peut être lent depuis Chine (VPN recommandé)

Option 2 : Baidu ASR (Speech Recognition)

const AipSpeechClient = require("baidu-aip-sdk").speech

const client = new AipSpeechClient(APP_ID, API_KEY, SECRET_KEY)

async function transcribe(audioPath) {
  const voiceBuffer = fs.readFileSync(audioPath)
  const voiceBase64 = voiceBuffer.toString('base64')

  const result = await client.recognize(voiceBase64, 'pcm', 16000)
  return result.result[0]
}

Avantages :

  • Optimisé pour chinois
  • Rapide depuis Chine
  • Gratuit jusqu'à 50k appels/jour

Inconvénients :

  • Moins précis que Whisper
  • Nécessite conversion format audio
  • Documentation en chinois

Option 3 : Tencent Cloud ASR

Avantages :

  • Infrastructure en Chine (rapide)
  • Intégration WeChat native
  • Prix compétitifs

Inconvénients :

  • Setup complexe
  • Documentation chinoise

3. Correction automatique

GPT-4 API (Recommandé)

async function correctHomework(transcription, criteria) {
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [
      {
        role: "system",
        content: `Tu es un professeur de français. Corrige ce devoir oral selon ces critères:
        - Grammaire
        - Vocabulaire
        - Fluidité
        - Prononciation (basée sur la transcription)

        Donne un score /10 et un feedback constructif en 3-4 phrases.`
      },
      {
        role: "user",
        content: `Transcription de l'audio de l'étudiant:\n\n${transcription}`
      }
    ]
  })

  return response.choices[0].message.content
}

Prompt engineering tips :

  • Définir critères précis
  • Demander format structuré (JSON pour parsing)
  • Inclure exemples (few-shot learning)

4. Base de données

SQLite (recommandé pour POC/petit volume)

-- Schema SQL
CREATE TABLE students (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  wechat_id TEXT UNIQUE NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE submissions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  student_id INTEGER NOT NULL,
  filename TEXT NOT NULL,
  file_path TEXT NOT NULL,
  submitted_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (student_id) REFERENCES students(id)
);

CREATE TABLE corrections (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  submission_id INTEGER NOT NULL,
  transcription TEXT,
  score INTEGER,
  feedback TEXT,
  corrected_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (submission_id) REFERENCES submissions(id)
);

CREATE TABLE stats (
  student_id INTEGER PRIMARY KEY,
  total_submissions INTEGER DEFAULT 0,
  average_score REAL,
  last_submission DATETIME,
  FOREIGN KEY (student_id) REFERENCES students(id)
);

Alternative : PostgreSQL (si scale > 100 étudiants)

5. Infrastructure

Hébergement :

  • VPS Chine (Aliyun, Tencent Cloud) pour latence faible
  • Alternative : VPS étranger + VPN
  • Minimum : 2GB RAM, 20GB storage

OS : Ubuntu 22.04 LTS

Node.js : v18+ (LTS)


🔄 Workflow détaillé

1. Initialisation bot

// bot.js
import { WechatyBuilder } from 'wechaty'
import { PuppetPadlocal } from 'wechaty-puppet-padlocal'
import Database from './database.js'
import { transcribeAudio, correctHomework } from './ai.js'

const TOKEN = process.env.PADLOCAL_TOKEN

const bot = WechatyBuilder.build({
  puppet: new PuppetPadlocal({ token: TOKEN })
})

const db = new Database('./homework.db')

bot.on('login', user => {
  console.log(`✅ Bot logged in: ${user}`)
})

bot.on('message', handleMessage)

await bot.start()

2. Gestion messages

// handlers.js
async function handleMessage(message) {
  // Ignorer messages du bot lui-même
  if (message.self()) return

  const contact = message.talker()
  const type = message.type()
  const room = message.room()

  // Ignorer messages de groupe (optionnel)
  if (room) return

  // Traiter audio/vidéo
  if (type === bot.Message.Type.Audio ||
      type === bot.Message.Type.Video) {
    await handleMediaSubmission(message, contact)
  }

  // Commandes texte (optionnel)
  if (type === bot.Message.Type.Text) {
    const text = message.text()
    if (text === '/stats') {
      await sendStats(contact)
    }
  }
}

3. Traitement soumission

async function handleMediaSubmission(message, contact) {
  try {
    // 1. Accusé réception
    await message.say('📥 Devoir reçu ! Traitement en cours...')

    // 2. Téléchargement
    const fileBox = await message.toFileBox()
    const filename = `${Date.now()}_${contact.id()}_${fileBox.name}`
    const filepath = `./uploads/${filename}`
    await fileBox.toFile(filepath)

    // 3. Enregistrement DB
    const student = await db.getOrCreateStudent(contact.id(), contact.name())
    const submission = await db.createSubmission(student.id, filename, filepath)

    // 4. Transcription
    const transcription = await transcribeAudio(filepath)

    // 5. Correction
    const correction = await correctHomework(transcription)

    // 6. Enregistrement résultat
    await db.saveCorrection(submission.id, transcription, correction.score, correction.feedback)

    // 7. Envoi feedback
    const feedbackMessage = `
✅ Devoir corrigé !

📊 Score: ${correction.score}/10

💬 Feedback:
${correction.feedback}

Bon courage ! 💪
    `.trim()

    await contact.say(feedbackMessage)

    // 8. Update stats
    await db.updateStats(student.id)

  } catch (error) {
    console.error('❌ Erreur traitement:', error)
    await contact.say('⚠️ Erreur lors du traitement. Réessaye ou contacte le prof.')
  }
}

4. Gestion vidéo (extraction audio)

import ffmpeg from 'fluent-ffmpeg'

async function extractAudioFromVideo(videoPath) {
  const audioPath = videoPath.replace(/\.(mp4|mov|avi)$/, '.mp3')

  return new Promise((resolve, reject) => {
    ffmpeg(videoPath)
      .toFormat('mp3')
      .on('end', () => resolve(audioPath))
      .on('error', reject)
      .save(audioPath)
  })
}

5. Statistiques étudiant

async function sendStats(contact) {
  const student = await db.getStudent(contact.id())
  if (!student) {
    await contact.say('Aucun devoir rendu pour le moment.')
    return
  }

  const stats = await db.getStats(student.id)

  const message = `
📊 Tes statistiques:

📝 Devoirs rendus: ${stats.total_submissions}
⭐ Moyenne: ${stats.average_score.toFixed(1)}/10
📅 Dernier devoir: ${stats.last_submission}

Continue comme ça ! 🚀
  `.trim()

  await contact.say(message)
}

⚠️ Risques et mitigations

1. Ban compte WeChat

Risque : WeChat détecte comportement automatisé → ban temporaire/permanent

Probabilité :

  • Compte principal : ~40%
  • Compte secondaire dédié : ~15%
  • Avec padlocal (payant) : ~5%

Mitigations :

  • Utiliser compte WeChat dédié (pas compte perso)
  • Puppet stable (padlocal > wechat4u)
  • Rate limiting : Ne pas répondre instantanément (delay 2-5s)
  • Humanisation : Varier temps de réponse
  • Éviter spam : Max 50 messages/heure
  • Warmup : Utiliser compte manuellement 1-2 semaines avant automation

Plan B si ban :

  • Compte backup prêt
  • Export données régulier
  • Alternative : WeChat Official Account (route officielle)

2. Instabilité Wechaty/Puppet

Risque : Updates WeChat cassent le protocole → bot offline

Probabilité : ~10-20% sur 6 mois (wechat4u), ~2-5% (padlocal)

Mitigations :

  • Monitoring : Alertes si bot offline >30min
  • Auto-restart : PM2 ou systemd
  • Logs : Debugging rapide
  • Puppet payant (padlocal) pour stabilité

3. Qualité transcription

Risque : Mauvaise qualité audio → transcription incorrecte → correction biaisée

Probabilité : 15-25% des submissions

Mitigations :

  • Consignes claires aux étudiants (environnement calme, micro proche)
  • Validation manuelle échantillon aléatoire (10%)
  • Flag low confidence : Whisper donne confidence score
  • Fallback : Si score <0.7, demander humain

4. Coûts API

Risque : Coûts explosent si volume important

Estimation mensuelle (20 étudiants, 3 devoirs/semaine, 2min audio moyenne) :

  • Transcription (Whisper) : 20 × 3 × 4 × 2min × $0.006 = $2.88/mois
  • Correction (GPT-4) : 60 corrections × $0.03 = $1.80/mois
  • Total API : ~$5/mois
  • Padlocal : $8/mois
  • VPS : $5-10/mois

Total estimé : $18-23/mois

Mitigations :

  • Quotas : Limite devoirs/étudiant/semaine
  • Caching : Ne pas retraiter si déjà fait
  • Alternative gratuite : Baidu STT (50k/jour gratuit)

5. Privacy/RGPD

Risque : Stockage données sensibles (voix étudiants)

Mitigations :

  • Consentement explicite étudiants
  • Encryption fichiers sensibles
  • Rétention : Auto-delete après 3 mois
  • Anonymisation : Hash WeChat IDs

6. Dépendance internet

Risque : API externes down → bot inutilisable

Mitigations :

  • Queue system : Redis/Bull pour retry automatique
  • Fallback : Mode dégradé (just download, manual correction)
  • Monitoring : Uptime alerts

🚀 Plan d'implémentation

Phase 1 : POC (Proof of Concept) - 2 jours

Objectif : Valider faisabilité technique end-to-end

Livrables :

  • Bot Wechaty qui se connecte
  • Réception 1 audio/vidéo
  • Download fichier localement
  • Envoi à Whisper API
  • Retour transcription au user

Stack minimal :

  • Wechaty + wechat4u (gratuit pour tester)
  • OpenAI Whisper API
  • Pas de DB (juste logs)

Critère succès : 1 cycle complet fonctionnel

Phase 2 : MVP (Minimum Viable Product) - 1 semaine

Objectif : Version utilisable avec 1 classe test

Livrables :

  • Database SQLite (students, submissions, corrections)
  • Correction automatique GPT-4
  • Feedback formaté
  • Gestion erreurs basique
  • Commande /stats

Stack :

  • Upgrade vers padlocal (stable)
  • SQLite + better-sqlite3
  • GPT-4 API integration
  • Error handling + logging

Critère succès : 5 étudiants tests pendant 1 semaine

Phase 3 : Production - 2 semaines

Objectif : Déploiement avec 2 classes complètes

Livrables :

  • VPS déployé (Chine ou VPN)
  • PM2 auto-restart
  • Monitoring (Uptime Kuma ou similaire)
  • Dashboard stats (optionnel)
  • Documentation utilisateur
  • Backup automatique DB

Infrastructure :

  • VPS (Aliyun/Tencent Cloud ou Hetzner+VPN)
  • Nginx reverse proxy
  • Let's Encrypt SSL
  • Daily backup S3/OSS

Critère succès : 95% uptime sur 2 semaines

Phase 4 : Optimisation - Ongoing

Features additionnelles :

  • Dashboard web (stats agrégées)
  • Export Excel statistiques
  • Correction par niveaux (débutant/intermédiaire/avancé)
  • Multi-langue (FR/EN switch auto)
  • Voice feedback (TTS pour audio response)
  • Plagiarism detection
  • Progress tracking over time

💰 Coûts

Setup initial (one-time)

  • Développement : DIY (0€) ou freelance (500-1500€)
  • VPS setup : 0€ (si DIY)
  • Compte WeChat dédié : 0€ (création gratuite)

Récurrent mensuel

Poste Coût mensuel Note
Padlocal token $8 (~7€) Puppet stable, recommandé production
VPS $5-15 Aliyun/Hetzner selon localisation
Whisper API $3-10 Dépend volume (20-50 étudiants)
GPT-4 API $5-15 Dépend longueur feedbacks
Domain (optionnel) $1 Si dashboard web
Backup storage $1-2 S3/OSS pour backups DB
TOTAL $23-51/mois ~20-45€/mois

Scaling costs

50 étudiants :

  • Whisper : ~$10/mois
  • GPT-4 : ~$20/mois
  • Total : ~$40-55/mois

100 étudiants :

  • Whisper : ~$20/mois
  • GPT-4 : ~$40/mois
  • VPS upgrade : $20/mois
  • Total : ~$90-110/mois

ROI (Return on Investment)

Temps gagné (estimation) :

  • Correction manuelle : ~5min/devoir
  • Correction auto : ~30s/devoir (juste validation)
  • Gain : 4.5min/devoir

Pour 20 étudiants, 3 devoirs/semaine :

  • 60 devoirs/semaine × 4.5min = 270 min/semaine = 4.5h/semaine
  • 18h/mois gagnées

Coût horaire : $25/mois ÷ 18h = $1.40/h

Rentable si ton temps vaut >$2/h (spoiler: oui)


🔀 Alternatives

Alternative 1 : WeChat Official Account (route officielle)

Description : Créer un Official Account WeChat et utiliser l'API officielle

Avantages :

  • Légal, supporté par WeChat
  • Stable (pas de risque ban)
  • Features avancées (menus, paiements, etc.)

Inconvénients :

  • Nécessite vérification (entreprise chinoise)
  • Process bureaucratique (2-4 semaines)
  • Coûts annuels (300 RMB/an ~40€)
  • Limitations API (quotas stricts)

Recommandation : Pour usage éducatif personnel → Overkill

Alternative 2 : Workflow semi-automatique

Description : Étudiants uploadent sur plateforme (Google Drive, WeTransfer) → traitement batch

Avantages :

  • Pas de risque ban WeChat
  • Plus simple techniquement
  • Meilleur contrôle qualité fichiers

Inconvénients :

  • Friction étudiants (changer habitudes)
  • Pas de feedback instantané
  • Nécessite discipline upload

Recommandation : Backup plan si Wechaty trop instable

Alternative 3 : Telegram Bot

Description : Utiliser Telegram au lieu de WeChat

Avantages :

  • API officielle gratuite et stable
  • Excellente documentation
  • Pas de risque ban
  • Features riches (keyboards, inline, etc.)

Inconvénients :

  • Étudiants chinois utilisent peu Telegram
  • VPN nécessaire en Chine (Telegram bloqué)
  • Friction adoption

Recommandation : Si étudiants non-Chinois ou tech-savvy

Alternative 4 : DingTalk Bot

Description : Utiliser DingTalk (钉钉), plateforme pro chinoise

Avantages :

  • API officielle pour éducation
  • Utilisé dans écoles chinoises
  • Stable, pas de risque ban
  • Features éducation intégrées

Inconvénients :

  • Moins personnel que WeChat
  • Setup groupe de travail nécessaire
  • Documentation chinoise

Recommandation : Si contexte semi-officiel (collaboration école)

Comparaison rapide

Critère Wechaty Official Account Telegram DingTalk
Facilité adoption
Stabilité technique
Setup rapidité
Coût
Risque légal

Recommandation finale : Wechaty pour POC/MVP, migrer vers Official Account si scale


📚 Ressources

Documentation officielle

Puppets (protocoles WeChat)

Alternatives STT (Speech-to-Text)

Tutoriels et articles

Code examples

Infrastructure

VPS providers Chine


🎯 Next Steps

Actions immédiates

  1. Décision : Valider concept et approuver développement
  2. Setup :
    • Créer compte WeChat dédié (si pas déjà fait)
    • Acheter token Padlocal (ou tester wechat4u gratuit)
    • Créer compte OpenAI + ajouter crédits ($10 pour commencer)
  3. Dev POC : 1 weekend pour prototype fonctionnel
  4. Test : 1 semaine avec 3-5 étudiants pilotes
  5. Itération : Ajuster selon feedbacks
  6. Deployment : VPS + production avec toutes les classes

Questions ouvertes

  • Quel type de cours ? (FR/EN/CN/autre) → Impact prompts correction
  • Critères de correction ? (grammaire, vocabulaire, prononciation, fluidité)
  • Format feedback ? (score seul, détaillé, recommandations)
  • Fréquence devoirs ? (quotidien, hebdo) → Impact coûts
  • Deadline rendu ? (système de rappels automatiques ?)

Mesures de succès

POC :

  • 1 cycle complet fonctionnel
  • Temps traitement <2min
  • Précision transcription >85%

MVP :

  • 5 étudiants utilisent pendant 1 semaine
  • 0 crash critique
  • Feedback étudiants positif (>7/10)

Production :

  • 95% uptime
  • Temps gagné >15h/mois
  • Satisfaction étudiants >8/10
  • ROI <3 mois

📝 Notes

Créé : 2025-11-29 Auteur : Alexis Trouvé Status : CONCEPT → À valider avant passage WIP Prochaine review : TBD

Changements majeurs :

  • 2025-11-29 : Création document initial

Tags : #wechat #bot #automation #education #ai #stt #gpt4 #wechaty