Pular para o conteúdo principal

Feature: Modo de Manutenção

Introdução ao documento​

Este documento descreve a funcionalidade de controle de modo de manutenção do sistema.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Visão geral​

A feature de modo de manutenção permite ativar/desativar diferentes modos de manutenção do sistema, exibindo páginas customizadas para usuários quando o sistema está em manutenção. Suporta múltiplos modos de manutenção identificados por slug, mas apenas um pode estar ativo por vez.

Atores envolvidos​

  • Administrador Geral: Cria, edita e gerencia modos de manutenção
  • Usuários: Visualizam página de manutenção quando sistema está em modo de manutenção
  • Sistema: Aplica middleware para redirecionar usuários durante manutenção

Pré-condições​

  • Permissão Administração_Geral para gerenciar modos de manutenção
  • Tabela maintenance_modes criada e acessível
  • Middleware RedirectIfMaintenanceModeActive configurado nas rotas

Fluxo principal​

Criação de Modo de Manutenção​

  1. Administrador acessa interface

    • Acessa /admin/manutencao (requer permissão Administração_Geral)
    • Visualiza lista de modos de manutenção existentes

  2. Criação de novo modo

    • Preenche formulário com título, mensagem e descrição
    • Sistema valida dados (título único, tamanhos máximos)
    • Gera slug automaticamente a partir do título (uppercase, caracteres especiais substituídos por _)

  3. Persistência

    • Modo é criado com active = false (inativo por padrão)
    • Slug deve ser único no sistema
    • Dados são salvos na tabela maintenance_modes

Ativação de Modo de Manutenção​

  1. Seleção de modo

    • Administrador seleciona modo de manutenção para ativar
    • Sistema desativa todos os modos existentes
    • Ativa apenas o modo selecionado

  2. Aplicação do modo

    • Middleware RedirectIfMaintenanceModeActive verifica se há modo ativo
    • Se ativo, redireciona usuários para /manutencao
    • Página de manutenção exibe título, mensagem e descrição do modo ativo

  3. Desativação

    • Administrador pode desativar enviando slug = "disabled"
    • Todos os modos são desativados
    • Sistema volta ao funcionamento normal

Fluxos alternativos​

Múltiplos modos (apenas um ativo)​

  • Sistema garante que apenas um modo pode estar ativo por vez
  • Ao ativar um modo, todos os outros são automaticamente desativados
  • Evita conflitos e confusão sobre qual mensagem exibir

Modo não encontrado​

  • Se slug fornecido não existe, sistema retorna erro
  • Modo não é ativado
  • Sistema permanece no estado anterior

Validação de título duplicado​

  • Título deve ser único na tabela
  • Se duplicado, sistema retorna erro de validação
  • Administrador deve escolher título diferente

Acesso durante manutenção​

  • Usuários são redirecionados para página de manutenção
  • Apenas administradores com permissão adequada podem acessar sistema
  • API pode continuar funcionando (dependendo da configuração do middleware)

Regras de negócio​

  1. Apenas um modo ativo: Sistema permite apenas um modo de manutenção ativo por vez
  2. Slug único: Slug gerado automaticamente deve ser único
  3. Título único: Título deve ser único na tabela
  4. Geração de slug: Slug é gerado automaticamente: uppercase, caracteres especiais substituídos por _
  5. Inativo por padrão: Novos modos são criados com active = false
  6. Middleware aplicado: Middleware verifica modo ativo em rotas web e API (quando configurado)

Estados possíveis​

  • Inativo: Nenhum modo de manutenção ativo, sistema operacional
  • Ativo: Modo de manutenção ativo, usuários redirecionados
  • Criado mas inativo: Modo existe mas não está ativo
  • Erro: Falha na criação/ativação de modo

Endpoints envolvidos​

Admin Panel (requer permissão)​

  • GET /admin/manutencao - Lista modos de manutenção
  • POST /admin/maintenance-mode/create - Cria novo modo
  • PUT /admin/maintenance-mode/update/{id} - Atualiza modo existente
  • POST /admin/maintenance-mode/toggle/{slug} - Ativa/desativa modo
  • DELETE /admin/maintenance-mode/delete/{id} - Remove modo

Página pública​

  • GET /manutencao - Página de manutenção exibida aos usuários

Dados afetados​

  • Tabela maintenance_modes: Armazena modos de manutenção
    • Campos: id, title, message, description, slug, active, created_at, updated_at
    • Relacionamento: Nenhum (tabela independente)

Middleware relacionado​

  • RedirectIfMaintenanceModeActive: Verifica se modo de manutenção está ativo
    • Aplicado em rotas web e API (quando configurado)
    • Redireciona para /manutencao se modo ativo