# PRD Executável - Paridade Banco de Talentos (Novo x Legado)

## Contexto

Este backlog transforma o diagnóstico de paridade entre o módulo novo (`banco-de-talentos-laravel-9`) e o legado (`legacy/api-siati-angra` + `legacy/front_bt_angra`) em plano de execução incremental, orientado a entrega e redução de risco.

## Objetivo do produto

Garantir paridade funcional e operacional do novo Banco de Talentos, com:

- fluxos críticos completos;
- integração estável com SSO/Conta Angra;
- consistência de dados;
- cobertura mínima de testes;
- observabilidade para operação em produção.

## Métricas de sucesso

- 100% dos fluxos críticos do legado operacionais no novo.
- 0 inconsistência detectada entre cadastro local e sincronizações externas nos cenários de aceite.
- Tempo médio de diagnóstico de falha de integração < 15 min.
- Cobertura de testes dos fluxos críticos >= 80% dos cenários de negócio mapeados (não cobertura de linha).

## Escopo funcional (priorizado)

### P0 - Bloqueadores de produção

1. Recuperação de senha real (web)
2. Migração/reconciliação de dados legado -> novo
3. Hardening de integrações (SSO/Conta Angra/BT) com fallback consistente

### P1 - Qualidade de entrega

4. Compatibilidade de contratos API legado x novo
5. Testes automatizados dos fluxos críticos

### P2 - Operação contínua

6. Observabilidade e alertas operacionais do módulo BT
7. Runbook de incidentes e operação

---

## Epicos e backlog executável

## EPIC 1 - Recuperação de Senha (Paridade Funcional)

**Problema atual:** rota web de "esqueci senha" ainda é placeholder.

**Resultado esperado:** usuário recupera senha ponta a ponta com token válido, expiração e confirmação.

### Historias

- Como usuário, quero solicitar reset de senha por CPF/CNPJ+e-mail para recuperar acesso.
- Como usuário, quero redefinir senha com token válido e receber confirmação.
- Como sistema, quero bloquear abuso por rate limit e token expirado/reutilizado.

### Tarefas técnicas

- Implementar controller/service dedicado para reset no módulo web BT.
  - Arquivos alvo: `routes/web.php`, `app/Http/Controllers/Web/TalentBank/AuthWebController.php` (ou controller novo), service dedicado em `app/Http/Services/TalentBank/`.
- Reusar infraestrutura já existente de reset do ecossistema quando possível.
- Criar views de solicitação e redefinição, mantendo padrão visual atual.
  - Arquivos alvo: `resources/views/talent-bank/auth/forgot-password.blade.php` e view de reset.
- Persistência de token e invalidação após uso.
- Adicionar logs de auditoria sem vazar informação sensível.

### Critérios de aceite

- Solicitação de reset gera token válido e envio.
- Token expirado ou usado retorna mensagem controlada.
- Senha alterada permite login imediato.
- Tentativas excessivas são limitadas.

**Estimativa:** M (2-3 dias)

---

## EPIC 2 - Migração e Reconciliação de Dados

**Problema atual:** não há pipeline consolidado no app novo para migração/reconciliação.

**Resultado esperado:** processo repetível de migração com dry-run e relatório de conflitos.

### Historias

- Como time de implantação, quero migrar dados de forma rastreável.
- Como time de negócio, quero relatório de conflitos para decidir reconciliação.

### Tarefas técnicas

- Criar comandos Artisan no app novo para migração por domínio:
  - candidatos, empresas, vagas, candidaturas, catálogos.
- Implementar modo `--dry-run` e `--from-date`.
- Implementar tabela/arquivo de auditoria de migração (contagem inseridos/atualizados/ignorados).
- Regras de deduplicação:
  - candidato: CPF/e-mail
  - empresa: CNPJ/e-mail
  - vaga: chave composta (empresa + titulo + período)
- Validar integridade referencial pós-migração.

### Critérios de aceite

- Execução completa em homologação sem erro crítico.
- Relatório de reconciliação entregue com conflitos classificados.
- Reexecução idempotente não duplica registros.

**Estimativa:** G (4-6 dias)

---

## EPIC 3 - Integrações e Consistência Transacional

**Problema atual:** pontos de integração já existem, mas sem padronização total de fallback/compensação/observabilidade.

**Resultado esperado:** fluxos críticos com comportamento previsível sob falha externa.

### Historias

- Como usuário, quero concluir cadastro sem estado inconsistente mesmo com falhas externas.
- Como operação, quero identificar rapidamente em qual integração ocorreu erro.

### Tarefas técnicas

- Padronizar contrato de erro entre services de integração:
  - `LegacyApiService`, `AngraSsoProvisioningService`, serviços de sync Conta Angra/BT.
- Criar política por fluxo:
  - retry limitado para indisponibilidade transitória;
  - compensação (rollback lógico) quando necessário;
  - fallback explícito para contingência.
- Incluir correlação de logs (`request_id`, documento, origem).
- Revisar timeouts e circuit-breaker simples (contagem de falhas por janela).

### Critérios de aceite

- Cadastro candidato/empresa não deixa dados órfãos em falha de integração.
- Logs permitem rastrear fluxo completo por correlação.
- Cenários de indisponibilidade retornam mensagens de negócio adequadas.

**Estimativa:** M/G (3-5 dias)

---

## EPIC 4 - Compatibilidade de Contratos API

**Problema atual:** risco de divergência silenciosa entre payloads do legado e novo.

**Resultado esperado:** matriz de compatibilidade com endpoints críticos homologados.

### Historias

- Como consumidor de API, quero contratos previsíveis para evitar quebra no cliente.

### Tarefas técnicas

- Mapear endpoints críticos legado x novo:
  - auth/session, candidate/profile, company/session, jobs/list/show, application, report, dashboard, contact.
- Definir para cada endpoint:
  - campos obrigatórios;
  - campos opcionais;
  - diferenças aceitas (com documentação);
  - mudanças breaking (com plano).
- Criar testes de contrato (snapshot de payload essencial).

### Critérios de aceite

- Matriz de contratos publicada em `docs/`.
- Endpoints críticos com status de paridade (OK/PARCIAL/NOK).

**Estimativa:** M (2-3 dias)

---

## EPIC 5 - Testes Automatizados dos Fluxos Críticos

**Problema atual:** baixa cobertura de testes do módulo BT.

**Resultado esperado:** suíte mínima de regressão para deploy seguro.

### Historias

- Como time de engenharia, quero detectar regressões antes de produção.

### Tarefas técnicas

- Criar testes Feature para:
  - cadastro/login candidato;
  - cadastro/login empresa;
  - candidatura e cancelamento;
  - atualização de perfil/currículo;
  - relatório e dashboard;
  - contato.
- Criar testes de falha de integração (mock/fake HTTP).
- Criar fixtures/seeds mínimos dedicados ao BT.

### Critérios de aceite

- Pipeline roda testes BT em CI.
- Falhas críticas reproduzidas por teste.

**Estimativa:** G (4-6 dias)

---

## EPIC 6 - Observabilidade e Runbook Operacional

**Problema atual:** troubleshooting depende de inspeção manual extensa de logs/banco.

**Resultado esperado:** operação guiada por indicadores e procedimentos.

### Historias

- Como operação, quero detectar e responder incidentes de BT rapidamente.

### Tarefas técnicas

- Padronizar logs estruturados por evento de negócio.
- Definir KPIs operacionais:
  - taxa de cadastro concluído,
  - taxa de candidatura,
  - falha por integração,
  - latência p95 dos endpoints críticos.
- Criar runbook em `docs/`:
  - sintomas,
  - causa provável,
  - consulta SQL/log de diagnóstico,
  - ação corretiva.

### Critérios de aceite

- Runbook validado com time.
- Diagnóstico de incidentes comuns em <= 15 min.

**Estimativa:** M (2-3 dias)

---

## Plano de releases

### Release 1 (P0)

- EPIC 1 + EPIC 3 (núcleo de integração) + base do EPIC 2 (dry-run e dedupe)

### Release 2 (P1)

- EPIC 2 completo + EPIC 4 + início do EPIC 5

### Release 3 (P2)

- EPIC 5 completo + EPIC 6

---

## Dependências e riscos

- Dependência de disponibilidade/contrato dos serviços SSO/Conta Angra.
- Divergências de schema entre ambientes (local/hml/prod) podem afetar migração.
- Dados legados com qualidade heterogênea (CPF/CNPJ/e-mail inválidos/duplicados).

## Mitigações

- feature flags por fluxo crítico;
- migração com `dry-run` obrigatório antes de execução efetiva;
- rollback por release e checkpoints de banco;
- testes de contrato antes de deploy.

---

## Checklist de pronto para produção

- [x] Fluxo de recuperação de senha validado ponta a ponta — ciclo automatizado  
  Evidência: `tests/Feature/TalentBank/PasswordRecoveryE2ETest.php` cobre solicitação, anti-enumeração, validações, redefinição, respostas do serviço e ciclo completo (etapas automatizáveis).  
  Pendente homolog: recebimento real de e-mail + login com nova senha — roteiro manual em `docs/talent-bank/password-recovery.md`.
- [ ] Migração + reconciliação executada em homologação
- [ ] Testes críticos automatizados em CI
- [ ] Matriz de compatibilidade de API aprovada
- [ ] Logs estruturados + runbook publicado
- [ ] Plano de rollback revisado e testado