Concepts

Checklist

Inspeção registrada para um veículo. Tem status (Pending, InProgress, Completed, Reopened), odômetro, coordenadas GPS da execução, nome do motorista e fotos (gerais + CNH). Cada ChecklistItem recebe Ok, Attention ou Reproved. ChecklistTemplate/ChecklistTemplateItem definem o modelo reutilizável por ChecklistCategory. Reabertura de um checklist fechado é auditada em ChecklistReopenLog.

Finalizar um checklist é bloqueado por regras de negócio (ViolationType): item sem status, foto obrigatória faltando, observação obrigatória faltando, menos itens ou categorias do que o mínimo exigido.

Frota (Vehicle)

Veículo com status: PendingRegistration, Active, Maintenance, Attention, Sold. A transição Active ↔ Attention é automática (ver comando fleet:evaluate-attention em Commands); as demais são feitas por um humano.

Implemento (Implement) e Acoplamento (Hitch)

Implement é um equipamento acoplável ao veículo (reboque, carreta). ImplementHitch registra o acople/desacople numa posição específica, com quem acoplou/desacoplou e quando. O tipo de evento (HitchEventType) usa os valores acople/desacople em português deliberadamente — o app mobile consome esses valores como contrato fixo, então traduzir para inglês quebraria o cliente.

Filial (Branch)

Unidade organizacional dentro de uma única instância de cliente — não é multi-tenant entre clientes diferentes, é multi-filial dentro de um cliente. O middleware ResolveBranchContext resolve a filial ativa a cada request; sem uma filial ativa, a aplicação recusa a operação (NoActiveBranchException).

Papéis

Quatro roles fixos via spatie/laravel-permission: admin, fleet_manager, technician, driver. Permissões seguem o padrão resource.action (ex.: checklist.execute, vehicle.view).

Licenciamento (módulo licensing)

Camada de integração com o license-manager. ConfigLicenseGateway consulta o snapshot da licença e decide allow/deny por módulo. Dois comportamentos configuráveis por variável de ambiente:

• Fail-open (LICENSE_FAIL_OPEN, padrão true) — se o license-manager estiver indisponível, libera o acesso em vez de bloquear.
• Enforcement (LICENSE_ENFORCE) — se false ou sem credenciais configuradas, tudo é liberado. Hoje está false em produção.

O middleware EnsureModuleActive (module:<key>) é o que efetivamente bloqueia uma rota quando o módulo correspondente não está habilitado na licença.