Bloco Serviços

O que são serviços

O bloco Servicos descreve tarefas em background — processos que rodam de forma assíncrona e não em resposta direta a uma requisição do usuário. Jobs agendados, processadores de fila, limpeza de dados, envio periódico de relatórios.

São componentes que existem no sistema mas não têm endpoint direto. Sem o bloco Servicos, a IA pode não criar esses componentes ou criá-los sem o comportamento esperado.

Servicos {
  service LimpezaDeSessoes {
    periodicidade: 24 horas
    horario: 03:00
    - Remover sessões de usuários expiradas há mais de 30 dias
    - Enviar relatório de limpeza por e-mail para o administrador
  }
}

Campos de um serviço

Campo	Descrição
`periodicidade`	Com que frequência o serviço executa. Texto livre: "1 minuto", "24 horas", "semanal".
`horario`	Horário de execução quando a periodicidade for diária. Formato HH:MM.
`ciclo-de-vida`	DI lifetime do serviço: `singleton`, `scoped`, `transient`, `hosted-service`.

Descrevendo o comportamento com instruções livres

O comportamento do serviço é descrito com instruções livres usando hífen. Cada instrução descreve uma tarefa que o serviço deve executar em cada ciclo:

Servicos {
  service ProcessarPedidosPendentes {
    periodicidade: 5 minutos
    ciclo-de-vida: hosted-service
    /// Processar em lotes de 50 para não sobrecarregar o banco
    - Buscar pedidos com status "pendente" criados há mais de 10 minutos
    - Para cada pedido, verificar disponibilidade de estoque
    - Atualizar status para "aprovado" ou "sem_estoque" conforme disponibilidade
    - Notificar cliente via e-mail sobre o status do pedido
    - Registrar resultado do processamento no log de auditoria
  }

  service RelatorioSemanal {
    periodicidade: semanal
    horario: 08:00
    - Gerar relatório de vendas da semana anterior
    - Incluir comparativo com a semana anterior
    - Enviar para lista de gestores cadastrados
    /// Enviar toda segunda-feira — o campo horario define apenas a hora
  }
}

Campo ciclo-de-vida

O campo ciclo-de-vida informa à IA qual padrão de injeção de dependência o serviço deve usar. Isso é especialmente relevante em frameworks que usam DI como .NET, Spring ou NestJS:

Valor	Comportamento	Uso típico
`singleton`	Uma instância para toda a aplicação	Cache, conexões de baixo nível
`scoped`	Uma instância por requisição/escopo	Acesso ao banco de dados
`transient`	Nova instância a cada injeção	Operações leves e sem estado
`hosted-service`	BackgroundService do host — cria scope manual	Jobs em background de longa duração

Serviço de autodestruction com ciclo-de-vida

service AutodestruicaoService {
  periodicidade: 1 minuto
  ciclo-de-vida: hosted-service
  /// BackgroundService — cria scope manual para injetar DbContext
  - Soft delete de bilhetes expirados (DestruirEm < agora)
  - Emitir evento para limpeza de arquivos associados
}

Serviços por evento

Quando o serviço não tem periodicidade fixa mas é disparado por um evento, descreva o gatilho com texto livre:

service NotificacaoPedidoAprovado {
  periodicidade: por evento — disparado quando pedido muda para "aprovado"
  ciclo-de-vida: scoped
  - Buscar dados completos do pedido e do cliente
  - Enviar e-mail de confirmação ao cliente
  - Enviar WhatsApp se o cliente tiver número cadastrado
  - Gerar nota fiscal via integração fiscal
  /// Usar fila de mensagens para garantir entrega — não disparar síncrono no request
}

service SincronizacaoEstoque {
  periodicidade: por webhook — ERP envia notificação a cada mudança de estoque
  - Validar assinatura do webhook
  - Atualizar quantidade em estoque no banco local
  - Recalcular disponibilidade de produtos afetados
  - Invalidar cache de listagem de produtos
}