DeutschMeister — Agent Guide
Linee guida architetturali vincolanti, standard grafici premium, architettura vocale interattiva (Ascolto 🔊 & Microfono 🎤), regole didattiche e convenzioni di codice per sviluppatori e agenti AI.
1. I Dieci Comandamenti del Progetto
2. Architettura Vocale: Ascolto (🔊) e Microfono (🎤)
L'integrazione del riconoscimento vocale (STT) e della sintesi vocale (TTS) in tedesco (de-DE) richiede l'applicazione rigorosa di questo standard HTML:
<!-- Coppia Standard Audio & Microfono con ID Univoco Isolato -->
<div class="voice-item-row">
<div>
<strong>Ich spreche Italienisch.</strong>
<div class="vocab-italian">🇮🇹 <em>«Parlo italiano.»</em></div>
<!-- Box di feedback isolato con ID UNIVOCO -->
<div id="fb_rep_unique_01" class="row-voice-feedback"></div>
</div>
<div class="action-btn-group">
<button class="audio-btn" data-speak="Ich spreche Italienisch." title="Ascolta">🔊</button>
<button class="audio-btn mic-repeat-btn"
data-target="Ich spreche Italienisch."
data-feedback-id="fb_rep_unique_01"
title="Ripeti al microfono">🎤</button>
</div>
</div>
Non omettere mai
data-feedback-id="...". In passato, la risalita ai contenitori generici (come .grammar-card o .exercise-card) causava la scrittura del punteggio vocale sempre nella prima riga dell'intera sezione (il famigerato problema die Äpfel). Con l'ID univoco l'isolamento è al 100% garantito.
speech.js:Per parole rapide (come "mein", "Sie", "über"), Chrome emette solo trascrizioni intermedie (
isFinal = false). Il nostro motore in assets/js/speech.js cattura lastRecognizedText e normalizza le dieresi (ä ↔ ae, ö ↔ oe, ü ↔ ue, ß ↔ ss) per assegnare punteggi corretti (85-100%).
3. Demo Vocale Interattiva
4. Sistema di Autosalvataggio Locale (storage.js)
Ogni lezione importa i 3 script cardine ed esegue il binding automatico:
const LEVEL = 'A1';
const DAY = 1; // Incrementare per ogni giorno (Day 2, Day 3, ecc.)
document.addEventListener('DOMContentLoaded', () => {
// 1. Collega tutti i campi input[data-save], scelte multiple, note e stato completamento
window.courseStorage.autoBindLesson(LEVEL, DAY);
// 2. Inizializza e ripristina tutti i pulsanti vocali (.mic-repeat-btn)
window.speechEngine.initAllMicRepeatButtons(LEVEL, DAY);
});
5. Traduzioni a Fronte Obbligatorie per gli Esercizi
Inserire sempre sotto la riga dell'input la traduzione in corsivo: 🇮🇹 «Ciao, io sono Matteo.» (verbo: sein).
Ogni opzione errata deve riportare la traduzione letterale che ne chiarisce l'errore (es. «Io sono Italia e parlare Germania — Sgrammaticata»). L'opzione esatta deve avere la traduzione corretta evidenziata in verde.
Ogni chip di parola tedesca deve riportare il mini-tag italiano (es. Heute <small>(Oggi)</small>). In JavaScript, il controllo dell'ordine deve avvenire su getAttribute('data-word') per non confrontare il testo dei tag ausiliari.
6. Struttura Standard a 9 Sezioni per Ogni Giorno
| Sezione | Nome Canonico | Contenuto & Componenti Obbligatori |
|---|---|---|
| Header | App Header & Nav | Brand badge 🇩🇪, breadcrumb giorno, indicatore autosalvataggio, switch tema. |
| Hero | Lesson Hero | Badge livello/giorno, titolo in tedesco, obiettivo operativo giornaliero. |
| Sez. 1 | Fonetica / Regola Cardine | Tabelle fonetiche o articoli con 🔊 ascolto e 🎤 microfono per ogni suono. |
| Sez. 2 | Vocabolario Fondamentale | Card vocaboli con chip genere (der/die/das), traduzione, 🔊 ascolto e 🎤 voce. |
| Sez. 3 | Grammatica / Coniugazioni | Griglia bilanciata (2x2 se 4 verbi), tabelle di coniugazione, 🔊 e 🎤 per ogni riga. |
| Sez. 4 | Nazioni / Espressioni Utili | Card situazionali e frasi chiave della presentazione con 🔊 e 🎤. |
| Sez. 5 | Studio Vocale Avanzato | Box ampi dedicati alla pronuncia con dizione analitica. |
| Sez. 6 | Esercizi Interattivi | Fill-in-the-blank, scelta multipla e riordino: tutti con traduzioni, 🔊 e 🎤. |
| Sez. 7 | Assistente Conversazionale | Roleplay situazionale guidato con il Tutor AI locale (tutor.js). |
| Sez. 8 | Taccuino Personale | Textarea persistente in localStorage per gli appunti dello studente. |
7. Standard Architetturale CSS & Classi HTML (Fedeltà Assoluta a Day 1)
lesson.css
Nei Giorni dal 2 al 7 era stata introdotta una nomenclatura di classi arbitraria (es. .lesson-container, .lesson-card, .card-header-flex, .btn-voice, .voice-training-box, .exercise-box).
Poiché il foglio di stile centralizzato assets/css/lesson.css dichiara esclusivamente selettori legati a Day 1 (es. .main-wrapper, .lesson-section, .section-header, .audio-btn, .pronounce-box, .exercise-card), il browser non applicava le regole, producendo un layout sballato e privo del design premium.
Tabella di Mapping: Classi Vietate vs Classi Autorizzate Day 1
| Componente | ❌ Classe Vietata (Ad-Hoc) | ✅ Classe Canonica Day 1 | Regola CSS Applicata da lesson.css |
|---|---|---|---|
| Container Principale | <main class="lesson-container"> |
<main class="main-wrapper"> |
Centratura max-width: 1100px, padding uniforme e margini dinamici responsive. |
| Sezioni della Lezione | <section class="lesson-card"> |
<section class="lesson-section"> |
Bordo dorato/neon subtle, sfondo scuro glassmorphism, padding 2rem, margin-bottom 2.5rem. |
| Header di Sezione | .card-header-flex + .card-title |
.section-header + .section-title |
Tipografia Outfit/Inter, icona .icon proporzionata, linea divisoria o flex standard. |
| Pulsante Ascolto | <button class="btn-voice"> |
<button class="audio-btn" data-speak="..."> |
Cerchio glassmorphism dorato, hover luminescente, stato .speaking animato. |
| Pulsante Microfono | <button class="mic-repeat-btn"> |
<button class="audio-btn mic-repeat-btn" data-target="..." data-feedback-id="..."> |
Stile cerchio coordinato, pulsazione verde/rossa .listening durante la cattura. |
| Verbi e Regole 2x2 | .grammar-grid (generico) |
.verbs-2x2-grid contenente .grammar-card |
Griglia a 2 colonne su desktop (1fr 1fr), collassa a 1 colonna su tablet/mobile (≤920px). |
| Card Vocabolario | .vocab-word / .vocab-meaning |
.vocab-grid > .vocab-card (.vocab-german, .vocab-italian) |
Layout a griglia automatica (minmax 240px), badge genere .der, .die, .das. |
| Studio Pronuncia | .voice-training-box / .voice-item |
.pronounce-box (.pronounce-target, .mic-btn, .pronounce-result) |
Box centrale con testo target grande, pulsante registrazione con feedback percentuale/colori. |
| Esercizi Interattivi | .exercise-box |
.exercise-card (.exercise-question, .blank-input, .mc-options) |
Card sopraelevata, input stilizzati con evidenziazione verde/rossa immediata al click. |
| Scelte Multiple | .mc-btn / .mc-options-grid |
.mc-options > .mc-option-btn |
Griglia 2 o 3 opzioni, stati .selected-correct e .selected-wrong. |
| Sentence Builder | .chips-pool / .chip |
.word-bank > .word-chip (con <small> per traduzione) |
Chip interattivi cliccabili che si spostano tra la banca e l'area di composizione frase. |
| Taccuino Personale | #personalNotes / .notes-area |
<textarea id="lessonNotes" class="notes-textarea"> |
Textarea ad altezza fissa, font monospazio/sans leggibile, listener saveNotes() collegato. |
Ogni livello QCER (A1, A2, B1, B2, C1) si conclude tassativamente con una pagina d'esame finale (es. A1/test-a1.html).
L'esame deve comprendere:
• Score Tracker in Tempo Reale: indicatore numerico persistente fino a 100 Punti.
• 5 Moduli di Valutazione: Fonetica/Ascolto, Grammatica/Casi, Sintassi (Sentence Builder), Comprensione Situazionale e Colloquio d'Esame Orale (Mündliche Prüfung) con il Tutor AI.
• Certificato Ufficiale Dinamico: rilasciato a chi ottiene almeno 60/100, con nome modificabile, valutazione QCER (Bestanden, Gut, Sehr Gut) e funzione di stampa/salvataggio PDF (window.print()).
Struttura DOM Canonica (Copia & Incolla per Nuove Lezioni)
<!-- HEADER APP -->
<header class="app-header">
<div class="brand-container">
<a href="../index.html" class="brand-badge">🇩🇪</a>
<div><div class="brand-title">Deutsch<span>Meister</span></div></div>
</div>
<div class="save-indicator" id="saveIndicator">
<div class="save-dot"></div><span class="save-text">Autosalvato in locale</span>
</div>
<div class="nav-actions">...</div>
</header>
<!-- MAIN WRAPPER OBBLIGATORIO -->
<main class="main-wrapper">
<div class="lesson-nav-bar">
<div class="lesson-breadcrumbs">...</div>
<button id="completeLessonBtn" class="btn btn-primary">Segna come completato</button>
</div>
<section class="lesson-hero">
<span class="lesson-badge">Giorno X • Livello A1</span>
<h1 class="lesson-title">Titolo della Lezione</h1>
<p class="lesson-goal"><strong>Obiettivo:</strong> Obiettivo operativo...</p>
</section>
<!-- CARD VOCABOLARIO CANONICA (SEZIONE 2: 2 CHILD DIRETTI, FLEX ROW) -->
<div class="vocab-card">
<div style="flex: 1; min-width: 0;">
<div class="vocab-german">
<span class="gender-chip der">der</span> Morgen
</div>
<div class="vocab-phonetic">Espressione: <strong>am Morgen</strong></div>
<div class="vocab-italian">il mattino / la mattina</div>
<div style="font-size: 0.8rem; color: var(--text-muted); margin-top: 0.35rem;">💡 Nota o esempio contestuale</div>
<div id="fb_voc_1" class="row-voice-feedback"></div>
</div>
<div class="action-btn-group" style="margin-left: 1rem; align-self: flex-start;">
<button class="audio-btn" data-speak="der Morgen, am Morgen" title="Ascolta">🔊</button>
<button class="audio-btn mic-repeat-btn" data-target="am Morgen" data-feedback-id="fb_voc_1" title="Ripeti">🎤</button>
</div>
</div>
<!-- SEZIONI DA 1 A 8: TUTTE <section class="lesson-section"> -->
<section class="lesson-section" id="sezione-1">
<div class="section-header">
<h2 class="section-title"><span class="icon">🎯</span> 1. Titolo Sezione</h2>
</div>
<p style="color: var(--text-secondary); margin-bottom: 1.25rem;">Spiegazione chiara...</p>
...
</section>
</main>
8. Tutor AI Conversazionale Locale (tutor.js)
Il tutor dialoga con lo studente simulando scenari quotidiani (ordinare al bar, presentarsi a una festa, chiedere informazioni a Berlino).
In passato, il tutor avviava automaticamente la riproduzione audio al caricamento della pagina, spaventando l'utente e venendo bloccato dai browser per via dei vincoli di autoplay. L'audio deve partire solo quando l'utente clicca sul pulsante di ascolto del messaggio o attiva il microfono.
9. Regole Operative per Agenti AI & Manutentori
PowerShell su Windows interpreta male apici singoli/doppi e codepage ANSI, corrompendo gli Umlaut in caratteri sostitutivi (\uFFFD).
Procedura corretta: Scrivere sempre il codice in un file temporaneo in scratch/ ed eseguirlo con node scratch/nome_script.js.
Ogni nuovo giorno generato (es. day-03.html) deve essere validato sintatticamente con new Function(scriptContent) per garantire zero errori di runtime in console.
Avvia_Corso.bat
Il microfono richiede un contesto sicuro (http://localhost:5500 o HTTPS). Il file batch avvia automaticamente il server locale leggero senza bisogno di configurazioni esterne.