# Runbook Operacional — Banco de Talentos (Tarefa 8)

## Objetivo

Padronizar operacao e resposta a incidentes do modulo BT com:

- deploy seguro,
- rollback rapido,
- execucao de migracao,
- contingencia para indisponibilidade do SSO/identidade,
- diagnostico de filas e SQL,
- comunicacao de incidente.

---

## Escopo

Este runbook cobre o projeto `banco-de-talentos-laravel-9` e integra:

- hardening de integracoes (`docs/talent-bank/integrations-hardening.md`);
- migracao dry-run e efetiva (`migration-legacy-dry-run.md`, `migration-legacy-effective.md`);
- observabilidade (`docs/talent-bank/observability.md`).

---

## Pré-checklist de deploy

1. Branch/tag aprovado e testes relevantes verdes.
2. Backup recente de banco confirmado.
3. Variaveis de ambiente validadas (`APP_ENV`, `APP_URL`, `AUTH_SERVICE_URL`, `ANGRA_SSO_*`) e pareadas com o portal Conta Angra: no Angra, `SSO_BRIDGE_SECRET` igual a `ANGRA_SSO_SECRET` no BT; `SSO_BRIDGE_ALLOWED_ORIGINS` cobrindo todas as origens publicas do BT (`APP_URL`, https, www e sem-www se aplicavel); opcional `SSO_BRIDGE_CODE_TTL` alinhado ao contrato do bridge.
4. Janela de deploy e canal de comunicacao definidos.
5. Responsavel por rollback designado.

---

## Procedimento de deploy

### 1) Atualizar codigo

```bash
git fetch --all
git checkout <tag-ou-branch>
git pull
```

### 2) Dependencias e cache

```bash
composer install --no-dev --optimize-autoloader
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### 3) Migracoes

```bash
php artisan migrate --force
```

### 4) Reinicio de workers/fila

```bash
php artisan queue:restart
```

### 5) Smoke test minimo

- `/api/talent-bank/dashboard`
- fluxo de candidatura (`POST /api/talent-bank/job/{id}/application` em homologacao)
- fluxo de login/cadastro BT conforme ambiente

---

## Tarefa 2 - Teste ponta a ponta pos-deploy (SSO + sincronizacao)

> Objetivo: garantir que o cadastro no BT sincroniza corretamente a conta no portal Conta Angra e que o login BT via popup SSO termina com popup fechada e sessao/header corretos.

### 2.1 Cadastro de empresa nova no BT -> login no Conta Angra
1. No BT, crie uma empresa nova (rota `/cadastro/empresa` via o botao "Cadastre sua empresa pelo BT Angra" na pagina `/entrar`).
2. Use uma senha controlada (anote) para a empresa e confirme no BT.
3. Aguarde alguns segundos e/ou recarregue o BT se a tela nao confirmar imediatamente.
4. No portal Conta Angra, tente login usando:
   - CNPJ ou email da empresa; e
   - a mesma senha usada no BT.

**Criterio de aceite:**
- Login no portal Conta Angra e usuario autenticado (sem erro de credenciais).

### 2.2 Login BT via popup SSO -> popup fecha e sessao/header corretos
1. No BT, acesse a pagina `/entrar`.
2. Clique em "Acessar com Conta Angra" e permita popups no navegador.
3. Faça login no portal Conta Angra no popup.
4. Observe que o popup deve ser fechado automaticamente (a pagina `/sso/bridge` executa `window.close()` ao enviar o callback).

**Criterios de aceite (BT):**
- Ao final do fluxo, o BT redireciona para:
  - `talent-bank.company.dashboard` (quando for empresa); ou
  - `talent-bank.candidate.profile` (quando for candidato).
- A sessao no BT fica ativa:
  - a navbar mostra o usuario logado (dropdown "Area da empresa" para empresa).
- Sessao e permissoes aplicadas:
  - apos o login, paginas protegidas (ex.: `talent-bank.company.dashboard` ou `talent-bank.candidate.profile`) nao devem redirecionar para `/entrar`.
  - opcionalmente, valide `GET /auth/status` (rota `auth.status`) respondendo `authenticated: true`.

### 2.3 Quando falhar (check rapido)
- Popup bloqueado: mensagem no BT sobre popup bloqueado -> liberar popups para a origem do BT e repetir.
- Redirecionamento nao acontece: conferir timeout/erro no fluxo (mensagem em tela "Erro ao autenticar..."), e checar logs em `storage/logs/talent-bank-observability.log`.

---

## Tarefa 3 - Retroativo (empresas antes do fix AngraCompanySyncService)

> Se houver empresas cadastradas **antes** do ajuste no `AngraCompanySyncService`, pode existir gap no provisionamento no portal Conta Angra (por exemplo: falta de registros em `mysql_angra` para `users` e/ou `solicitantes_conta_empresa`).
>
> Decidir (A) rodar backfill/sync manual dessas empresas, ou (B) documentar que o comportamento vale **apenas para contas novas** a partir do deploy.

### 3.1 Diagnostico rapido (so para decidir se retroativo e necessario)
1. Escolha uma empresa antiga que esta falhando (login no portal via BT e/ou troca SSO).
2. No **portal Conta Angra** (DB `mysql_angra`), verifique:
   - tabela `users`: existe registro com `cpf` (CNPJ) e/ou `email` da empresa?
   - tabela `solicitantes_conta_empresa`: existe registro com `cnpj` e/ou `email`?

### 3.2 Opcao A — Rodar sync manual (backfill)
Quando o `users` e/ou `solicitantes_conta_empresa` estiverem incompletos.

**Como executar (operacional)**
- Rodar um backfill chamando `AngraCompanySyncService::syncToAngra(...)` para as empresas afetadas.
- Se a senha original estiver disponivel: passe `passwordHash` (para criar/ajustar login no portal).
- Se o objetivo for apenas corrigir registros de provisionamento para exchange/SSO: pode chamar sem `passwordHash` e focar em garantir `solicitantes_conta_empresa` (depende do contrato do portal para exchange).

**Criterio de aceite apos backfill**
- Login no portal Conta Angra funciona (com CNPJ ou e-mail) e o fluxo de login BT via popup SSO completa e redireciona sem cair em `/entrar`.

### 3.3 Opcao B — Documentar “só contas novas”
Quando nao houver capacidade/seguranca para backfill (tempo, risco de credenciais, indisponibilidade de senha original).

**O que documentar**
- Empresas cadastradas **antes** do deploy podem precisar:
  - de recadastro no BT com senha atual (para garantir provisionamento no portal), e/ou
  - de ajuste manual no portal (dependendo de como o exchange valida `users` e `solicitantes_conta_empresa`).
- A partir do deploy, novas empresas seguem o fluxo normal de sincronizacao.

**Criterio de aceite**
- Todas as partes envolvidas concordam com o “scope do fix”: somente novas contas ou novas + retroativo.

---

## Tarefa 4 - Qualidade (testes)

> Rodar os testes do BT após merge para reduzir risco de regressao em:
> - fluxos de login/cadastro (API);
> - contratos minimos e compatibilidade com legado.

### 4.1 Testes apos merge (mesmo filtro do CI)
Rodar a suite do BT em `Feature` (somente os testes do BT usados no CI).

Opcoes:

1. Via `php artisan test`:
   - `php artisan test --testsuite Feature --filter TalentBank`
   - ou, se o CI filtra pelos nomes:
     - `php artisan test --testsuite Feature --filter CriticalFlowsTest`
     - `php artisan test --testsuite Feature --filter ApiCompatibilityMatrixTest`

2. Via `phpunit` (diretorio especifico):
   - `./vendor/bin/phpunit --testsuite Feature tests/Feature/TalentBank`

### 4.2 Opcional: teste de integracao que toca `mysql_angra` (so em integraçao)
Se quiser uma cobertura automatizada extra para o provisionamento/sync que usa `mysql_angra`:

1. Criar um teste dedicado (ex.: `AngraCompanySyncIntegrationTest`).
2. Fazer o teste **skipar** por padrao, e rodar apenas quando estiver em ambiente de integracao (ex.: `APP_ENV=integration` ou uma flag como `BT_INTEGRATION_TESTS=1`).
3. Validar apenas invariantes seguras (ex.: o sync nao quebra e cria/atualiza registros esperados), para evitar depender de dados locais do Laragon.

**Criterio de aceite**
- Em CI/local o teste fica skipado e nao tenta acessar `mysql_angra`.
- Em pipeline de integracao (com DB do portal Angra e credenciais), o teste roda e falha se o provisionamento estiver quebrado.

---

## Tarefa 5 - Seguranca / produto

> Checklist para garantir que o bridge SSO e a politica de senha entre BT e portal estao consistentes antes de colocar em producao/homolog.

### 5.0 Logout do Conta Angra antes do popup SSO
O BT abre `GET /logout?redirect=/login?redirect=<bridge BT>`. O portal deve aceitar redirect para `/login` (mesma origem), nao apenas paths `/sso/*`. Se o logout cair na home (`/`), o popup nunca chega ao login e o SSO nao completa.

**Criterio de aceite**
- `curl -sI 'https://<angra>/logout?redirect=https%3A%2F%2F<angra>%2Flogin%3Fredirect%3D...'` retorna `Location` apontando para `/login`, nao para a home.

### 5.1 `SSO_BRIDGE_ALLOWED_ORIGINS` cobre todas as URLs publicas do BT
O bridge usa `postMessage` e o BT envia `allowedOrigin` baseado no host onde a pagina esta sendo acessada.

Verifique no portal Conta Angra:
1. `SSO_BRIDGE_ALLOWED_ORIGINS` deve conter o **scheme + host** do BT, incluindo:
   - `www` vs `sem www` (quando forem URLs publicas distintas);
   - `https` vs `http` (se ambos existirem publicamente);
   - quaisquer variacoes publicas que os usuarios usam.
2. O host precisa bater com o host real do BT, porque o BT passa como origin `request()->getSchemeAndHttpHost()` na view `/sso/bridge`.

**Criterio de aceite**
- Login SSO funciona tanto em `www` quanto em `sem www` (quando aplicavel), sem falhas/interrupcoes no callback do popup.

### 5.2 Politica de “mesma senha” entre BT e portal (o que o codigo garante hoje)
O que o codigo garante hoje esta ligado ao tipo de cadastro:

1. **Cadastro de empresa no BT sem SSO (web)**
   Em `AuthWebController::registerCompanyWithoutSso`, o sync para o portal usa:
   - `AngraCompanySyncService::syncToAngra(..., Hash::make($password))`

   Resultado: o **hash da senha no portal** e gerado a partir da **mesma senha informada no BT**.

2. **Login via popup SSO (exchange/callback)**
   Em `AuthWebController::ssoCallback`, o provisionamento para BT usa `AngraSsoProvisioningService` e sincroniza **apenas nome/e-mail** (sem atualizar hash de senha no portal via esta camada).

   Resultado: a validacao de senha nesse fluxo e responsabilidade do mecanismo do portal/SSO (bridge/exchange).

3. **Backfill/retroativo**
   `AngraCompanySyncService` so cria/ajusta credenciais no portal quando existe `passwordHash` (se vier vazio/null, registra warning e pode pular a criacao do usuario no portal).

**Criterio de aceite**
- Empresas criadas via BT sem SSO: portal aceita login usando a **mesma senha**.
- Empresas acessadas via SSO popup: o fluxo completa (autenticacao acontece no portal/SSO; o BT apenas consome o resultado via callback).

## Rollback (padrao)

> Nunca usar rollback de banco sem avaliar impacto de dados novos produzidos apos deploy.

### 1) Rollback de aplicacao

```bash
git checkout <tag-estavel-anterior>
composer install --no-dev --optimize-autoloader
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
```

### 2) Banco

- Preferir restauracao de backup consistente quando houver mudanca de schema incompatível.
- `migrate:rollback` apenas se a migracao for claramente reversivel e sem perda de dados de negocio.

### 3) Pos-rollback

- repetir smoke test;
- monitorar logs por 15-30 minutos.

---

## Migração legado → novo (operacional)

### Homolog/prod (dump SQL — 1 comando)

```bash
php artisan talent-bank:homolog-setup --force
```

Ver checklist: `docs/talent-bank/checklist-migracao-homolog.md`.

### Sequencia manual (dump ou conexão direta)

```bash
php artisan talent-bank:legacy-dry-run --report=storage/app/bt_dry_run_pre.json
php artisan talent-bank:legacy-migrate --force --sql-dump=storage/app/siati_app.sql --report=storage/app/bt_migrate.json
php artisan talent-bank:legacy-dry-run --report=storage/app/bt_dry_run_post.json
php artisan talent-bank:validate-migration
```

### Critérios de aceite operacional

- sem erros criticos no JSON de migracao;
- contagens coerentes entre legado e alvo;
- reexecucao idempotente sem duplicidade.

---

## SSO / Identidade indisponivel

### Sintomas comuns

- `401/503` em fluxos de login/cadastro;
- aumento de eventos `*.failed` no BT;
- mensagens de indisponibilidade no frontend.

### Diagnostico rapido

```bash
rg "sso\\.api|session_connection_failed|auth\\.service_unavailable" "storage/logs/laravel.log"
rg "candidate\\.login\\.failed|company\\.login\\.failed|register\\.failed" "storage/logs/talent-bank-observability.log"
```

### Acoes imediatas

1. Confirmar conectividade para `AUTH_SERVICE_URL`.
2. Validar timeout/retry do BT (`TALENT_BANK_HTTP_*`).
3. Se indisponibilidade externa confirmada:
   - registrar incidente;
   - comunicar status e ETA;
   - monitorar recuperacao.

---

## Filas (queue) — diagnóstico e recuperação

### Verificar falhas

```bash
php artisan queue:failed
```

### Reprocessar

```bash
php artisan queue:retry all
```

### Limpeza controlada (somente com aprovação operacional)

```bash
php artisan queue:flush
```

### Reiniciar workers

```bash
php artisan queue:restart
```

---

## SQL de diagnóstico (MySQL)

> Ajustar nomes de conexão/DB conforme ambiente.

### 1) Duplicidade de candidato por CPF

```sql
SELECT cpf, COUNT(*) qtd
FROM candidates
GROUP BY cpf
HAVING COUNT(*) > 1;
```

### 2) Duplicidade de empresa por CNPJ

```sql
SELECT cnpj, COUNT(*) qtd
FROM companies
GROUP BY cnpj
HAVING COUNT(*) > 1;
```

### 3) Candidaturas órfãs

```sql
SELECT jlc.*
FROM job_listing_candidate jlc
LEFT JOIN job_listings j ON j.id = jlc.job_listing_id
LEFT JOIN candidates c ON c.id = jlc.candidate_id
WHERE j.id IS NULL OR c.id IS NULL;
```

### 4) Vagas sem empresa

```sql
SELECT j.*
FROM job_listings j
LEFT JOIN companies c ON c.id = j.company_id
WHERE c.id IS NULL;
```

---

## Observabilidade e alertas (operacao)

Arquivo principal:

- `storage/logs/talent-bank-observability.log`

Consultas uteis:

```bash
rg "metric\\.http_request_latency_ms" "storage/logs/talent-bank-observability.log"
rg "job\\.application\\.(created|create_failed|deleted|delete_failed)" "storage/logs/talent-bank-observability.log"
rg "\\.failed" "storage/logs/talent-bank-observability.log"
```

Alertas sugeridos:

- pico de `*.failed` em 5 minutos;
- p95 de latencia > 1200ms em endpoints criticos;
- queda da taxa de sucesso de candidatura.

---

## Comunicação de incidente (template)

### Mensagem inicial (até 10 min)

```text
[INCIDENTE][BT] Identificado aumento de falhas no Banco de Talentos.
Impacto: <descrever fluxo afetado>.
Inicio estimado: <hora>.
Escopo: <ambiente/usuarios>.
Proxima atualizacao: <hora + 15 min>.
```

### Atualização periódica

```text
[UPDATE][BT] Status: <investigando/mitigando/monitorando>.
Causa provável: <resumo>.
Acao em andamento: <acao>.
ETA proximo update: <hora>.
```

### Encerramento

```text
[RESOLVIDO][BT] Incidente encerrado.
Causa raiz: <resumo>.
Correcao aplicada: <resumo>.
Periodo de impacto: <inicio-fim>.
Follow-up: <acao preventiva>.
```

---

## Pós-incidente

1. Registrar timeline do incidente.
2. Vincular `correlation_id` e evidencias de log.
3. Definir acao preventiva (teste, alerta, hardening, automacao).
4. Atualizar este runbook quando houver aprendizado operacional.