# Matriz de compatibilidade da API (legado x novo)

## Objetivo

Documentar o estado atual de compatibilidade dos endpoints criticos do Banco de Talentos entre:

- legado: `legacy/api-siati-angra`
- novo: `banco-de-talentos-laravel-9`

Status usados:

- `OK`: contrato funcionalmente compativel para consumo existente
- `PARCIAL`: endpoint existe, mas ha diferencas de contrato/comportamento
- `NOK`: endpoint ausente ou com quebra relevante sem fallback

## Escopo analisado

Endpoints criticos definidos no PRD:

- auth/session
- candidate/profile
- company/session
- jobs/list/show
- application
- report
- dashboard
- contact

## Matriz de status

### 1) Sessao de autenticacao (`auth/session`)

- **Legado:** `GET /api/session`
- **Novo:** `GET /api/session` (endpoint de compatibilidade — `SessionCompatibilityController`)
- **Status:** `OK`
- **Payload:** payload SSO bruto retornado pelo servico de identidade (mesmo contrato do legado)
- **Notas:** requer token SSO valido (`auth.sso` middleware). Consumidores legados nao precisam alterar chamadas.

### 2) Sessao de candidato (`candidate/profile`)

- **Legado:** `GET /api/talent-bank/candidate/session`
- **Novo:** `GET /api/talent-bank/candidate/session`
- **Status:** `OK`
- **Payload minimo:** `id`, `cpf`, `name`, `email`
- **Notas:** estrutura de recurso principal permanece; dados complementares (relacoes) continuam no payload

### 3) Sessao de empresa (`company/session`)

- **Legado:** `GET /api/talent-bank/company/session`
- **Novo:** `GET /api/talent-bank/company/session`
- **Status:** `OK`
- **Payload minimo:** `id`, `document`, `corporate_name`/`trading_name`, `email`
- **Notas:** rota e semantica mantidas

### 4) Vagas - listagem e detalhe (`jobs/list/show`)

- **Legado:** 
  - `GET /api/talent-bank/job`
  - `GET /api/talent-bank/job/{job}`
- **Novo:** 
  - `GET /api/talent-bank/job`
  - `GET /api/talent-bank/job/{job}`
- **Status:** `OK`
- **Payload minimo:** `id`, `descripton`, `is_hiring`, metadados de ocupacao/faixa salarial/contrato
- **Notas:** no novo, internamente a coluna foi normalizada para `description`, mas o recurso publico segue entregando `descripton` para compatibilidade

### 5) Candidatura (`application`)

- **Legado:**
  - `POST /api/talent-bank/job/{job}/application`
  - `DELETE /api/talent-bank/job/{job}/application`
- **Novo:**
  - `POST /api/talent-bank/job/{job}/application`
  - `DELETE /api/talent-bank/job/{job}/application`
- **Status:** `OK`
- **Payload minimo (POST):** identificacao da vaga via path + sessao autenticada de candidato
- **Notas:** fluxo de candidatura/cancelamento foi preservado

### 6) Relatorio de candidatos (`report`)

- **Legado:** `GET /api/talent-bank/report/candidate`
- **Novo:** `GET /api/talent-bank/report/candidate`
- **Status:** `OK`
- **Payload minimo:** `data.list.candidates[*].{id, cpf, name, ethnicity, neighbourhood}` + `data.counters.{total, brancos, pretos, pardos, indigenas, amarelos, feminino, masculino, outro, special_needs}`
- **Ethnicity:** legado armazenava string direta (`ethnicity`); novo usa `ethnicity_id` + relacionamento mas serializa `ethnicity?->name` — mesmo valor string no payload.
- **Filtros verificados (paridade confirmada):** `ethnicity`, `age_between`, `neighbourhoods`, `occupations` — comportamento idêntico ao legado incluindo supressão de contadores por etnia quando filtro ativo e contadores indexados por nome para bairros/ocupações.
- **Cobertura:** `tests/Feature/TalentBank/ReportParityTest.php` (14 cenários)

### 7) Dashboard (`dashboard`)

- **Legado:**
  - `GET /api/talent-bank/dashboard`
  - `GET /api/talent-bank/dashjobs`
- **Novo:**
  - `GET /api/talent-bank/dashboard`
  - `GET /api/talent-bank/dashjobs`
- **Status:** `OK`
- **Payload minimo:** contadores gerais (candidatos, vagas, empresas) e metricas de vagas
- **Notas:** rotas e intencao funcional mantidas

### 8) Fale conosco (`contact`)

- **Legado:** `POST /api/talent-bank/contact`
- **Novo:** `POST /api/talent-bank/contact`
- **Status:** `OK`
- **Payload minimo:** `name`, `email`, `phone`, `subject`, `message`
- **Notas:** contrato de entrada principal mantido

## Breaking changes consolidados

Sem breaking changes pendentes. Todos os endpoints criticos estao em status `OK`.

## Acoes recomendadas (curto prazo)

1. Congelar contrato minimo dos endpoints criticos com testes de snapshot (feature/integration).
2. Publicar exemplos oficiais de request/response para:
   - `session` (compat)
   - `candidate/session`
   - `company/session`
   - `job` list/show
   - `report/candidate`
3. Validar consumidores do legado contra os campos normalizados do novo (principalmente relatorio).

## Fonte de verdade usada nesta matriz

- `routes/api.php` (novo)
- `legacy/api-siati-angra/routes/api.php` (legado)
- `app/Http/Requests/TalentBank/*` (novo e legado)
- `app/Http/Resources/TalentBank/*` (novo e legado)
- `docs/banco-de-talentos-legado.md`