cursoitaliano/SPEC.md

Italiano Vivo — Especificação do Produto (v1)

App de italiano situacional-first, com voz livre, scoring de inteligibilidade ("errado mas entendido" conta como sucesso), treino de estratégias de comunicação (circunlóquio, pedir a palavra que falta) e modo viagem offline. Do extremo básico (A0/Pre-A1) ao avançado (C1), ancorado nos can-do statements do CEFR / ALTE Social & Tourist Can-Dos.

1. Por que este app existe (lacunas comprovadas na pesquisa)

Dor	Estado do mercado	Nossa resposta
Avaliação binária ❌/✅	Babbel/Duolingo/Speakly marcam fala correta como errada; nenhum separa precisão de sentido	Scoring em 3 eixos: Sentido transmitido / Naturalidade / Precisão gramatical. Saída padrão: "Quase lá — o italiano diria: …", nunca "Errado"
Vocabulário temático solto	Babbel começa com queijo de cabra; Duolingo prende o aluno no path	Dia 1: aluno escolhe as próprias situações-âncora ("quero pedir um lanche", "preciso reclamar do aquecedor")
Falta de estratégia quando a palavra some	Zero apps de italiano treinam circunlóquio (evidência: Coluzzi 2022; Dörnyei 1995)	Módulo dedicado "Salvavita": Come si dice…?, Può ripetere più lentamente?, descrever sem nomear. Penaliza abandonar a mensagem, não o erro
Syllabus gramatical (presente→congiuntivo)	Todos os grandes	Unidades = missões comunicativas (aeroporto, farmácia, hotel…). Gramática entra como insumo da missão, nunca como capítulo
Voz livre sem memória	Apps de IA conversacional: "no vocab list, no grammar log, no review schedule"	Conversa livre → extrai as frases que quebraram → rebuild → reaparecem espaçadas dentro de uma situação nova
Offline confiável + áudio-only	Só Pimsleur é hands-free, e 9% das reviews negativas citam offline quebrado	PWA com Service Worker + catálogo 100% local; TTS/áudio empacotados; IA só quando online, com degradação suave
ASR hostil ao aprendiz	Monossílabos ignorados, correções circulares	ASR via LLM multimodal (tolerante a sotaque) + botão "isso estava certo" que vira dado de re-treino; sensível a geminadas (pala/balla, nono/nonna)
Billing predatório	Queixa nº1 (renovação silenciosa, expiração antecipada)	Compra única por trilha ou lifetime. Sem streak-guilt, sem conteúdo removido

2. Persona e escopo

• Henrique viajante: foi à Itália, travou no balcão. Quer o básico de criança ("io voglio / io ho bisogno / mi scusi, non so come si dice") encaixado em contexto real, progredindo até conversa adulta.
• Escopo tudo: viajante + expat/burocracia (permesso, ASL, banca, affitto), porque há exigência legal objetiva (B1 cidadania CILS/CELI) e disposição a pagar por resultado mensurável.

3. Metodologia implementada (mecânica de app)

Princípio	Mecânica
Aquisição natural (como criança)	Fase 1 só áudio+imagem, sem escrita; texto desbloqueado após N exposições; produção cedo porém curta
Comprehensible input i+1	Diálogos com % de cognatos controlado pelo nível; missão seguinte libera com comprehension ≥ ~80%
Chunks / lexical approach	Unidade mínima = bloco pronto (Mi scusi, non ho capito — può ripetere più lentamente?), nunca palavra isolada
CLT / Task-Based Learning	Cada missão tem critério de sucesso comunicativo ("marque uma visita médica sem inglês"). O app avalia a meta atingida, depois expõe os gaps
Output practice (Swain)	Após conversa livre: extrair 3 frases tentadas-e-quebradas → rebuild → re-gravar → reencontrar 3 dias depois
SRS	Revisão de frases-chunks (SM-2 simplificado), reintroduzidas dentro de diálogo novo, não como flashcard morto
Shadowing	Modo carro/corrida: áudio nativo em velocidade real, gravação sobreposta, medição de lag; protocolo Arguelles (blind → transcript → read+shadow)
Estratégias de comunicação (CS)	Minijogo "descreva sem nomear" cronometrado; cartões de resgate; auto-repair pontuado positivamente
CEFR can-do	Badge = "Você agora consegue: reclamar de um item com defeito", com verificação por voz. Pre-A1 → B2/C1

4. Trilhas e missões (espinha dorsal)

Trilha Bambino (A0–A1) — núcleo da ideia: quero/não quero, tenho/preciso, gosto, dói, é grande/pequeno, mais/menos, isto/aquilo, números, sim/não/forse, e principalmente os salvavidas: come si dice…? / non capisco / ripeta piano / come si scrive? / scusi, non conosco la parola.

Trilha Viaggio (A1–B2) — aeroporto e alfândega · check-in de voo · táxi/ônibus/trem · hotel (checar, reclamar do quarto, pedir extra) · bar e restaurante (pedir, alergia, conta, gorjeta, reserva) · supermercado/padaria/lanche ("vorrei un panino con…" + descrever o que não sei o nome) · farmácia e médico (sintomas, dor, dosagem) · banco e câmbio · aluguel de carro · compras e devolução · reclamar/negociar/recusar · fazer amizade/small talk · emergência e polícia · telefone/online burocrático.

Trilha Vivere (B1–C1) — questura/permesso, ASL/sanità, SPID, comune/anagrafe, casa e landlord, scuola dei figli, lavoro, preparazione CILS/CELI B1 cittadinanza.

Cada missão = scenario com: objetivos can-do, chunks essenciais, diálogos-âncora (áudio), armadilhas reais (tu vs Lei, cortesia italiana, "magari/dai/vabbè"), role-play de voz livre, e checklist de sobrevivência offline.

5. Motor de feedback (o diferencial)

Pipeline por tentativa de fala:

1. ASR (qwen omni-flash, tolerante a sotaque) → transcrição + confusão provável.
2. Judge (qwen3.8-max) produz JSON estruturado:
   • meaning_conveyed: full | partial | failed
   • naturalness: score + versão que um italiano diria
   • grammar: erros classificados (grave=gera mal-entendido / leve / cosmético)
   • next_move: continuação do diálogo como italiano faria
   • rescue_card: se o aluno travou por falta de palavra → ensina o salvavita aplicável
3. Regra de ouro: meaning_conveyed=full ⇒ missão avança mesmo com erros graves leves; feedback sempre termina com a frase reconstruída para repetir.
4. Botão "isto estava certo" → registra dissidência (dataset futuro de calibração).

6. Arquitetura técnica

cursoitaliano/
  app/                  # PWA React+Vite+TS (IndexedDB/Dexie, Workbox SW, MediaRecorder, Web Speech playback)
    src/lib/ai.ts       # cliente OpenAI-compatible -> LiteLLM (http://10.8.0.1:4000/v1)
    src/engine/         # judge, scoring, srs, mission graph
    src/content/        # JSONs gerados (missões, chunks, diálogos, salvavidas)
  server/               # Node TS: /transcribe /judge /tts /generate-mission (cache + rate-limit + fallback chain)
  content/              # pipeline de geração (Node) -> JSON versionado no repo
  audio/                # assets TTS pré-gerados (por missão)
  SPEC.md README.md .env.example

• IA: tudo via LiteLLM local (sem custo PAYG): chat/judge qwen3.8-max, drills rápidos qwen3.8-flash, voz/ASR qwen3-omni-flash (audio base64), TTS via Edge TTS vozes it-IT-ElsaNeural/it-IT-DiegoNeural (geração em lote, pacote offline; fallback Web Speech API).
• Offline: catálogo, chunks, diálogos e áudio empacotados no build + IndexedDB; role-play de voz exige rede; phrasebook de resgate e SRS funcionam 100% offline; fila de tentativas para julgamento quando voltar a conexão.
• Segurança: chave do proxy fora do bundle — .env no server/, app fala só com o próprio server; .env no .gitignore; .env.example sem segredo.

7. MVP (o que está sendo construído agora)

1. Repo inicializado, config, scripts.
2. Conteúdo gerado: trilha Bambino completa (12 unidades) + Viaggio M1–M6 (aeroporto, táxi/trem, hotel, restaurante, bar/lanche, farmácia/médico), cada uma com can-dos, 12–20 chunks, 2 diálogos, role-play prompts, salvavidas.
3. Server com /judge (3-eixos), /transcribe (omni), /tts.
4. App PWA: home por missões, player de diálogo com áudio, cabine de voz (gravar → judge → feedback "quase lá"), minijogo "descreva sem nomear", SRS de chunks, modo resgate offline.
5. README com rodar-local, arquitetura e roadmap (trilhas restantes, shadowing mode, CILS prep, Android nativo).

8. Roadmap pós-MVP

• Missões 7–15 da trilha Viaggio + trilha Vivere inteira (geração pelo mesmo pipeline).
• Modo carro/shadowing com medição de lag, análise fonêmica de geminadas.
• Export de erro como currículo (log de interlíngua + revisão adaptativa).
• Trilha CILS/CELI B1 (cidadania) com simulado.
• Wrapper Android (Capacitor) com áudio offline por pacote.
• Calibração do judge com os votos "isto estava certo".