# Hardening de integrações (Tarefa 2) — Banco de Talentos

## Objetivo

Reduzir estados inconsistentes e falhas silenciosas entre **sessão web**, **API de identidade** (`AUTH_SERVICE_URL`) e **SSO Conta Angra** (exchange), com **logs correlacionados** e **retry seguro** em falhas transitórias de rede.

## Fluxos cobertos

| Área | Comportamento |
|------|----------------|
| **Sessão opcional web** (`OptionalAuthSSOWeb`) | Sessões sintéticas (`__talent_bank_local_session__`, `__angra_sso_session__`) **não** chamam `/api/session`; o payload vem só de `session('sso.user_payload')`. Evita limpar a sessão ao abrir páginas públicas (ex.: detalhe de vaga). |
| **Sessão obrigatória web** (`AuthSSOWeb`) | Falha de **conexão** ao auth → redirect login com mensagem; **não** apaga sessão em timeout isolado sem resposta HTTP inválida (comportamento distinto de 401). |
| **API Sanctum/SSO** (`AuthSSO`) | `ConnectionException` → `503` JSON + log `sso.api.session_connection_failed`. |
| **AuthService** | Timeout configurável, **retry apenas em** `Illuminate\Http\Client\ConnectionException`, header `X-Correlation-ID` repassado ao auth quando o middleware definiu `correlation_id`. Proxy vazio em `AUTH_SERVICE_URL` localhost (mesma ideia do exchange SSO). |
| **Exchange SSO** (`AuthWebController::ssoCallback`) | Timeout + retry em conexão; log em falha HTTP ou conexão; header de correlação no POST. |
| **Refresh payload pós-login** | `ConnectionException` logada sem quebrar fluxo. |
| **Recuperação de senha** | Logs via `IntegrationLog` (inclui `correlation_id`). |
| **AngraCompanySyncService** | Erros com `IntegrationLog` e dados mascarados (dívida arquitetural: acesso direto a `mysql_angra` — ver `btrules`; migração futura para API). |

## Correlation ID

- Middleware `AssignCorrelationId` (grupos `web` e `api`): usa `X-Request-ID` do cliente ou gera UUID; grava em `request()->attributes['correlation_id']`; devolve o mesmo valor no header de resposta `X-Request-ID`.
- Logs centralizados em `App\Support\TalentBank\IntegrationLog` prefixam o contexto com `correlation_id` quando existir.

## Configuração (`config/talent_bank.php`)

| Chave | Env | Padrão |
|-------|-----|--------|
| `http_timeout_seconds` | `TALENT_BANK_HTTP_TIMEOUT` | 20 |
| `http_retry_times` | `TALENT_BANK_HTTP_RETRY` | 2 |
| `http_retry_sleep_ms` | `TALENT_BANK_HTTP_RETRY_MS` | 350 |

Retry **não** é aplicado a respostas HTTP 5xx com corpo válido — só a exceções de conexão, para não duplicar efeitos colaterais em `POST` sensíveis.

## Decisões técnicas

- **Compensação transacional:** cadastro web candidato/empresa já usa `DB::transaction` onde aplicável; esta tarefa não altera regras de negócio de commit.
- **Modo degradado:** em `OptionalAuthSSOWeb`, falha de `/api/session` em token real inválido continua limpando sessão (token exposto como inválido); falha de **rede** em rota opcional segue sem auth (página pública ainda carrega).

## Arquivos tocados (referência)

- `app/Http/Middleware/AssignCorrelationId.php`
- `app/Http/Middleware/OptionalAuthSSOWeb.php`, `AuthSSOWeb.php`, `AuthSSO.php`
- `app/Http/Services/AuthService.php`
- `app/Http/Controllers/Web/TalentBank/AuthWebController.php` (exchange + refresh payload)
- `app/Support/TalentBank/IntegrationLog.php`
- `app/Http/Services/TalentBank/PasswordRecoveryService.php`, `AngraCompanySyncService.php`
- `app/Http/Kernel.php`, `config/talent_bank.php`, `lang/*/auth.php`