feat: hierarquia do backlog - épicos, features, PBIs e critérios de aceitação (S1-05, S1-06, S1-07, S1-10)

[vitorpdim]

O que foi feito?

Implementa a camada de aplicação que faltava para a hierarquia do backlog (Épico → Feature →
PBI), que até então só existia como schema de banco (database/init.sql). O projeto só tinha
auth e projects implementados. Este PR fecha quatro tasks da print 1 de uma vez porque
elas são mutuamente dependentes: S1-10 (critérios) precisa de S1-05/06/07 existindo para ser
demonstrável, e por isso entram juntas neste PR.

Cada nível segue exatamente o padrão arquitetural já estabelecido pelo módulo projects: SQL
parametrizado via pg (sem ORM), validação com Zod na borda, auditoria transacional em toda
escrita, e testes com o runner nativo node:test.

Alterações técnicas

[S1-05] Épicos - API e regras de cadastro/conclusão

backend/src/modules/epics/ (novo módulo completo - types, repository, service,
controller, routes + testes de service e de rota HTTP):

• Campos do guia: titulo, descricao, objetivo, escopo_macro, resultado_esperado,
  prioridade (Must/Should/Could)
• Criação sempre resulta em status: "rascunho", mesmo com todos os campos preenchidos
  (Cenário 1 do PBI-01.1.2)
• Permite salvar rascunho com apenas o título (Cenário 2)
• PATCH /epics/:id/complete bloqueia a conclusão listando os campos faltantes
  (campos_faltantes) quando faltar qualquer um dos 5 campos do guia ou não houver nenhum
  critério de aceitação vinculado (Cenário 3 - a regra do guia inclui "critérios de aceitação"
  como campo obrigatório do épico)
• Bloqueia cadastro em projeto inexistente (404) ou arquivado (400)

frontend/src/backlog/Epics.tsx: lista de épicos do projeto, formulário de criação,
tela de detalhe com botão "Marcar como concluído" que exibe os campos faltantes em português
quando a API recusa.

[S1-06] Features - vínculo obrigatório ao épico e contexto navegável

backend/src/modules/features/ (novo módulo completo):

• Campos do guia: titulo, descricao, objetivo
• GET /features/:id sempre retorna epico_titulo e projeto_id junto — o contrato já
  resolve o Cenário 2 do PBI-01.1.3 ("exibir a qual épico ela pertence, com acesso ao épico de
  origem") sem exigir uma segunda chamada do frontend
• Bloqueia criação sem epico_id válido (400 se ausente/malformado, 404 se o épico não existir)
• Conclusão exige descricao e objetivo preenchidos

frontend/src/backlog/Features.tsx: mesmo padrão do épico, com breadcrumb "Épico: <título>"
e botão para voltar ao épico de origem.

[S1-07] PBIs - história em três campos e código provisório

backend/src/modules/pbis/ (novo módulo completo):

• História separada em historia_como_um, historia_eu_quero, historia_para_que — três
  campos de banco distintos, cada um obrigatório individualmente (não é um textarea único)
• codigo gerado automaticamente pelo sistema (PBI-001, PBI-002, ...), sequencial por
  feature - nunca aceito do cliente, satisfazendo "código provisório" do card
• GET /pbis/:id retorna a cadeia completa (feature_titulo, epico_id, epico_titulo,
  projeto_id) para navegação de contexto
• Conclusão exige ao menos um cenário de aceitação (ligação direta com S1-10)

frontend/src/backlog/Pbis.tsx: formulário com os três campos de história visualmente
distintos (cenário 2 do PBI-01.1.4), lista e detalhe com o código gerado.

[S1-10] Critérios de aceitação polimórficos

backend/src/modules/criteria/ (novo módulo, apenas Backend + Banco, sem tela própria

• por escopo do próprio card):
• Uma única tabela (criterio_aceitacao) atende épico, feature e PBI via entidade_tipo +
  entidade_id
• Épico/feature: campo texto livre. PBI: cenário nomeado com nome, dado, quando, entao
  • todos exigidos em conjunto (Cenário 2 do PBI-01.2.3: cenário incompleto é recusado)
• Novo critério sempre entra ao final da ordem existente daquela entidade (ordem persistida)
• DELETE /criteria/:id remove e reordena os demais da mesma entidade transacionalmente
  (Cenário 3 do PBI-01.2.1)
• Valida que a entidade referenciada existe antes de aceitar o critério (404 caso contrário)

database/migrations/005_backlog_hierarchy_domain.sql (novo):

• Adiciona descricao/resultado_esperado/status em epico, descricao/status em
  feature, status em pbi (todos com CHECK e DEFAULT 'rascunho', sem quebrar volumes
  existentes)
• Adiciona nome e ordem em criterio_aceitacao, CHECK de entidade_tipo, e índice único
  (entidade_tipo, entidade_id, ordem)

Ajustes transversais

• backend/src/shared/errors.ts (novo): AppError/NotFoundError/ConflictError/
  ValidationError foram movidas de projects.service.ts para um local compartilhado - o
  errorHandler global não deveria depender de um módulo de negócio específico, e os quatro
  módulos novos precisavam importar as mesmas classes.
• requireRole.ts: mensagem de 403 generalizada ("Seu perfil não permite realizar esta
  operação") em vez do texto fixo "não permite alterar projetos", já que o middleware agora é
  reusado por 4 módulos novos.
• docs/api/openapi.yaml: os 13 endpoints novos documentados (épicos, features, PBIs,
  critérios), com schemas de request/response e os códigos de erro relevantes.

Como validar

cd backend && npm run typecheck && npm test     # 95 testes (node:test)
cd frontend && npm test && npm run build         # 49 testes (vitest) + build de produção

Ambos passam tranquilamente. A migration 005 segue exatamente o padrão idempotente das migrations
002/004 (ADD COLUMN IF NOT EXISTS, DO $$ ... IF NOT EXISTS (SELECT 1 FROM pg_constraint)),
mas não pôde ser validada contra um postgres real na minha máquina (usei o windows) - pedir que o pipeline validate-seed do CI
confirme antes do merge.

A ser feito (checklist da definição, por task)
S1-05 / S1-06 / S1-07 / S1-10 (idêntico nas 4, conforme os cards):

 Critérios do PBI demonstráveis (cenários DADO/QUANDO/ENTÃO do backlog cobertos por teste)
 Testes automatizados relevantes passando
 Pull Request revisado por outra pessoa
 OpenAPI e documentação atualizadas
 Sem exposição de dados sensíveis em logs
Pendências / fora de escopo deste PR
 S1-08 (edição com aviso de não salvo + auditoria de leitura para arquivados) - depende deste PR, ainda não iniciada
 S1-11 (editores de critério no frontend) e S1-12 (reordenar cenário no frontend) - dependem de S1-10, que agora está pronta; ficam para uma próxima rodada
 S1-13 (motor de validação determinística: verbo no infinitivo, termos vagos etc.) - depende de S1-07/S1-10, agora desbloqueada
 S1-20 (aba de documentos) - continua bloqueada por S1-19 (upload), que não existe
 
cc: @LoadCG pelo sprint planning para atribuição e revisão dos critérios de aceitação.