# Task 014 — `PADRAO_INTEGRACAO.md`

**Depende de:** 013
**Bloqueia:** nada

## Objetivo

Guia para outros sinais consumirem o módulo OTP. Inclui um exemplo end-to-end (alteração de senha por e-mail) — apenas como ilustração documental, sem implementar.

## Deliverable

`componentes/Missoes/Mensageria/sinais/Otp/PADRAO_INTEGRACAO.md` com seções:

1. **Quando usar este módulo** — qualquer fluxo que precise validar identidade/intenção via código one-time.
2. **Fluxo padrão de integração**
   1. Definir um `contexto` único (ex.: `alteracao_senha`).
   2. Registrar `OtpConfig` (validade, max_tentativas, canal_padrao) no bootstrap do sinal consumidor.
   3. Implementar `OtpEventoBase` se houver side-effect pós-validação.
   4. Registrar evento via `OtpEventoRegistry::registrar($contexto, $eventoClass)`.
   5. Chamar `OtpSatelite` com `'criar_e_enviar'`, `'validar'`, `'cancelar'` conforme o fluxo.
3. **Exemplo: alteração de senha por e-mail** (esqueleto comentado, não implementado):
   ```php
   // No bootstrap do AlteracaoSenha:
   OtpConfig::registrar('alteracao_senha', [
       'validade_segundos' => 600,
       'max_tentativas'    => 3,
       'tamanho_codigo'    => 6,
       'canal_padrao'      => 'email',
   ]);
   OtpEventoRegistry::registrar('alteracao_senha', AlteracaoSenhaOtpEvento::class);

   // Quando usuário clica "Quero trocar senha":
   $resp = (new OtpSatelite($galaxia, 'criar_e_enviar', [
       'contexto'           => 'alteracao_senha',
       'referencia_externa' => $usuarioId,
       'destinatario'       => $usuario->email,
       'dados_adicionais'   => ['solicitado_em' => date('c')],
   ]))->response;

   // Quando usuário envia o código + nova senha:
   $resp = (new OtpSatelite($galaxia, 'validar', [
       'contexto'           => 'alteracao_senha',
       'referencia_externa' => $usuarioId,
       'codigo'             => $request['codigo'],
   ]))->response;
   if ($resp['notification_class'] === 'success') {
       // AlteracaoSenhaOtpEvento::aoValidar já chamou — internamente ele alterou a senha.
       // Aqui só responder ao front.
   }
   ```
4. **Códigos de erro retornados em `validar`** — tabela com `motivo` → significado → ação sugerida ao front.
5. **Lista de canais disponíveis** — atualizada conforme providers forem implementados.
6. **Convenções para nomear `contexto`** — snake_case, ≤50 chars, único globalmente.
7. **Onde NÃO usar este módulo** — fluxos que precisam de auth de longo prazo (sessão, JWT), 2FA contínuo, hardware key.
8. **Limitações conhecidas (v1)** — sem rate-limit por IP/usuário (apenas por OTP), sem retry automático em falha de envio, sem suporte a múltiplos eventos por contexto.

## Critério de aceite

- Doc compreensível por dev que não conhece o módulo.
- Exemplo do `alteracao_senha` é apenas ilustrativo — deixa claro que não está implementado.