# Integração com a Amazon Alexa (Custom Skill "Nexus")

Comande o Nexus por voz: *"Alexa, peça ao Nexus para adicionar leite na lista de
compras"*, *"...criar a tarefa pagar o condomínio"*, *"...como está a casa"*,
*"...como está a rede"*.

> **Termos rápidos:**
> - **Skill** = o "app" de voz da Alexa. O nosso é um **Custom Skill** chamado *Nexus*.
> - **Endpoint** = o endereço do SEU servidor que a Alexa chama a cada comando. No
>   nosso caso é `https://SEU-DOMINIO/alexa` (já pronto no Nexus).
> - **Skill ID** = um código do tipo `amzn1.ask.skill.xxxx` que o console te dá.
>
> **O que este skill FAZ:** listas (criar / adicionar / ler / marcar), tarefas
> (criar / ler / **mover**), **status da casa**, **rede**, **clima**, **energia** e
> **pendências** (o que precisa de você). **NÃO** controla os dispositivos — isso já é
> feito pelas skills dos fabricantes (eWeLink, Tuya, Philips Hue etc.), ligadas direto
> na Alexa.
>
> Exemplos: *"...adicione leite na lista de compras"*, *"...crie a lista farmácia"*,
> *"...mova a tarefa pagar o condomínio para feito"*, *"...vai chover?"*,
> *"...como está a energia?"*, *"...o que precisa de mim?"*, *"...como está a casa?"*.

---

## Passo 1 — Criar o skill no console

1. Acesse **https://developer.amazon.com/alexa/console/ask** e faça login com a sua
   conta de desenvolvedor.
2. Clique em **Create Skill**.
3. **Skill name:** `Nexus`. **Primary locale:** **Português (BR)**.
4. Em "type of experience", escolha **Other** e depois **Custom**.
5. Em "how to host", escolha **Provision your own** (vamos usar o seu servidor, não a
   nuvem da Amazon).
6. Clique **Create skill** (pode escolher o template "Start from Scratch").

**✅ Deu certo se:** abriu o editor do skill (Build), com um menu à esquerda.

---

## Passo 2 — Nome de invocação + modelo de interação

1. No menu à esquerda, em **Invocation → Skill Invocation Name**, confirme que está
   **`nexus`** (tudo minúsculo). Salve.
2. No menu, clique em **Interaction Model → JSON Editor**.
3. Apague o conteúdo e **cole o arquivo** `deploy/alexa/interaction-model-ptBR.json`
   (deste repositório) inteiro.
4. Clique **Save Model** e depois **Build Model** (leva ~1 minuto).

**✅ Deu certo se:** o build terminou com "Full Build Successful".

**Deu problema?** Se reclamar de idioma, confirme que o locale do skill é **pt-BR**
(canto superior). O arquivo é todo em português.

---

## Passo 3 — Apontar o endpoint para o seu servidor

1. No menu, clique em **Endpoint**.
2. Escolha **HTTPS**.
3. Em **Default Region**, cole:

   ```
   https://SEU-DOMINIO/alexa
   ```

   (troque `SEU-DOMINIO` pelo domínio HTTPS do seu servidor — o mesmo do Let's Encrypt.)
4. No seletor abaixo do campo, escolha:
   **"My development endpoint has a certificate from a trusted certificate authority"**
   (o Let's Encrypt é confiável — não é auto-assinado).
5. **Save Endpoints**.

**✅ Deu certo se:** salvou sem erro.

---

## Passo 4 — Ligar no servidor (.env + módulo)

1. Copie o **Skill ID**: no menu **Endpoint** (ou na engrenagem do skill) aparece
   algo como `amzn1.ask.skill.1234abcd-...`. Copie inteiro.
2. No `C:\wamp64\www\Nexus\api\.env`, preencha:

   ```
   ALEXA_ENABLED=true
   ALEXA_SKILL_ID=amzn1.ask.skill.COLE-O-SEU-AQUI
   ```

   (O `ALEXA_VERIFY_SIGNATURE` já vem `true` — **NÃO desligue**: é o que impede
   qualquer um de comandar a casa.)
3. Confirme que o módulo **Amazon Alexa** está **ligado** em **Módulos** (`/modulos`).

**✅ Deu certo se:** salvou o `.env`. (Teste no próximo passo.)

---

## Passo 5 — Testar

**No console** (jeito mais rápido): aba **Test** (topo), mude "Off" para
**Development**, e digite/fale:

- *peça ao nexus para adicionar leite na lista de compras*
- *pergunte ao nexus como está a casa*
- *peça ao nexus para criar a tarefa pagar o condomínio*

**✅ Deu certo se:** a Alexa responde falando (ex.: *"Adicionei leite na lista
Compras."*) e o item aparece em **Listas** no Nexus.

**No aparelho Echo:** com o skill em Development, ele já funciona nos seus Echos da
mesma conta. Diga *"Alexa, abrir Nexus"* e depois o comando, ou tudo de uma vez:
*"Alexa, peça ao Nexus para..."*.

**Antes de testar no servidor**, dá para validar a lógica sem a Alexa:

```
"C:\wamp64\bin\php\php8.3.14\php.exe" "C:\wamp64\www\Nexus\api\scripts\alexa_test.php" AddListItemIntent item=leite lista=compras
"C:\wamp64\bin\php\php8.3.14\php.exe" "C:\wamp64\www\Nexus\api\scripts\alexa_test.php" HouseStatusIntent
```

---

## Deu problema?

- **"There was a problem with the requested skill's response"** no Test: o servidor
  respondeu erro. Cheque o **log do Apache** e o `logs/` do Nexus. Causas comuns:
  `ALEXA_SKILL_ID` diferente do skill (o endpoint rejeita), ou o módulo desligado.
- **A Alexa não entende o comando:** adicione mais exemplos de fala (samples) no
  JSON Editor e refaça o Build. Os valores de dispositivo/lista são flexíveis — a
  Alexa aceita além dos exemplos, mas quanto mais amostras, melhor o reconhecimento.
- **"signature" no log:** a validação da assinatura falhou. Confirme que o servidor
  tem o `cacert.pem` no `php.ini` do Apache (ver `deploy/` — mesma configuração das
  outras integrações HTTPS) e que a hora do servidor está certa (o timestamp da
  Alexa tem janela de 150 s).
- **Frases não reconhecidas / lista errada:** o Nexus casa o nome falado com o
  cadastro sem acento e por aproximação. Se tiver uma lista "Feira", diga "feira".

---

## Como funciona por dentro (para quem for mexer no código)

- **`public/alexa.php`** — recebe o POST JSON da Alexa, valida (módulo + skill ID +
  **assinatura** via `App\Alexa\AlexaVerifier` + timestamp) e roteia por
  `Web\Services\AlexaSkill`. Requisição não autenticada → não-200 (a Alexa trata como
  falha).
- **`App\Alexa\AlexaVerifier`** — validação self-contained (só `openssl`): trava a URL
  do certificado em `s3.amazonaws.com/echo.api/`, confere SAN `echo-api.amazon.com`,
  validade, cadeia de confiança e a assinatura `Signature-256` do corpo.
- **`App\Alexa\AlexaRequest`** — parser puro do JSON (intent + slots + applicationId
  + timestamp), testado por `api/scripts/tests_alexa.php`.
- **`Web\Services\AlexaSkill`** — o roteador de intents; reusa `ListaRepository`,
  `BoardRepository`, `AutomationApiService` (só leitura de status) e `NetworkService`.
- **Módulo `alexa`** no kill-switch (`/modulos`): desligado, o endpoint recusa tudo.