couple-repo/Projects/WIP/wechat_miniapp_homework.md

# WeChat Mini Program - Auto-Correction Homework System

**Status**: WIP
**Created**: 2025-11-30
**Moved to WIP**: 2025-11-30
**Horizon**: Plusieurs années (usage long terme)
**Use Case**: Mini Program WeChat pour soumettre devoirs audio/vidéo et recevoir corrections automatiques AI
**Target**: Cours particuliers d'Alexis (2 classes, usage éducatif privé)
**Alternative**: Bot Wechaty (voir `wechat_homework_bot.md`)

---

## 📋 Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Pourquoi Mini Program > Bot](#pourquoi-mini-program--bot)
3. [Faisabilité technique](#faisabilité-technique)
4. [Architecture système](#architecture-système)
5. [Stack technique](#stack-technique)
6. [Features détaillées](#features-détaillées)
7. [Design & UX](#design--ux)
8. [Backend API](#backend-api)
9. [Workflow utilisateur](#workflow-utilisateur)
10. [Risques et mitigations](#risques-et-mitigations)
11. [Plan d'implémentation](#plan-dimplémentation)
12. [Coûts](#coûts)
13. [Requirements WeChat](#requirements-wechat)
14. [Process Setup Compte WeChat Developer](#process-setup-compte-wechat-developer)
15. [Ressources](#ressources)

---

## 🎯 Vue d'ensemble

### Problème
- Étudiants envoient devoirs audio/vidéo de manière désorganisée
- Collecte manuelle chronophage
- Correction manuelle répétitive
- Pas de tracking automatique
- Feedback non standardisé

### Solution : WeChat Mini Program

Application native WeChat permettant de :
1. **Soumettre** devoirs audio/vidéo avec interface dédiée
2. **Transcrire** automatiquement (Whisper API)
3. **Corriger** avec AI (GPT-4)
4. **Afficher** feedback structuré en temps réel
5. **Tracker** progression individuelle
6. **Consulter** historique et statistiques

### Bénéfices vs Bot Wechaty

| Avantage | Impact |
|----------|--------|
| **Zéro risque ban** | Stabilité long terme garantie |
| **UX native** | Adoption étudiants +50% |
| **Features riches** | Historique, stats, notifications |
| **Scalabilité** | Illimitée (vs bot limité) |
| **Professionnalisme** | Crédibilité auprès parents/école |

---

## ✅ Pourquoi Mini Program > Bot

### Comparaison directe

| Critère | Bot Wechaty | Mini Program ⭐ |
|---------|-------------|----------------|
| **Risque ban** | 5-15% ❌ | 0% ✅ |
| **Setup initial** | 2 jours ✅ | 5-7 jours ⚠️ |
| **Stabilité** | Moyenne | Excellente ✅ |
| **UX étudiant** | Messages WeChat | App dédiée ✅ |
| **Features** | Limitées | Illimitées ✅ |
| **Coût mensuel** | $23-51 | $10-30 ✅ |
| **Scalabilité** | ~50 users | Illimitée ✅ |
| **Pérennité** | Risquée | Garantie ✅ |

### Cas d'usage recommandés

**Mini Program** si :
- ✅ Usage >3 mois
- ✅ Classes stables
- ✅ Volonté investir 1 semaine dev
- ✅ Besoin crédibilité/professionnalisme

**Bot Wechaty** si :
- ✅ Test <2 mois
- ✅ POC rapide
- ✅ Pas sûr de continuer

---

## 🔧 Faisabilité technique

### Verdict : **100% FAISABLE**

### Capacités WeChat Mini Program confirmées

**API natives disponibles** :
- ✅ `wx.chooseMedia()` - Sélection audio/vidéo/image
- ✅ `wx.getRecorderManager()` - Enregistrement audio natif
- ✅ `wx.uploadFile()` - Upload fichiers vers serveur
- ✅ `wx.request()` - API REST calls
- ✅ `wx.showToast()` / `wx.showModal()` - Notifications
- ✅ `wx.navigateTo()` - Navigation pages
- ✅ Template Messages - Notifications push

**Limitations techniques** :
- Upload fichier : Max 100MB (largement suffisant pour audio/vidéo courts)
- Durée enregistrement : Illimitée (gérer côté app)
- Formats supportés : mp3, mp4, m4a, wav (tous compatibles Whisper)

### Proof of concept

```javascript
// Exemple minimal fonctionnel
Page({
  uploadHomework() {
    wx.chooseMedia({
      count: 1,
      mediaType: ['video', 'audio'],
      success: (res) => {
        wx.uploadFile({
          url: 'https://api.example.com/homework',
          filePath: res.tempFiles[0].tempFilePath,
          name: 'file',
          success: (uploadRes) => {
            wx.showToast({ title: 'Envoyé !' })
          }
        })
      }
    })
  }
})
```

---

## 🏗️ Architecture système

```
┌─────────────────────────────────────────────────────────────────┐
│                   ÉTUDIANT (WeChat App)                         │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │           WeChat Mini Program Frontend                   │  │
│  │  - Upload audio/vidéo                                    │  │
│  │  - Enregistrement natif                                  │  │
│  │  - Historique devoirs                                    │  │
│  │  - Stats progression                                     │  │
│  └──────────────────────┬───────────────────────────────────┘  │
└─────────────────────────┼───────────────────────────────────────┘
                          │
                          │ HTTPS (wx.uploadFile / wx.request)
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     BACKEND SERVER (VPS)                        │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                REST API (Express.js)                     │  │
│  │  POST   /api/homework         - Upload devoir           │  │
│  │  GET    /api/homework/:id     - Status correction       │  │
│  │  GET    /api/student/stats    - Statistiques            │  │
│  │  GET    /api/student/history  - Historique              │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         │                                       │
│  ┌──────────────────────▼───────────────────────────────────┐  │
│  │              JOB QUEUE (Bull + Redis)                    │  │
│  │  - process-homework (async)                              │  │
│  │  - send-notification                                     │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         │                                       │
│  ┌──────────────────────▼───────────────────────────────────┐  │
│  │              FILE STORAGE (./uploads/)                   │  │
│  │  timestamp_studentId_filename.mp3/mp4                    │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │            DATABASE (PostgreSQL/SQLite)                  │  │
│  │  - students                                              │  │
│  │  - assignments                                           │  │
│  │  - submissions                                           │  │
│  │  - corrections                                           │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          │ API Calls
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Whisper    │  │    GPT-4     │  │   WeChat     │
│     API      │  │     API      │  │  Notify API  │
│              │  │              │  │              │
│ Transcription│  │  Correction  │  │  Template    │
│   Audio→Text │  │  + Feedback  │  │   Message    │
└──────────────┘  └──────────────┘  └──────────────┘
```

---

## 🛠️ Stack technique

### 1. Frontend (WeChat Mini Program)

**Langage** : JavaScript (WXML/WXSS, similaire HTML/CSS mais propriétaire)

**Structure fichiers** :
```
miniprogram/
├── pages/
│   ├── index/          # Page accueil
│   ├── upload/         # Upload devoir
│   ├── history/        # Historique
│   ├── detail/         # Détail correction
│   └── stats/          # Statistiques
├── components/
│   ├── recorder/       # Enregistreur audio custom
│   └── progress/       # Barre progression
├── utils/
│   ├── api.js          # Helper API calls
│   └── auth.js         # WeChat login
├── app.js              # Entry point
├── app.json            # Config app
└── app.wxss            # Styles globaux
```

**Frameworks/Libs** :
- **WeChat DevTools** (IDE officiel) - Obligatoire
- **Vant Weapp** (UI components) - Optionnel mais recommandé
- **WeUI** (style guide WeChat) - Recommandé

### 2. Backend

**Langage** : Node.js 18+ (TypeScript optionnel)

**Framework** : Express.js

**Structure** :
```
server/
├── src/
│   ├── routes/
│   │   ├── homework.js
│   │   ├── student.js
│   │   └── auth.js
│   ├── controllers/
│   │   ├── homeworkController.js
│   │   └── studentController.js
│   ├── services/
│   │   ├── whisperService.js     # Transcription
│   │   ├── gptService.js         # Correction
│   │   └── wechatService.js      # Notifications
│   ├── jobs/
│   │   └── processHomework.js    # Worker async
│   ├── models/
│   │   ├── Student.js
│   │   ├── Submission.js
│   │   └── Correction.js
│   ├── middleware/
│   │   ├── auth.js               # JWT validation
│   │   └── upload.js             # Multer config
│   └── utils/
│       ├── db.js
│       └── logger.js
├── uploads/                       # Fichiers temporaires
├── .env                          # Variables env
└── server.js                     # Entry point
```

**Key dependencies** :
```json
{
  "express": "^4.18.0",
  "multer": "^1.4.5-lts.1",
  "bull": "^4.12.0",
  "redis": "^4.6.0",
  "pg": "^8.11.0",              // PostgreSQL
  "openai": "^4.20.0",           // Whisper + GPT-4
  "dotenv": "^16.3.0",
  "jsonwebtoken": "^9.0.0",
  "axios": "^1.6.0"
}
```

### 3. Database

**PostgreSQL** (recommandé) ou SQLite (POC)

**Schema** :
```sql
-- Students (liaison WeChat OpenID)
CREATE TABLE students (
  id SERIAL PRIMARY KEY,
  wechat_openid VARCHAR(100) UNIQUE NOT NULL,
  nickname VARCHAR(100),
  class_name VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW()
);

-- Assignments (devoirs à faire)
CREATE TABLE assignments (
  id SERIAL PRIMARY KEY,
  title VARCHAR(200) NOT NULL,
  description TEXT,
  due_date TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Submissions (devoirs rendus)
CREATE TABLE submissions (
  id SERIAL PRIMARY KEY,
  student_id INTEGER REFERENCES students(id),
  assignment_id INTEGER REFERENCES assignments(id),
  file_path VARCHAR(500) NOT NULL,
  file_type VARCHAR(20),              -- 'audio' | 'video'
  file_size INTEGER,
  status VARCHAR(20) DEFAULT 'pending', -- pending | processing | completed | error
  submitted_at TIMESTAMP DEFAULT NOW()
);

-- Corrections
CREATE TABLE corrections (
  id SERIAL PRIMARY KEY,
  submission_id INTEGER REFERENCES submissions(id) UNIQUE,
  transcription TEXT,
  score INTEGER,                       -- 0-100
  feedback_json JSONB,                 -- Structure feedback détaillé
  corrected_at TIMESTAMP DEFAULT NOW()
);

-- Stats cache (pour performance)
CREATE TABLE student_stats (
  student_id INTEGER PRIMARY KEY REFERENCES students(id),
  total_submissions INTEGER DEFAULT 0,
  average_score REAL,
  last_submission TIMESTAMP,
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Indexes pour performance
CREATE INDEX idx_submissions_student ON submissions(student_id);
CREATE INDEX idx_submissions_status ON submissions(status);
CREATE INDEX idx_corrections_submission ON corrections(submission_id);
```

### 4. Job Queue

**Bull** (Redis-based) pour traitement asynchrone

**Pourquoi** :
- Upload fichier = retour immédiat
- Transcription + Correction = traitement async (peut prendre 30-60s)
- Retry automatique si échec
- Monitoring jobs

```javascript
// jobs/processHomework.js
const Queue = require('bull');
const homeworkQueue = new Queue('homework', process.env.REDIS_URL);

homeworkQueue.process(async (job) => {
  const { submissionId, filePath } = job.data;

  // 1. Transcription
  job.progress(30);
  const transcription = await whisperService.transcribe(filePath);

  // 2. Correction
  job.progress(60);
  const correction = await gptService.correct(transcription);

  // 3. Save DB
  job.progress(90);
  await db.saveCorrection(submissionId, correction);

  // 4. Notify student
  await wechatService.sendTemplateMessage(submissionId);

  return { success: true };
});
```

### 5. AI Services

#### Whisper API (Transcription)
```javascript
// services/whisperService.js
const OpenAI = require('openai');
const fs = require('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: "fr", // ou "zh", "en"
    response_format: "verbose_json" // Inclut timestamps, confidence
  });

  return {
    text: transcription.text,
    duration: transcription.duration,
    confidence: transcription.segments[0]?.confidence || 0
  };
}
```

#### GPT-4 API (Correction)
```javascript
// services/gptService.js
async function correct(transcription, assignmentCriteria) {
  const prompt = `
Tu es un professeur de français expérimenté. Corrige ce devoir oral selon ces critères :

**Critères d'évaluation** :
1. Grammaire (0-25 points)
2. Vocabulaire (0-25 points)
3. Fluidité (0-25 points)
4. Prononciation (0-25 points)

**Transcription** :
${transcription.text}

**Format de réponse** (JSON strict) :
{
  "score_total": 0-100,
  "scores_details": {
    "grammaire": 0-25,
    "vocabulaire": 0-25,
    "fluidite": 0-25,
    "prononciation": 0-25
  },
  "points_positifs": ["...", "..."],
  "points_ameliorer": ["...", "..."],
  "recommandations": "...",
  "erreurs_principales": [
    {"texte": "...", "correction": "...", "explication": "..."}
  ]
}
`;

  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [
      { role: "system", content: "Tu es un correcteur expert. Réponds UNIQUEMENT en JSON valide." },
      { role: "user", content: prompt }
    ],
    temperature: 0.3,
    response_format: { type: "json_object" }
  });

  return JSON.parse(response.choices[0].message.content);
}
```

### 6. Infrastructure

**Hébergement** :
- **VPS Chine** : Aliyun, Tencent Cloud (si besoin ICP license pour publication)
- **VPS International** : Hetzner, DigitalOcean, Vultr (+ VPN si blocages)
- **Serverless** : Vercel/Railway (backend) + Cloudflare R2 (storage)

**Requirements minimaux** :
- 2GB RAM
- 2 vCPU
- 30GB SSD
- Ubuntu 22.04 LTS

**Stack deployment** :
- **PM2** : Process manager + auto-restart
- **Nginx** : Reverse proxy + SSL
- **Let's Encrypt** : Certificats SSL gratuits
- **Redis** : Job queue + cache

---

## 🎨 Features détaillées

### MVP (Phase 1)

#### 1. Authentification
- Login WeChat automatique (`wx.login()`)
- Récupération OpenID (identifiant unique anonyme)
- Stockage JWT pour API calls

#### 2. Soumission devoir
- **Upload fichier existant** :
  - Bouton "Choisir fichier" → `wx.chooseMedia()`
  - Preview audio/vidéo avant envoi
  - Indication taille fichier
- **Enregistrement direct** :
  - Bouton "Enregistrer" → `wx.getRecorderManager()`
  - Timer temps réel
  - Bouton pause/reprendre
  - Écoute playback avant envoi
- **Métadonnées** :
  - Sélection assignment (si multiple devoirs)
  - Commentaire optionnel étudiant
- **Upload** :
  - Progress bar temps réel
  - Retry automatique si échec réseau
  - Notification succès

#### 3. Status correction
- **Page status temps réel** :
  - "⏳ En cours de traitement..."
  - "🎧 Transcription audio..." (30%)
  - "🤖 Correction en cours..." (60%)
  - "✅ Terminé !" (100%)
- **Notifications push** :
  - Template Message WeChat quand correction prête

#### 4. Affichage feedback
- **Score global** : Grande card avec score/100
- **Scores détaillés** :
  - Grammaire : 18/25
  - Vocabulaire : 20/25
  - Fluidité : 15/25
  - Prononciation : 17/25
- **Points positifs** : Liste avec icônes ✅
- **Points à améliorer** : Liste avec icônes ⚠️
- **Erreurs principales** :
  - Texte original
  - Correction suggérée
  - Explication courte
- **Recommandations** : Paragraphe synthèse

#### 5. Historique
- **Liste devoirs** :
  - Tri par date (récent → ancien)
  - Card par devoir : Date, titre, score, status
  - Filtre par status (tous, corrigés, en attente)
- **Navigation** : Tap card → Page détail correction

#### 6. Statistiques basiques
- **Nombre devoirs rendus**
- **Score moyen**
- **Dernier devoir**
- **Graphique progression** (scores au fil du temps)

### Phase 2 (Features avancées)

#### 7. Gestion assignments professeur
- Interface admin (web ou mini program séparé)
- Création devoirs avec :
  - Titre, description, deadline
  - Critères correction custom
  - Durée audio min/max
- Suivi temps réel (qui a rendu, qui manque)

#### 8. Notifications intelligentes
- Rappels deadline (J-3, J-1, J-day)
- Encouragements progression
- Alerts baisse performance

#### 9. Gamification
- Badges (3 devoirs d'affilée, score >90, etc.)
- Leaderboard classe (optionnel, opt-in)
- Streaks (jours consécutifs)

#### 10. Export données
- Export Excel stats élève
- PDF rapport individuel
- Partage parents (QR code)

#### 11. Multi-langue
- Switch FR/EN/CN
- Détection langue audio automatique
- Feedback dans langue de l'étudiant

#### 12. Voice feedback
- Option TTS (Text-to-Speech) pour lire feedback
- Audio correction prononciation

---

## 🎨 Design & UX

### Thème visuel

**Identité** :
- Clean, éducatif, encourageant
- Couleurs : Bleu primary (#1989FA WeChat), Vert success (#07C160), Rouge error (#EE0A24)
- Icons : WeUI icons standard

### Pages principales

#### Page 1 : Home
```
┌─────────────────────────────┐
│  👋 Bonjour, [Nickname]     │
│                             │
│  📊 Tes statistiques        │
│  ┌─────────────────────┐   │
│  │ Devoirs : 12        │   │
│  │ Moyenne : 78/100    │   │
│  │ Dernier : Il y a 2j │   │
│  └─────────────────────┘   │
│                             │
│  [📤 Nouveau devoir]        │
│                             │
│  📝 Devoirs récents         │
│  ┌─────────────────────┐   │
│  │ 28 Nov - Devoir 5   │   │
│  │ ✅ 82/100           │   │
│  └─────────────────────┘   │
│  ┌─────────────────────┐   │
│  │ 26 Nov - Devoir 4   │   │
│  │ ⏳ En cours...       │   │
│  └─────────────────────┘   │
│                             │
│  [Historique complet]       │
└─────────────────────────────┘
 Home    Upload    Stats
```

#### Page 2 : Upload
```
┌─────────────────────────────┐
│  📤 Soumettre un devoir     │
│                             │
│  Devoir : [Dropdown v]      │
│  Devoir 5 - Présentation    │
│                             │
│  ┌─────────────────────┐   │
│  │   🎙️ Enregistrer    │   │
│  │      audio          │   │
│  └─────────────────────┘   │
│                             │
│  ┌─────────────────────┐   │
│  │   📁 Choisir        │   │
│  │      fichier        │   │
│  └─────────────────────┘   │
│                             │
│  Commentaire (optionnel):   │
│  ┌─────────────────────┐   │
│  │                     │   │
│  └─────────────────────┘   │
│                             │
│  [Envoyer]                  │
└─────────────────────────────┘
```

#### Page 3 : Feedback détail
```
┌─────────────────────────────┐
│  Devoir 5 - 28 Nov 2025     │
│                             │
│  ┌─────────────────────┐   │
│  │      82/100         │   │
│  │      ⭐⭐⭐⭐         │   │
│  └─────────────────────┘   │
│                             │
│  Détails :                  │
│  Grammaire    ███████ 18/25 │
│  Vocabulaire  ████████ 20/25│
│  Fluidité     ██████ 15/25  │
│  Prononciation ███████ 17/25│
│                             │
│  ✅ Points positifs :       │
│  • Bon vocabulaire varié    │
│  • Structure claire         │
│                             │
│  ⚠️ À améliorer :            │
│  • Accord verbes            │
│  • Prononciation 'u'        │
│                             │
│  💡 Recommandations :       │
│  Revise les accords...      │
│                             │
│  [Voir transcription]       │
└─────────────────────────────┘
```

### Composants réutilisables

#### ScoreCard Component
```javascript
// components/score-card/score-card.js
Component({
  properties: {
    score: Number,
    maxScore: { type: Number, value: 100 }
  },
  data: {
    percentage: 0,
    stars: 0
  },
  lifetimes: {
    attached() {
      const percentage = (this.data.score / this.data.maxScore) * 100;
      const stars = Math.round(percentage / 20); // 0-5 étoiles
      this.setData({ percentage, stars });
    }
  }
})
```

---

## 🔌 Backend API

### Endpoints complets

#### 1. Authentication

**POST `/api/auth/login`**
```javascript
// Request
{
  "code": "WeChat login code"
}

// Response
{
  "token": "JWT_TOKEN",
  "student": {
    "id": 123,
    "nickname": "张三",
    "class": "Class A"
  }
}
```

#### 2. Assignments

**GET `/api/assignments`**
```javascript
// Response
[
  {
    "id": 1,
    "title": "Devoir 5 - Présentation famille",
    "description": "Présente ta famille en 2 minutes",
    "due_date": "2025-12-05T23:59:59Z",
    "status": "active"
  }
]
```

#### 3. Submissions

**POST `/api/homework`**
```javascript
// Request (multipart/form-data)
{
  "file": File,
  "assignment_id": 1,
  "comment": "Voici mon devoir"
}

// Response
{
  "submission_id": 456,
  "status": "pending",
  "message": "Devoir reçu ! Traitement en cours..."
}
```

**GET `/api/homework/:id`**
```javascript
// Response
{
  "id": 456,
  "status": "completed", // pending | processing | completed | error
  "progress": 100,
  "submitted_at": "2025-11-30T10:30:00Z",
  "corrected_at": "2025-11-30T10:32:15Z",
  "file_type": "audio",
  "correction": {
    "score_total": 82,
    "scores_details": {
      "grammaire": 18,
      "vocabulaire": 20,
      "fluidite": 15,
      "prononciation": 17
    },
    "points_positifs": ["Vocabulaire varié", "Structure claire"],
    "points_ameliorer": ["Accords verbes", "Prononciation 'u'"],
    "recommandations": "...",
    "transcription": "Bonjour je m'appelle..."
  }
}
```

#### 4. Student Stats

**GET `/api/student/stats`**
```javascript
// Response
{
  "total_submissions": 12,
  "average_score": 78.5,
  "last_submission": "2025-11-30T10:30:00Z",
  "scores_history": [
    { "date": "2025-11-15", "score": 75 },
    { "date": "2025-11-20", "score": 80 },
    { "date": "2025-11-25", "score": 82 }
  ]
}
```

**GET `/api/student/history`**
```javascript
// Query params: ?limit=20&offset=0&status=all
// Response
{
  "submissions": [
    {
      "id": 456,
      "assignment_title": "Devoir 5",
      "submitted_at": "2025-11-30T10:30:00Z",
      "status": "completed",
      "score": 82
    }
  ],
  "total": 12
}
```

### Implementation complète

```javascript
// routes/homework.js
const express = require('express');
const multer = require('multer');
const router = express.Router();
const homeworkController = require('../controllers/homeworkController');
const authMiddleware = require('../middleware/auth');

const upload = multer({
  dest: 'uploads/',
  limits: { fileSize: 100 * 1024 * 1024 }, // 100MB
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['audio/mpeg', 'audio/mp4', 'video/mp4'];
    if (allowedTypes.includes(file.mimetype)) {
      cb(null, true);
    } else {
      cb(new Error('Type fichier non supporté'));
    }
  }
});

router.post(
  '/homework',
  authMiddleware.verifyToken,
  upload.single('file'),
  homeworkController.submit
);

router.get(
  '/homework/:id',
  authMiddleware.verifyToken,
  homeworkController.getStatus
);

module.exports = router;
```

```javascript
// controllers/homeworkController.js
const homeworkQueue = require('../jobs/processHomework');
const db = require('../utils/db');

exports.submit = async (req, res) => {
  try {
    const { assignment_id, comment } = req.body;
    const file = req.file;
    const studentId = req.user.id; // From JWT

    // Save submission DB
    const submission = await db.query(`
      INSERT INTO submissions (student_id, assignment_id, file_path, file_type, file_size)
      VALUES ($1, $2, $3, $4, $5)
      RETURNING id
    `, [studentId, assignment_id, file.path, file.mimetype.split('/')[0], file.size]);

    const submissionId = submission.rows[0].id;

    // Add to job queue (async processing)
    await homeworkQueue.add('process-homework', {
      submissionId,
      filePath: file.path,
      fileType: file.mimetype
    });

    res.json({
      submission_id: submissionId,
      status: 'pending',
      message: 'Devoir reçu ! Traitement en cours...'
    });

  } catch (error) {
    console.error('Submit error:', error);
    res.status(500).json({ error: 'Erreur serveur' });
  }
};

exports.getStatus = async (req, res) => {
  try {
    const { id } = req.params;
    const studentId = req.user.id;

    // Get submission + correction
    const result = await db.query(`
      SELECT
        s.*,
        c.transcription,
        c.score,
        c.feedback_json,
        c.corrected_at
      FROM submissions s
      LEFT JOIN corrections c ON s.id = c.submission_id
      WHERE s.id = $1 AND s.student_id = $2
    `, [id, studentId]);

    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Devoir non trouvé' });
    }

    const submission = result.rows[0];

    res.json({
      id: submission.id,
      status: submission.status,
      submitted_at: submission.submitted_at,
      corrected_at: submission.corrected_at,
      correction: submission.feedback_json ? {
        score_total: submission.score,
        ...submission.feedback_json,
        transcription: submission.transcription
      } : null
    });

  } catch (error) {
    console.error('GetStatus error:', error);
    res.status(500).json({ error: 'Erreur serveur' });
  }
};
```

---

## 🔄 Workflow utilisateur

### Scénario complet

**1. Première connexion (one-time)**
```
Étudiant ouvre Mini Program
→ wx.login() automatique
→ Backend crée compte avec OpenID
→ Demande nickname (optionnel)
→ Assign à classe (via code invitation ou manual)
```

**2. Soumission devoir**
```
Étudiant clique "Nouveau devoir"
→ Sélectionne assignment (dropdown)
→ Choix : Enregistrer OU Upload fichier

[Enregistrement]
→ Clique bouton micro
→ Enregistre (timer visible)
→ Arrête enregistrement
→ Écoute playback (bouton play)
→ Valide ou recommence

[Upload]
→ Clique "Choisir fichier"
→ Sélectionne depuis galerie/fichiers
→ Preview fichier

→ (Optionnel) Ajoute commentaire
→ Clique "Envoyer"
→ Progress bar upload (0-100%)
→ Notification "Devoir envoyé !"
→ Redirection page status
```

**3. Traitement backend (invisible pour user)**
```
[Backend reçoit fichier]
→ Save DB (status: pending)
→ Return submission_id
→ Add job queue

[Worker async]
→ Update status: processing
→ Extract audio si vidéo (ffmpeg)
→ Whisper API transcription (30s)
→ GPT-4 correction (15s)
→ Save correction DB
→ Update status: completed
→ Send WeChat Template Message notification
```

**4. Consultation résultat**
```
[Temps réel]
Étudiant voit page status auto-refresh
→ "⏳ En cours..." → "🎧 Transcription..." → "✅ Terminé !"

[Notification push]
Reçoit Template Message WeChat
→ "Ton devoir a été corrigé ! Score: 82/100"
→ Clique notification → Ouvre Mini Program page détail

[Page détail]
→ Score global 82/100
→ Graphique scores détaillés
→ Points positifs / à améliorer
→ Erreurs avec corrections suggérées
→ Recommandations
→ Bouton "Voir transcription" (expand)
```

**5. Historique**
```
Étudiant clique tab "Historique"
→ Liste tous devoirs (scroll infini)
→ Filtre par status
→ Clique card → Page détail correction
```

**6. Stats**
```
Étudiant clique tab "Stats"
→ Cards stats (total, moyenne, dernier)
→ Graphique progression (line chart)
→ (Future) Badges, streaks, etc.
```

---

## ⚠️ Risques et mitigations

### 1. Review WeChat rejetée

**Risque** : Mini Program refusée lors du review initial

**Probabilité** : 15-25% (première soumission)

**Causes communes** :
- Contenu sensible (politique, pornographie)
- Fonctionnalités non déclarées
- Bugs critiques
- Manque documentation

**Mitigations** :
- ✅ **Review checklist officielle** avant submit
- ✅ **Tests exhaustifs** (zero crash)
- ✅ **Description claire** du use case éducatif
- ✅ **Screenshots** représentatifs
- ✅ **Privacy policy** si collect données
- ✅ **Soumettre en chinois** (description, textes)

**Plan B si rejet** :
- Lire raison rejet (WeChat donne feedback)
- Corriger et re-soumettre (généralement accepté round 2)
- Support WeChat développeur (réactif)

### 2. Coûts API explosent

**Risque** : Volume inattendu → facture OpenAI élevée

**Probabilité** : 10% (si pas de quotas)

**Mitigations** :
- ✅ **Hard limits** OpenAI dashboard (ex: $50/mois max)
- ✅ **Rate limiting** app : Max 3 devoirs/étudiant/semaine
- ✅ **Alertes** si coûts >$30/mois (email notification)
- ✅ **Caching** : Ne pas re-transcrire si déjà fait
- ✅ **Fallback** : Baidu STT gratuit si quota dépassé

### 3. Performance backend dégradée

**Risque** : Trop de requests simultanées → serveur crash

**Probabilité** : 20% (si traffic spike)

**Mitigations** :
- ✅ **Job queue** (Bull) : Traitement async, pas de surcharge
- ✅ **Rate limiting** API : Max 10 req/min/user
- ✅ **Auto-scaling** : VPS upgrade automatique (si cloud)
- ✅ **Monitoring** : Uptime Kuma + alerts
- ✅ **CDN** : Cloudflare pour fichiers statiques

### 4. Qualité transcription insuffisante

**Risque** : Audio bruyant/mauvaise qualité → transcription incorrecte

**Probabilité** : 15-25%

**Mitigations** :
- ✅ **Consignes claires** étudiant : Environnement calme, micro proche
- ✅ **Validation confidence** Whisper : Flag si <0.7
- ✅ **Human review** échantillon aléatoire (10%)
- ✅ **Bouton "Contester"** : Étudiant peut signaler erreur
- ✅ **Fallback** : Si très mauvais, demander re-soumission

### 5. Privacy / RGPD

**Risque** : Stockage données sensibles (voix mineurs)

**Mitigations** :
- ✅ **Consentement explicite** parents (popup première connexion)
- ✅ **Anonymisation** : OpenID only, pas de noms réels stockés
- ✅ **Encryption** fichiers sensibles (at rest + transit)
- ✅ **Rétention** : Auto-delete fichiers après 90 jours
- ✅ **Privacy policy** claire (page dédiée dans app)
- ✅ **Export données** : User peut télécharger ses données

### 6. Dépendance OpenAI

**Risque** : API OpenAI down → app inutilisable

**Probabilité** : 2-5% (rare mais possible)

**Mitigations** :
- ✅ **Retry logic** : 3 tentatives avec backoff exponentiel
- ✅ **Fallback API** : Baidu STT + Claude API (Anthropic) pour correction
- ✅ **Queue persistence** : Redis persiste jobs si serveur redémarre
- ✅ **Status page** : Afficher "Maintenance" si API down

### 7. WeChat API changes

**Risque** : WeChat modifie API → app casse

**Probabilité** : 5-10% sur 12 mois

**Mitigations** :
- ✅ **Version pinning** : Utiliser version stable SDK
- ✅ **Monitoring** WeChat changelog
- ✅ **Community** : Suivre forums développeurs WeChat
- ✅ **Testing** : CI/CD avec tests automatisés

---

## 🚀 Plan d'implémentation

### Phase 0 : Setup & Requirements (Jour 1-2)

**Objectif** : Compte développeur + environnement prêt

**Tasks** :
- [ ] Créer compte WeChat Developer (mp.weixin.qq.com)
  - Upload ID card (verification 1-3 jours)
  - Type compte : "个人" (Personnel) - Gratuit
- [ ] Télécharger WeChat DevTools (IDE officiel)
- [ ] Lire documentation officielle :
  - Mini Program guide : https://developers.weixin.qq.com/miniprogram/dev/framework/
  - API reference : https://developers.weixin.qq.com/miniprogram/dev/api/
- [ ] Setup backend :
  - VPS (Hetzner $5/mois ou Aliyun)
  - Install Node.js 18+, PostgreSQL, Redis, Nginx
  - SSL certificate (Let's Encrypt)
- [ ] Créer comptes API :
  - OpenAI account + $10 credits
  - WeChat Official Account (pour Template Messages)

**Critère succès** :
- Compte WeChat Developer vérifié
- DevTools installé + Hello World compilé
- Backend VPS accessible HTTPS

---

### Phase 1 : POC Frontend (Jour 3-4)

**Objectif** : Mini Program basique qui upload fichier

**Tasks** :
- [ ] Créer projet Mini Program (DevTools)
- [ ] Implémenter pages :
  - `index` : Home avec bouton upload
  - `upload` : Sélection fichier + upload
- [ ] Implémenter `wx.chooseMedia()` + `wx.uploadFile()`
- [ ] Mock backend (retourne success)
- [ ] Test sur simulateur + vrai device (scan QR code)

**Code minimal** :
```javascript
// pages/upload/upload.js
Page({
  uploadFile() {
    wx.chooseMedia({
      count: 1,
      mediaType: ['audio', 'video'],
      success: (res) => {
        wx.uploadFile({
          url: 'https://yourserver.com/api/homework',
          filePath: res.tempFiles[0].tempFilePath,
          name: 'file',
          success: () => {
            wx.showToast({ title: 'Envoyé !' })
          }
        })
      }
    })
  }
})
```

**Critère succès** : Upload fichier fonctionne sur vrai device

---

### Phase 2 : POC Backend (Jour 5-6)

**Objectif** : API qui reçoit fichier + transcription Whisper

**Tasks** :
- [ ] Setup Express.js + Multer (file upload)
- [ ] Endpoint `POST /api/homework`
- [ ] Intégrer Whisper API
- [ ] Return transcription au frontend
- [ ] Test end-to-end (Mini Program → Backend → Whisper)

**Code minimal** :
```javascript
// server.js
const express = require('express');
const multer = require('multer');
const whisperService = require('./services/whisper');

const app = express();
const upload = multer({ dest: 'uploads/' });

app.post('/api/homework', upload.single('file'), async (req, res) => {
  const transcription = await whisperService.transcribe(req.file.path);
  res.json({ transcription: transcription.text });
});

app.listen(3000);
```

**Critère succès** :
- Upload audio → Backend → Whisper → Return transcription
- Latence <60s

---

### Phase 3 : MVP Complet (Jour 7-10)

**Objectif** : App fonctionnelle avec correction complète

**Tasks Backend** :
- [ ] Database PostgreSQL setup (schema complet)
- [ ] JWT authentication (WeChat login)
- [ ] Job queue (Bull + Redis)
- [ ] GPT-4 correction service
- [ ] Endpoints complets (homework, stats, history)
- [ ] Template Messages WeChat (notifications)

**Tasks Frontend** :
- [ ] Page login (wx.login)
- [ ] Page upload améliorée (enregistrement natif)
- [ ] Page status (polling temps réel)
- [ ] Page détail correction (score, feedback)
- [ ] Page historique (liste devoirs)
- [ ] Page stats (graphiques basiques)

**Critère succès** :
- 1 cycle complet : Upload → Transcription → Correction → Feedback
- 5 étudiants tests utilisent pendant 3 jours
- 0 crash critique

---

### Phase 4 : Testing & Review (Jour 11-13)

**Objectif** : Tests exhaustifs + soumission WeChat review

**Tasks** :
- [ ] Tests fonctionnels :
  - Upload audio mp3 ✅
  - Upload vidéo mp4 ✅
  - Enregistrement natif ✅
  - Correction précision >80% ✅
  - Notifications push ✅
- [ ] Tests edge cases :
  - Fichier 100MB (limite)
  - Audio bruyant
  - Réseau lent/instable
  - Backend offline (error handling)
- [ ] Tests devices :
  - iPhone (iOS 14+)
  - Android (version récente)
  - WeChat versions (latest + N-1)
- [ ] Optimisations :
  - Code minification
  - Image compression
  - Lazy loading
- [ ] Documentation :
  - Privacy policy (page dédiée)
  - User guide (FAQ)
  - Screenshots app (pour review)
- [ ] Soumission WeChat review :
  - Remplir formulaire
  - Upload screenshots
  - Description claire (chinois)
  - Submit

**Critère succès** : Review passée (ou feedback reçu si rejet)

---

### Phase 5 : Production Deploy (Jour 14-15)

**Objectif** : Déploiement production stable

**Tasks** :
- [ ] Backend production :
  - PM2 setup (auto-restart)
  - Nginx reverse proxy
  - SSL certificate
  - Environment variables sécurisées
  - Logging (Winston)
  - Monitoring (Uptime Kuma)
- [ ] Database :
  - Backups automatiques (daily, S3/OSS)
  - Indexes optimisés
- [ ] Frontend :
  - Version production uploadée WeChat
  - QR code génération (pour partage étudiants)
- [ ] Documentation :
  - README technique (pour maintenance)
  - Runbook (procédures incidents)

**Critère succès** :
- App publiée WeChat (accessible via QR code)
- 95% uptime sur 48h
- 10+ étudiants utilisent sans problème

---

### Phase 6 : Onboarding Users (Jour 16+)

**Objectif** : Adoption massive étudiants

**Tasks** :
- [ ] Communication étudiants :
  - Message WeChat avec QR code
  - Video tutorial (1min)
  - FAQ (questions communes)
- [ ] Monitoring adoption :
  - Track inscriptions
  - Support réactif (questions)
- [ ] Itérations :
  - Collect feedback étudiants
  - Fix bugs critiques
  - Ajustements UX

**Critère succès** : 80%+ étudiants utilisent dans 1 semaine

---

### Timeline récapitulatif

| Phase | Durée | Cumul | Livrables |
|-------|-------|-------|-----------|
| **Phase 0** | 2j | J2 | Compte dev vérifié, VPS setup |
| **Phase 1** | 2j | J4 | Mini Program upload fichier |
| **Phase 2** | 2j | J6 | Backend + Whisper |
| **Phase 3** | 4j | J10 | MVP complet fonctionnel |
| **Phase 4** | 3j | J13 | Tests + Review soumise |
| **Phase 5** | 2j | J15 | Production déployée |
| **Phase 6** | Ongoing | J16+ | Adoption users |

**TOTAL** : **15 jours** (temps plein) ou **3-4 semaines** (part-time)

---

## 💰 Coûts

### Setup initial (one-time)

| Poste | Coût | Note |
|-------|------|------|
| **Compte WeChat Developer** | 0€ | Gratuit (type Personnel) |
| **Développement** | 0€ | DIY |
| **VPS setup** | 0€ | DIY |
| **Domaine** | 10€/an | Optionnel (peut utiliser IP) |
| **TOTAL** | **0-10€** | |

### Récurrent mensuel

| Poste | Coût mensuel | Note |
|-------|--------------|------|
| **VPS** | $5-15 | Hetzner/DigitalOcean/Aliyun |
| **Whisper API** | $3-10 | 20-50 étudiants, 2min audio moy |
| **GPT-4 API** | $5-15 | Dépend longueur feedbacks |
| **Redis Cloud** | $0-5 | Free tier OK pour <100 users |
| **Backup storage** | $1-2 | S3/R2 pour DB backups |
| **SSL certificate** | $0 | Let's Encrypt gratuit |
| **TOTAL** | **$14-47/mois** | **~12-40€/mois** |

### Scaling costs

**50 étudiants** (3 devoirs/semaine) :
- Whisper : ~$10/mois
- GPT-4 : ~$20/mois
- VPS : $15/mois (upgrade 4GB RAM)
- **Total** : ~$50/mois

**100 étudiants** :
- Whisper : ~$20/mois
- GPT-4 : ~$40/mois
- VPS : $20/mois (8GB RAM)
- **Total** : ~$85/mois

### Comparaison Bot vs Mini Program

| Coût | Bot Wechaty | Mini Program |
|------|-------------|--------------|
| **Setup** | $0 | $0 |
| **Mensuel** | $23-51 | $14-47 ✅ |
| **Puppet** | $8/mois | N/A ✅ |
| **VPS** | $5-15 | $5-15 |
| **APIs** | $10-25 | $10-25 |

→ **Mini Program ~$10/mois moins cher** (pas de Padlocal puppet)

### ROI (Return on Investment)

**Temps gagné** (20 étudiants, 3 devoirs/semaine) :
- Correction manuelle : 5min/devoir
- Correction auto : 30s/devoir
- **Gain** : 4.5min × 60 devoirs = **18h/mois**

**Coût horaire** : $30/mois ÷ 18h = **$1.67/h**

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

---

## 📋 Requirements WeChat

### 1. Compte développeur

**Type recommandé** : 个人 (Personnel)

**Avantages** :
- ✅ Gratuit
- ✅ Review rapide (1-7 jours)
- ✅ Suffisant pour usage éducatif privé

**Limitations** :
- ⚠️ Max 10 Template Messages/jour (suffisant pour <100 users)
- ⚠️ Pas de paiement WeChat Pay
- ⚠️ Pas de géolocalisation avancée

**Alternative** : 企业 (Entreprise)
- Nécessite business license chinoise
- Coût : 300 RMB/an (~40€)
- Features illimitées
→ Overkill pour ton use case

### 2. Vérification identité

**Documents requis** :
- Carte d'identité (scan recto/verso)
- Photo selfie avec ID card
- Numéro téléphone chinois (SMS verification)

**Process** :
1. Upload documents
2. Reconnaissance faciale (via WeChat app)
3. Review WeChat (1-3 jours ouvrés)
4. Notification approval

### 3. Domaine & SSL

**Requirement** : Mini Program nécessite HTTPS pour API calls

**Options** :
- **Domaine propre** : exemple.com + Let's Encrypt SSL (gratuit)
- **Cloudflare Tunnel** : Expose localhost sans domaine (gratuit)
- **Ngrok** : Dev only, pas pour production

**Whitelist** : Ajouter domaine dans settings Mini Program

### 4. ICP License (备案)

**C'est quoi** : License gouvernementale chinoise pour héberger en Chine

**Obligatoire si** :
- Serveur en Chine (Aliyun, Tencent Cloud)
- Mini Program publique (non-privée)

**Pas obligatoire si** :
- Serveur hors Chine (Hetzner, DigitalOcean)
- Mini Program privée (usage interne)

**Process** : 2-4 semaines, bureaucratique

**Recommandation** :
- Pour ton cas (usage privé) → **Pas besoin ICP**
- Héberger hors Chine (Hetzner Europe) + Cloudflare CDN

### 5. Review checklist officielle

**Avant submit, vérifier** :
- [ ] Zero crash (tests exhaustifs)
- [ ] Toutes pages fonctionnelles
- [ ] Images <500KB chacune
- [ ] No placeholder content ("Lorem ipsum")
- [ ] Privacy policy (si collect données)
- [ ] Description claire use case (chinois)
- [ ] Screenshots représentatifs (4-5 images)
- [ ] Catégorie correcte : "教育" (Education)
- [ ] No contenu illégal (politique, porno, gambling)
- [ ] Compliance : Pas de features non-déclarées

**Délai review** : 1-7 jours (généralement 2-3 jours)

**Taux acceptation** : ~75% première soumission, ~95% après corrections

---

## 🔧 Process Setup Compte WeChat Developer

### Vue d'ensemble

**Objectif** : Créer et vérifier compte WeChat Developer pour développer Mini Programs

**Durée totale** : 1-3 jours (délai approval WeChat)

**Prérequis** :
- Compte WeChat personnel actif
- Carte d'identité valide (passeport acceptable)
- Numéro téléphone chinois (ou international, selon région)
- Email valide

---

### Étape 1 : Création du compte (15 minutes)

#### 1.1 Accéder au portail développeur

**URL** : https://mp.weixin.qq.com/

**Process** :
1. Ouvre le site dans ton navigateur
2. Clique sur **"立即注册"** (S'inscrire maintenant) en haut à droite
3. Sélectionne type de compte : **"小程序"** (Mini Program)

#### 1.2 Choix du type de compte

**3 options disponibles** :

| Type | Chinois | Coût | Use Case |
|------|---------|------|----------|
| **Personnel** | 个人 | Gratuit ✅ | Usage privé/éducatif |
| **Entreprise** | 企业 | 300 RMB/an | Usage commercial |
| **Organisation** | 组织 | Gratuit | ONG, écoles |

**Pour ton projet** : Choisis **"个人" (Personnel)**

**Pourquoi Personnel est suffisant** :
- ✅ Gratuit (0€)
- ✅ Peut publier Mini Programs
- ✅ Peut utiliser API essentielles (upload, storage, notifications limitées)
- ✅ Suffisant pour <100 utilisateurs
- ⚠️ Limitations : 10 Template Messages/jour (OK pour ton usage)

#### 1.3 Remplir informations de base

**Formulaire à compléter** :

```
Email : [ton email]
→ Utilisé pour récupération compte uniquement
→ Reçois code verification email

Mot de passe : [8-20 caractères]
→ Doit contenir lettres + chiffres

Code verification : [reçu par email]
→ Valide pendant 10 minutes

☑️ J'accepte les termes et conditions
```

**Cliquer** : **"注册"** (S'inscrire)

---

### Étape 2 : Sélection sujet principal (5 minutes)

#### 2.1 Type d'entité

**Question** : 主体类型 (Type de sujet principal)

**Sélectionne** : **"个人"** (Individuel)

#### 2.2 Informations personnelles

**Formulaire** :

```
Nom complet : [Ton nom sur ID]
→ Doit correspondre EXACTEMENT à ta pièce d'identité

Type de document :
→ Sélectionne : "Passport" (si pas ID chinoise)
→ Ou : "身份证" (ID chinoise)

Numéro document : [Numéro passeport/ID]

Nationalité : [Sélectionne pays]

Téléphone : [Numéro avec code pays]
→ Format : +33 6 12 34 56 78 (France)
→ Ou : +86 138 1234 5678 (Chine)
→ Reçois SMS verification
```

**Cliquer** : **"继续"** (Continuer)

---

### Étape 3 : Vérification identité (10 minutes)

#### 3.1 Upload documents

**Documents requis** :

**Option A : Carte d'identité chinoise** (身份证)
- Photo recto (face avant)
- Photo verso (face arrière)
- Format : JPG/PNG, <2MB chacune
- Qualité : Tous les textes lisibles

**Option B : Passeport** (Recommandé si étranger)
- Photo page identité (avec photo + infos)
- Format : JPG/PNG, <2MB
- Qualité : MRZ (ligne codes en bas) lisible

**Process upload** :
1. Clique **"上传身份证正面"** (Upload recto)
2. Sélectionne fichier depuis ordinateur
3. Vérifie preview (tous textes nets ?)
4. Répète pour verso (si ID chinoise)

#### 3.2 Vérification faciale (obligatoire)

**Méthode** : Scan QR code avec WeChat app mobile

**Process** :
1. Page web affiche QR code
2. **Ouvre WeChat app** sur smartphone
3. **Scan QR code** (bouton "扫一扫" en haut droite)
4. WeChat ouvre interface vérification faciale
5. **Instructions à l'écran** :
   - Positionne visage dans cadre
   - Cligne des yeux quand demandé
   - Tourne tête gauche/droite
   - Souris (parfois demandé)
6. Vérification automatique (5-10 secondes)
7. **Message confirmation** : "验证成功" (Vérification réussie)

**Retourne à ordinateur** → Page auto-refresh

**Si échec vérification faciale** :
- Assure éclairage suffisant
- Retire lunettes/masque
- Positionne caméra à hauteur visage
- Réessaye (3 tentatives possibles)

#### 3.3 Vérification téléphone

**Process** :
1. Entre numéro téléphone (avec code pays)
2. Clique **"获取验证码"** (Obtenir code)
3. Reçois SMS avec code 6 chiffres (1-2 minutes)
4. Entre code dans champ
5. Clique **"验证"** (Vérifier)

**Code expire après 10 minutes** → Redemander si expiré

---

### Étape 4 : Informations Mini Program (5 minutes)

#### 4.1 Nom du Mini Program

**Champ** : 小程序名称 (Nom Mini Program)

**Règles** :
- 4-30 caractères
- Chinois, anglais, chiffres acceptés
- Doit être unique (pas déjà pris)
- **Peut changer 2 fois/an** (réfléchis bien)

**Suggestions pour ton projet** :
- **英语作业助手** (English Homework Assistant)
- **法语练习小程序** (French Practice Mini Program)
- **语言学习打卡** (Language Learning Check-in)

**Exemple** : Entre `语言作业助手` (Language Homework Assistant)

#### 4.2 Catégorie

**Champ** : 服务类目 (Catégorie de service)

**Sélectionne** : **"教育 > 在线教育"** (Education > Online Education)

**Autres sous-catégories possibles** :
- 教育 > 教育信息服务 (Services info éducation)
- 教育 > 培训 (Formation)

#### 4.3 Description

**Champ** : 小程序介绍 (Introduction)

**Règles** :
- 10-120 caractères
- Décrit clairement la fonction
- Pas de contenu promotionnel excessif

**Exemple** :
```
一个帮助学生提交语音/视频作业并获得AI自动批改反馈的教育工具。
适用于语言学习课程的在线作业管理。

(Un outil éducatif pour soumettre devoirs audio/vidéo et recevoir
feedback auto-corrigé par AI. Pour gestion devoirs cours de langues.)
```

#### 4.4 Logo/Icon

**Upload icon Mini Program** :

**Spécifications** :
- Format : JPG/PNG
- Taille : 1024×1024 pixels (exactement)
- Poids : <2MB
- Design : Simple, reconnaissable, pas de texte

**Recommandations** :
- Icône représentative (📚 livre, 🎓 graduation, 🎙️ micro)
- Couleurs : 2-3 couleurs max
- Éviter : Logo complexe, trop de détails

**Si pas de logo** :
- Utilise Canva (gratuit) : Template "App Icon"
- Ou générateur AI : DALL-E, Midjourney
- Ou placeholder temporaire (changeable plus tard)

---

### Étape 5 : Admin/Contact (3 minutes)

#### 5.1 Administrateur

**Champ** : 管理员信息 (Info administrateur)

**Par défaut** : Toi (créateur compte)

**Infos requises** :
- Nom complet
- WeChat ID (scan QR code pour lier)
- Email
- Téléphone

**Lier WeChat admin** :
1. Page affiche QR code
2. Scan avec WeChat app
3. Confirme "绑定" (Lier)
4. Page web auto-refresh

#### 5.2 Contact principal

**Optionnel** : Email/téléphone pour support

**Recommandation** : Utilise même email que admin

---

### Étape 6 : Submit & Review (1-3 jours)

#### 6.1 Vérification finale

**Checklist avant submit** :
- [ ] Tous champs remplis
- [ ] Documents uploaded (nets, lisibles)
- [ ] Vérification faciale passée ✅
- [ ] Téléphone vérifié ✅
- [ ] WeChat admin lié ✅
- [ ] Nom/description en chinois (recommandé)

#### 6.2 Submit application

**Cliquer** : **"提交审核"** (Soumettre pour review)

**Message confirmation** : "提交成功，请等待审核" (Soumis avec succès, attendre review)

#### 6.3 Période d'attente

**Durée** : 1-3 jours ouvrés (généralement 1-2 jours)

**Pendant ce temps** :
- Rien à faire côté utilisateur
- WeChat review automatique + manuelle
- Peut vérifier status : https://mp.weixin.qq.com/ (login)

**Notification approval** :
- **Email** : "小程序注册成功" (Mini Program enregistré avec succès)
- **WeChat message** : Notification service account officiel
- **SMS** : Sur numéro enregistré

#### 6.4 Si rejet (15-25% cas)

**Raisons communes** :
- Documents illisibles
- Nom déjà pris
- Catégorie inadaptée
- Vérification faciale échouée
- Informations incohérentes

**Process re-soumission** :
1. Login https://mp.weixin.qq.com/
2. Lire message rejet (raison indiquée)
3. Corriger éléments signalés
4. Re-soumettre (bouton "重新提交")
5. Nouveau review (1-2 jours)

**Taux acceptation round 2** : ~95%

---

### Étape 7 : Post-Approval Setup (30 minutes)

#### 7.1 First login backend

**Une fois approuvé** :

1. **Login** : https://mp.weixin.qq.com/
2. **Entre** : Email + mot de passe
3. **Scan QR** : Confirmation WeChat app
4. **Dashboard** : Page admin Mini Program

#### 7.2 Récupérer credentials

**AppID** (obligatoire pour dev) :

1. Dans dashboard, clique **"开发" > "开发管理"** (Dev > Dev Management)
2. Section **"开发设置"** (Dev Settings)
3. **AppID** : Chaîne format `wx1234567890abcdef`
4. **Copier** et sauvegarder (besoin dans WeChat DevTools)

**AppSecret** (pour backend API) :

1. Même page "开发设置"
2. Clique **"生成"** (Générer) à côté de AppSecret
3. **Scan QR** WeChat pour confirmer (sécurité)
4. **AppSecret** : Chaîne 32 caractères
5. **IMPORTANT** : Affiché une seule fois ! Copier immédiatement
6. Sauvegarder dans `.env` (ne JAMAIS commit Git)

#### 7.3 Configurer domaine serveur

**Whitelist ton backend** :

1. Clique **"开发" > "开发管理" > "服务器域名"** (Server Domain)
2. **request合法域名** : Entre `https://api.tondomaine.com`
3. **uploadFile合法域名** : Même domaine
4. **downloadFile合法域名** : Même domaine (si besoin)
5. **Cliquer** : **"保存并提交"** (Save and submit)

**Requirements domaine** :
- ✅ HTTPS obligatoire (pas HTTP)
- ✅ Certificat SSL valide
- ✅ Port 443 (HTTPS standard)
- ⚠️ IP brute pas acceptée (besoin domaine)

**Si pas de domaine** :
- **Option temporaire** : Cloudflare Tunnel (gratuit, génère domaine HTTPS)
- **Option long terme** : Acheter domaine ($10/an) + Let's Encrypt SSL (gratuit)

#### 7.4 Download WeChat DevTools

**Lien** : https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html

**Versions disponibles** :
- Windows 64-bit
- macOS
- Linux

**Installation** :
1. Download installer (~200MB)
2. Exécuter installer
3. First launch : Login avec WeChat (scan QR)
4. **Enter AppID** (récupéré step 7.2)

**First project** :
1. Clique **"创建项目"** (Create project)
2. Enter **AppID**
3. Enter project name
4. Choose directory
5. Template : **"不使用云服务"** (No cloud services)
6. Clique **"确定"** (OK)

**Simulator lancé** : Mini Program Hello World visible !

---

### Étape 8 : Verify Setup Complete (10 minutes)

#### 8.1 Checklist finale

**Vérifie que tu as** :
- [ ] Compte WeChat Developer approuvé ✅
- [ ] AppID copié et sauvegardé
- [ ] AppSecret copié et sauvegardé (.env)
- [ ] WeChat DevTools installé
- [ ] First project créé (Hello World fonctionne)
- [ ] Domaine backend configuré (ou plan pour le faire)

#### 8.2 Test basique

**Dans WeChat DevTools** :

1. Ouvre `pages/index/index.wxml`
2. Modifie texte : `<text>Hello WeChat!</text>`
3. Sauvegarde (Ctrl+S / Cmd+S)
4. **Simulator auto-refresh** → Nouveau texte visible
5. ✅ Setup fonctionnel !

#### 8.3 Next steps

**Maintenant tu peux** :
- Commencer dev Mini Program (Phase 1 du plan)
- Tester APIs WeChat (`wx.chooseMedia()`, etc.)
- Upload code vers WeChat pour tests device réel

---

### Troubleshooting

#### Problème 1 : Vérification faciale échoue

**Solutions** :
- Utilise smartphone avec bonne caméra
- Éclairage naturel (face à fenêtre)
- Retire lunettes, chapeau, masque
- Essaye autre smartphone (si caméra ancienne)
- Réessaye heures différentes (serveurs WeChat surchargés certains moments)

#### Problème 2 : Documents rejetés

**Raisons communes** :
- Photo floue → Re-scan avec meilleure résolution
- Reflets sur plastique ID → Photo en lumière diffuse
- Coins coupés → Inclure tout le document dans cadre
- Mauvais format → Convertir en JPG

#### Problème 3 : Nom Mini Program déjà pris

**Solutions** :
- Ajoute préfixe/suffixe : "小" (Xiao), "助手" (Assistant)
- Utilise combinaison unique : "Alexis语言学习"
- Check disponibilité : Search dans WeChat app avant

#### Problème 4 : Pas de numéro chinois

**Solutions** :
- Numéros internationaux acceptés (France, US, etc.)
- Format : +33 6 12 34 56 78
- Si bloqué : Demander ami chinois prêter numéro (juste pour SMS)

#### Problème 5 : Review prend >3 jours

**Actions** :
- Check spam email (notification approval parfois là)
- Login dashboard : Status visible même sans email
- Patience : Weekends/holidays rallongent délai
- Si >7 jours : Contact support WeChat (bouton dans dashboard)

---

### Support WeChat Developer

**Si problème bloquant** :

**Forum officiel** : https://developers.weixin.qq.com/community/
- Pose question en chinois (utilise DeepL)
- Community réactive (~2h response)

**Support ticket** :
1. Login dashboard
2. Clique **"客服"** (Support) en bas droite
3. Décris problème (chinois recommandé)
4. Attach screenshots
5. Response : 1-2 jours ouvrés

**WeChat officiel account support** :
- Dans WeChat app, search "微信公众平台"
- Follow account
- Send message problème
- Auto-response + escalade si besoin

---

### Timeline récapitulatif

| Étape | Durée | Cumul | Blocage ? |
|-------|-------|-------|-----------|
| Création compte | 15min | 15min | Non |
| Sélection type | 5min | 20min | Non |
| Vérification ID | 10min | 30min | Non |
| Infos Mini Program | 5min | 35min | Non |
| Admin setup | 3min | 38min | Non |
| **Submit review** | **1-3j** | **~2j** | **Oui** ⏸️ |
| Post-approval | 30min | 2j+30min | Non |
| **TOTAL** | **~2 jours** | | |

**Note** : 90% du temps = attente review (passif)

---

### Ressources utiles

**Docs officielles** :
- Guide inscription : https://developers.weixin.qq.com/miniprogram/introduction/
- FAQ : https://developers.weixin.qq.com/community/develop/question

**Vidéos tutoriels** (chinois) :
- Création compte : https://www.bilibili.com/video/BV1uh411r7zV
- Setup complet : https://www.youtube.com/watch?v=TZN0YJJx5kI

**Tools** :
- Check nom disponible : Search WeChat app
- Générateur icon : Canva, Figma
- Traduction : DeepL (meilleur que Google pour chinois)

---

## 📚 Ressources

### Documentation officielle

**WeChat Mini Program** :
- Guide officiel : https://developers.weixin.qq.com/miniprogram/dev/framework/
- API Reference : https://developers.weixin.qq.com/miniprogram/dev/api/
- Component Library : https://developers.weixin.qq.com/miniprogram/dev/component/
- DevTools : https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html

**WeChat Login & Auth** :
- wx.login() : https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html
- Backend auth : https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/user-login/code2Session.html

**File Upload** :
- wx.chooseMedia() : https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseMedia.html
- wx.uploadFile() : https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/wx.uploadFile.html

**Template Messages** :
- Guide : https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/mp-message-management/subscribe-message/sendMessage.html

### UI Frameworks

**WeUI** (officiel WeChat) :
- GitHub : https://github.com/Tencent/weui-wxss
- Demo : https://weui.io/

**Vant Weapp** (recommandé) :
- Docs : https://vant-contrib.gitee.io/vant-weapp/
- GitHub : https://github.com/youzan/vant-weapp
- Components : Button, Cell, Form, Upload, Chart, etc.

### Backend

**OpenAI API** :
- Whisper : https://platform.openai.com/docs/guides/speech-to-text
- GPT-4 : https://platform.openai.com/docs/guides/chat

**Bull (Job Queue)** :
- Docs : https://github.com/OptimalBits/bull
- Guide : https://optimalbits.github.io/bull/

**Express + Multer** :
- Express : https://expressjs.com/
- Multer : https://github.com/expressjs/multer

### Tutoriels

**Mini Program (English)** :
- Getting Started : https://dev.to/vickywane/getting-started-with-wechat-mini-programs-5b8l
- Full Course : https://www.youtube.com/watch?v=5oTjiD0gKb0

**Mini Program (Chinese)** :
- 微信小程序开发教程 : https://www.bilibili.com/video/BV1834y1676P

### Tools

**WeChat DevTools** :
- Download : https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
- MacOS, Windows, Linux supported

**Monitoring** :
- Uptime Kuma : https://github.com/louislam/uptime-kuma
- PM2 : https://pm2.keymetrics.io/

**VPS** :
- Hetzner : https://www.hetzner.com/cloud (Europe, $3.79/mois)
- DigitalOcean : https://www.digitalocean.com/ ($6/mois)
- Aliyun : https://www.alibabacloud.com/ (Chine)

### Community

**Forums** :
- WeChat Dev Community : https://developers.weixin.qq.com/community/
- Stack Overflow : Tag `wechat-miniprogram`

**GitHub Examples** :
- Awesome Mini Programs : https://github.com/justjavac/awesome-wechat-weapp
- Templates : https://github.com/wechat-miniprogram

---

## 🎯 Next Steps

### Actions immédiates (Jour 1)

1. **Validation projet** :
   - [ ] Confirmer go/no-go pour Mini Program
   - [ ] Valider budget (~$30/mois acceptable ?)
   - [ ] Timeline réaliste (15 jours full-time ou 4 semaines part-time)

2. **Setup compte** :
   - [ ] Créer compte WeChat Developer : mp.weixin.qq.com
   - [ ] Upload ID verification
   - [ ] Download WeChat DevTools

3. **Setup backend** :
   - [ ] Choisir VPS (recommandation : Hetzner $5/mois)
   - [ ] Acheter domaine (optionnel)
   - [ ] Créer compte OpenAI + ajouter $10 credits

### Questions ouvertes

**Pédagogie** :
- Quels critères correction prioritaires ? (grammaire > prononciation ?)
- Format feedback idéal ? (détaillé vs concis ?)
- Score /10, /20, ou /100 ?

**Technique** :
- Langue principale app ? (Français, Chinois, ou Bilingue ?)
- Besoin features avancées Phase 1 ? (ou juste MVP ?)
- Préférence VPS Chine vs Europe ?

**Organisation** :
- Combien de classes ? (2 pour l'instant, peut scale ?)
- Nombre étudiants total ? (pour dimensionnement VPS)
- Fréquence devoirs ? (quotidien, hebdo, mensuel ?)

### Mesures de succès

**POC (Jour 6)** :
- ✅ 1 upload → transcription fonctionne
- ✅ Latence <60s
- ✅ Précision transcription >85%

**MVP (Jour 10)** :
- ✅ Cycle complet fonctionnel
- ✅ 5 étudiants tests utilisent 3 jours
- ✅ 0 crash critique
- ✅ Feedback étudiants positif (>7/10)

**Production (Jour 15)** :
- ✅ Review WeChat passée
- ✅ App publiée (QR code accessible)
- ✅ 95% uptime
- ✅ 80%+ étudiants adoptent dans 1 semaine

**Long terme (3 mois)** :
- ✅ Temps gagné >15h/mois
- ✅ Satisfaction étudiants >8/10
- ✅ ROI <3 mois
- ✅ 0 incident critique

---

## 📝 Notes

**Créé** : 2025-11-30
**Auteur** : Alexis Trouvé
**Status** : CONCEPT → À valider avant passage WIP
**Prochaine review** : TBD après validation initiale

**Décision vs Bot Wechaty** :
- Mini Program recommandé si usage >3 mois
- Investissement initial +5 jours mais ROI long terme meilleur
- Zéro risque technique vs 5-15% risque ban bot

**Changements majeurs** :
- 2025-11-30 : Création document initial

---

**Tags** : `#wechat` `#miniprogram` `#automation` `#education` `#ai` `#stt` `#gpt4` `#openai` `#homework`