# Runbook operacional — Banco de Talentos

## Incidente: falha no cadastro de candidato/empresa

- **Sintoma**
  - `POST /api/talent-bank/candidate/register` ou `POST /api/talent-bank/company/register` retorna `4xx/5xx`.
  - Front exibe erro genérico no cadastro.
- **Causa provável**
  - `AUTH_SERVICE_URL` indisponível.
  - Timeout em integração de identidade.
  - Banco local inacessível ou inconsistência transacional.
- **Consulta de diagnóstico**
  - `rg "candidate\\.register\\.(failed|success)|company\\.register\\.(failed|success)" "storage/logs/talent-bank-observability.log"`
  - `rg "sso\\.api\\.session_connection_failed|auth\\.service_unavailable" "storage/logs/laravel.log"`
  - SQL:
    - `SELECT id, cpf, email, created_at FROM candidates ORDER BY id DESC LIMIT 20;`
    - `SELECT id, cnpj, email, created_at FROM companies ORDER BY id DESC LIMIT 20;`
- **Ação corretiva**
  - Validar conectividade de `AUTH_SERVICE_URL`.
  - Ajustar `TALENT_BANK_HTTP_TIMEOUT`, `TALENT_BANK_HTTP_RETRY`, `TALENT_BANK_HTTP_RETRY_MS`.
  - Reprocessar cadastro apenas após confirmar estabilidade.

## Incidente: login retorna 500

- **Sintoma**
  - Login falha com `500` em `/entrar` ou endpoints API de login.
- **Causa provável**
  - Exceção não tratada em integração de sessão.
  - Payload inválido retornado por serviço externo.
- **Consulta de diagnóstico**
  - `rg "candidate\\.login\\.failed|company\\.login\\.failed|sso\\.web|sso\\.api" "storage/logs/talent-bank-observability.log" "storage/logs/laravel.log"`
  - Correlacionar por `correlation_id`.
- **Ação corretiva**
  - Corrigir indisponibilidade do auth upstream.
  - Confirmar payload mínimo (`document`, `email`, `permissions`) no endpoint de sessão.

## Incidente: sync Conta Angra falha silenciosamente

- **Sintoma**
  - Cadastro BT concluído, mas login no portal Angra não funciona.
  - SSO popup retorna falha de provisioning.
- **Causa provável**
  - Falha em `AngraCompanySyncService` (acesso `mysql_angra`, schema divergente, credenciais).
  - `passwordHash` ausente em fluxo que exige criação de usuário no portal.
- **Consulta de diagnóstico**
  - `rg "angra_company_sync|angra_sso|exchange_http_error|exchange_connection_failed" "storage/logs/laravel.log"`
  - SQL (`mysql_angra`):
    - `SELECT id, email, cpf FROM users WHERE cpf = '<cnpj>' OR email = '<email>';`
    - `SELECT id, cnpj, email, status FROM solicitantes_conta_empresa WHERE cnpj = '<cnpj>' OR email = '<email>';`
- **Ação corretiva**
  - Revisar variáveis `ANGRA_DB_*`.
  - Executar backfill pontual via `AngraCompanySyncService::syncToAngra(...)` quando necessário.

## Incidente: integração legado timeout

- **Sintoma**
  - Comandos de migração/dry-run lentos ou com erro de conexão.
  - Falhas em serviços que dependem de legado.
- **Causa provável**
  - `mysql_legacy` indisponível.
  - Timeout de rede ou proxy no ambiente.
- **Consulta de diagnóstico**
  - `rg "legacy|connection_failed|timeout" "storage/logs/laravel.log"`
  - Testar conectividade ao host de `TALENT_BANK_LEGACY_DB_HOST`.
- **Ação corretiva**
  - Ajustar credenciais do legado e janela de execução.
  - Reexecutar dry-run antes da migração efetiva.

## Campos de diagnóstico nos logs

- `correlation_id` — rastreia uma requisição ponta a ponta.
- `document` / `document_masked` — CPF/CNPJ quando disponível.
- `http_status` — status de integrações externas.
- `error` — exceção ou erro upstream.
- Canal de logs: `TALENT_BANK_OBSERVABILITY_CHANNEL` (default: `talent_bank_observability`).

## KPIs operacionais

- **Taxa de cadastro concluído**
  - `candidate.register.success / (candidate.register.success + candidate.register.failed)` e análogo para empresa.
- **Taxa de candidatura**
  - eventos `job.application.created` vs `job.application.create_failed`.
- **Falha por integração**
  - `IntegrationLog::error` agrupado por prefixo (`angra_sso`, `angra_company_sync`, `sso.api`, etc.).
- **Latência p95**
  - `metric.http_request_latency_ms` (middleware `LogTalentBankRequestMetrics`).

## Consultas rápidas (logs)

```bash
rg "metric\\.http_request_latency_ms" "storage/logs/talent-bank-observability.log"
rg "candidate\\.(register|login)|company\\.(register|login)" "storage/logs/talent-bank-observability.log"
rg "job\\.application\\.(created|create_failed|deleted|delete_failed)" "storage/logs/talent-bank-observability.log"
rg "angra_sso|angra_company_sync|sso\\.api|sso\\.web" "storage/logs/laravel.log"
```