🇩🇪
DeutschMeister
Agent Guide • Disciplinare Ufficiale
Documento Ufficiale di Riferimento • Settembre 2026

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

Principi cardine immutabili da rispettare per qualsiasi livello o lezione
Comandamento I
100% Gratuito & Offline-Ready
Nessuna API o abbonamento a pagamento. Si usano unicamente le Web API native del browser (Web Speech, AudioContext, localStorage).
Comandamento II
Design System Premium Dark
Sfondo profondo (#0b0f17), superfici elevate (#131b2e), accenti oro (#f59e0b) e smeraldo (#10b981), bordi sottili e glow al neon.
Comandamento III
Griglie Sempre Bilanciate
Vietate le asimmetrie visive. 4 elementi vanno disposti 2 in alto e 2 in basso (griglia 2x2), mai 3 in alto e 1 isolato sotto.
Comandamento IV
Regola Aurea: 🔊 Ascolto ➔ 🎤 Voce
Ogni volta che c'è l'icona dell'ascolto (🔊), DEVE esserci affiancato il microfono (🎤) per permettere all'utente di ripetere a voce alta.
Comandamento V
Traduzioni a Fronte Obbligatorie
Tutti gli esercizi della Sezione 6 devono riportare la traduzione italiana a supporto per garantire la piena comprensione contestuale.
Comandamento VI
Autosalvataggio Totale e Istantaneo
Input, scelte multiple, parole riordinate, appunti e punteggi vocali del microfono vengono persistiti in localStorage in tempo reale.
Comandamento VII
Nessun Autoplay Invasivo
All'apertura della pagina nessun audio deve partire in automatico: la voce parte solo su click intenzionale dell'utente.
Comandamento VIII
UTF-8 Puro Senza Corruzioni
Umlaut nativi (ä, ö, ü, ß) ed emoji sempre preservati. Vietati script inline da PowerShell che possano generare caratteri corrotti.
Comandamento IX
Isolamento Stagno dei Selettori
Ogni pulsante microfono punta al proprio box con data-feedback-id univoco per evitare che la voce finisca nella riga sbagliata.
Comandamento X
Tutor AI Conversazionale Locale
Ogni lezione culmina con un roleplay guidato contestualizzato all'argomento del giorno tramite assets/js/tutor.js.
🎙️

2. Architettura Vocale: Ascolto (🔊) e Microfono (🎤)

Struttura HTML obbligatoria, isolamento degli ID e gestione delle parole brevi

L'integrazione del riconoscimento vocale (STT) e della sintesi vocale (TTS) in tedesco (de-DE) richiede l'applicazione rigorosa di questo standard HTML:

HTML Standard
<!-- 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>
⚠️
Regola Fondamentale degli ID di Feedback:
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.
💡
Gestione Monosillabi e Parole Brevi in 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

Testa direttamente qui la coppia audio/microfono e l'algoritmo di similarità
Ich lerne Deutsch mit DeutschMeister.
🇮🇹 «Sto imparando il tedesco con DeutschMeister.»
💾

4. Sistema di Autosalvataggio Locale (storage.js)

Zero perdita dati: binding automatico e persistenza cross-sessione

Ogni lezione importa i 3 script cardine ed esegue il binding automatico:

JavaScript Inizializzazione
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

Ogni esercizio deve fornire il contesto italiano per agevolare l'apprendimento
1. Fill-in-the-Blank:

Inserire sempre sotto la riga dell'input la traduzione in corsivo: 🇮🇹 «Ciao, io sono Matteo.» (verbo: sein).

2. Scelta Multipla:

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.

3. Sentence Reordering (Word Bank):

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

Lo scheletro canonico immutabile da A1-Day 01 a C1-Day 30
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)

Divieto assoluto di classi ad-hoc: mappa completa dei selettori validi da lesson.css
⚠️ La Causa Tecnica del Disallineamento (Post-Mortem):

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.
🏆 Lo Standard per l'Esame Finale di Livello (Abschlusstest):

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)

Pratica di conversazione situazionale senza costi né dipendenze cloud

Il tutor dialoga con lo studente simulando scenari quotidiani (ordinare al bar, presentarsi a una festa, chiedere informazioni a Berlino).

🔇
Vincolo di Non-Autoplay:
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

Istruzioni tecniche per prevenire corruzioni di codifica e bug su Windows
1. Vietato usare PowerShell inline con stringhe complesse o caratteri speciali

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.

2. Verifica Sintattica Obbligatoria prima di Rilasciare

Ogni nuovo giorno generato (es. day-03.html) deve essere validato sintatticamente con new Function(scriptContent) per garantire zero errori di runtime in console.

3. Avviare sempre tramite 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.

‹ Torna alla Dashboard
DeutschMeister • Agent Guide per la Continuità e lo Sviluppo del Progetto
Apri A1 - Giorno 1 ➔