# 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".