# Recuperação de senha (Banco de Talentos — web)

## Descrição

Fluxo web para o cidadão solicitar redefinição de senha da **identidade central** (API em `AUTH_SERVICE_URL`, alinhada ao ecossistema SIATI / Conta Angra). O Banco de Talentos **não** armazena tokens de reset nem altera senha no próprio banco: apenas orquestra chamadas HTTP e exibe formulários.

## Fluxo

1. **Solicitação** (`GET/POST /esqueci-senha`)  
   - Usuário informa CPF ou CNPJ (somente dígitos após normalização) e e-mail.  
   - `POST` chama `AuthService::sendEmail` → `POST {AUTH_SERVICE_URL}/api/password/email` com `document` e `email`.  
   - **Anti-enumeração:** a resosta ao navegador é **sempre** a mesma mensagem genérica (`password_recovery.sent_generic`), independentemente de HTTP 200, 404 ou 422. Detalhes ficam em log estruturado (`talent_bank.password_recovery.send`).

2. **Nova senha** (`GET/POST /redefinir-senha`)  
   - Usuário informa o **código** recebido por e-mail (até 6 caracteres, conforme contrato legado) e a nova senha + confirmação.  
   - `POST` chama `AuthService::resetPassword` → `POST {AUTH_SERVICE_URL}/api/password/reset` com `code`, `new_password`, `new_password_confirmation`.  
   - Sucesso (`HTTP 200`): redireciona para `/entrar` com mensagem de sucesso.  
   - `422`: erros de validação repassados ao formulário.  
   - Outros erros: mensagem genérica amigável.

3. **Portal Conta Angra**  
   - Link opcional na tela de solicitação, configurável por `ANGRA_SSO_FORGOT_PASSWORD_URL` ou derivado de `ANGRA_SSO_LOGIN_URL` (padrão: mesma origem, rota `/esqueceu-senha`).

## Integrações

| Destino | Uso |
|---------|-----|
| `AUTH_SERVICE_URL` | `/api/password/email`, `/api/password/reset` (via `App\Http\Services\AuthService`) |
| Portal Angra (opcional) | URL pública de recuperação para quem gerencia a conta apenas no portal |

## Decisões técnicas

- **Sem token na URL:** critério de segurança institucional; o código trafega só no `POST` do segundo passo.  
- **Throttle:** middleware `throttle:password-recovery` (5 requisições por minuto por IP), definido em `RouteServiceProvider`.  
- **Regras de senha:** espelham o validador do legado (`api-siati-angra` / `AuthController::resetPassword`).  
- **Documentação obrigatória (btrules):** este arquivo cumpre o requisito de documentação por módulo/funcionalidade.

## Arquivos principais

- `App\Http\Controllers\Web\TalentBank\PasswordResetWebController`  
- `App\Http\Services\TalentBank\PasswordRecoveryService`  
- `App\Http\Requests\TalentBank\ForgotPasswordWebRequest`, `ResetPasswordWebRequest`  
- `resources/views/talent-bank/auth/forgot-password.blade.php`, `reset-password.blade.php`  
- `lang/{pt_BR,en}/password_recovery.php`, `lang/{pt_BR,en}/flash.php`  
- `routes/web.php` (grupo `throttle:password-recovery`)

## Variáveis de ambiente

- `AUTH_SERVICE_URL`, `APP_ID` — já usados pelo login/cadastro.  
- `ANGRA_SSO_FORGOT_PASSWORD_URL` (opcional) — sobrescreve URL do link “portal Conta Angra”.  
- `ANGRA_SSO_LOGIN_URL` — usado para derivar a URL de recuperação quando `ANGRA_SSO_FORGOT_PASSWORD_URL` estiver vazio.

## Testes automatizados

Arquivo: `tests/Feature/TalentBank/PasswordRecoveryE2ETest.php`

Cenarios cobertos (todos com `Http::fake()` sobre `AUTH_SERVICE_URL`):

| Cenario | O que verifica |
|---------|----------------|
| Renderizacao das paginas | GET /esqueci-senha e /redefinir-senha retornam 200 |
| Validacao de formulario (etapa 1) | CPF/CNPJ e e-mail obrigatorios; formato documento; e-mail valido; aceita CNPJ |
| Anti-enumeracao (etapa 1) | Mensagem sempre generica independente do status do servico (200/404/422) |
| Validacao de formulario (etapa 2) | Codigo obrigatorio; formato 6 alfanum; senha precisa letra+numero; chars proibidos; confirmacao |
| Integracao servico (etapa 2) | 200 → redirect /entrar com success; 422 → back com erros; 503 → back com mensagem generica |
| **Ciclo completo E2E** | `test_full_recovery_cycle_send_then_reset_redirects_to_login` — solicitacao → redefinicao → redirect /entrar + verifica que ambas as chamadas ao servico ocorreram |

A etapa "receber e-mail e capturar codigo" nao e automatizavel; ela e coberta pelo roteiro manual abaixo.

## Roteiro manual em homologacao

Pre-condicoes:

1. Ambiente homolog com `AUTH_SERVICE_URL` apontando para o servico de identidade correto.
2. E-mail de teste acessivel (para receber codigo).
3. Usuario de teste conhecido (CPF/CNPJ + e-mail).
4. Rotas web publicadas:
   - `GET/POST /esqueci-senha`
   - `GET/POST /redefinir-senha`
5. Sem bloqueio de rate limit no IP de quem executa o teste.

Passos:

1. Acessar `/esqueci-senha`.
2. Enviar CPF/CNPJ e e-mail validos do usuario de teste.
3. Confirmar retorno de mensagem generica de envio (anti-enumeracao).
4. Abrir e-mail recebido e capturar codigo de recuperacao.
5. Acessar `/redefinir-senha`.
6. Informar codigo + nova senha + confirmacao.
7. Confirmar redirecionamento para `/entrar` com mensagem de sucesso.
8. Fazer login em `/entrar` com a nova senha.
9. Confirmar que a senha antiga deixa de autenticar.

Evidencias minimas (anexar ao ticket/PR):

- Screenshot da tela de sucesso em `/redefinir-senha`.
- Registro do horario de recebimento do e-mail com codigo.
- Screenshot/login bem-sucedido com nova senha.
- (Opcional) tentativa de login com senha antiga falhando.
- Trechos de log com correlacao: `talent_bank.password_recovery.send` e `talent_bank.password_recovery.reset`.

## Criterios de aceite

- [x] Solicitacao de recuperacao conclui sem erro tecnico visivel — coberto por `PasswordRecoveryE2ETest`
- [x] Comportamento anti-enumeracao validado — coberto por `PasswordRecoveryE2ETest`
- [x] Validacao de formularios (documento, e-mail, codigo, senha) — coberto por `PasswordRecoveryE2ETest`
- [x] Redefinicao conclui com redirecionamento para `/entrar` — coberto por `PasswordRecoveryE2ETest`
- [x] Servico indisponivel retorna mensagem amigavel sem stack trace — coberto por `PasswordRecoveryE2ETest`
- [ ] Codigo recebido por e-mail permite redefinir senha em homolog — **requer execucao manual** (roteiro acima)
- [ ] Login com nova senha funciona imediatamente em homolog — **requer execucao manual**
- [ ] Login com senha antiga falha em homolog — **requer execucao manual**