Visão geral do sistema · Documentação Auto Mecânica Leme

O que é este sistema

O Auto Mecânica Leme — Sistema de Gestão é um sistema interno de operação para uma oficina mecânica. Ele organiza o atendimento em uma cadeia única e simplificada:

flowchart TB
    A["Cliente chega com o veículo"] --> B["Abertura da OS<br>(wizard em 5 passos)"]
    B --> C["Diagnóstico e tarefas<br>(mecânicos designados)"]
    C --> D{"Precisa de peça?"}
    D -- sim --> E["Solicitação → validação → pedido → recebimento"]
    E --> F["Execução das tarefas"]
    D -- não --> F
    F --> G["Pronta para entrega"]
    G --> H["Entrega / retirada do veículo"]
    H --> I["Histórico do cliente"]

Fluxo único de atendimento: tudo parte da Ordem de Serviço.

A Ordem de Serviço (OS) é o centro do domínio: ela registra a queixa do cliente, o diagnóstico técnico, as tarefas, os funcionários responsáveis, as peças necessárias, o andamento e a entrega/retirada do veículo. Todos os demais registros se relacionam com a OS quando fazem parte de um atendimento.

Regra de ouro: a OS deve ser a fonte do andamento operacional. Não criar fluxos paralelos fora dessa cadeia.

Resumo do produto

Núcleo operacional

clientes, veículos, ordens de serviço e pedidos de peças

4 perfis

admin, secretaria, mecânico-chefe e mecânico

12 status

ciclo completo da OS, de recebida a entregue

Extras

orçamentos, notificações, auditoria, backup e estoque

Tecnologias utilizadas

PHP 8 + procedural

Código em PHP puro, sem framework, com PDO para acesso ao banco.

MySQL / MariaDB

Banco relacional com schema normalizado e chaves estrangeiras.

Bootstrap 5 + CSS próprio

Design system com tema claro/escuro em css/style.css.

Lucide Icons + Turnstile

Ícones via CDN (versão fixada) e verificação anti-bot no login com Cloudflare Turnstile.

Não há framework PHP, Composer, API REST formal, camada de serviços separada nem ORM. Todo o acesso a dados usa prepared statements enviados pela conexão PDO global $conn. Exceções de banco nunca são exibidas ao usuário.

Como cada página carrega

Toda página do sistema obedece a esta sequência de inclusões, nesta ordem:

flowchart LR
    A["includes/sessao.php<br>carrega .env, sessão, login, CSRF, papéis"] --> B["config/conexao.php<br>PDO + helpers"]
    B --> C["exigir_papel()<br>autorização no backend"]
    C --> D["includes/header.php<br>HTML, CSS, JSON base/CSRF, sidebar"]
    D --> E["Conteúdo da página<br>tabelas e formulários"]
    E --> F["includes/footer.php<br>Bootstrap + main.js"]

Cadeia de carregamento de uma página PHP.

Estrutura de pastas

mecanica/
├── index.php                  # Dashboard por papel
├── .htaccess                  # Bloqueia .env, .sql, logs e pastas internas
├── README.md                  # Instalação e credenciais de teste
├── api/                       # Endpoints JSON (notificações, veículos)
├── config/
│   ├── conexao.php            # PDO + helpers
│   ├── env.php                # Leitor de .env/config.local.php
│   ├── turnstile.php          # Site key pública do Turnstile
│   ├── empresa.php            # Dados visuais da empresa
│   └── config.local.example.php  # Modelo de config local (fora do Git)
├── css/style.css              # Design system (claro/escuro + responsivo)
├── includes/
│   ├── sessao.php             # Sessão, CSRF e controle de papéis
│   ├── base_url.php           # Caminho base automático (raiz/subpasta)
│   ├── header.php             # Cabeçalho, CSS, Lucide, sidebar
│   ├── footer.php             # Scripts finais
│   ├── mensagens.php          # Mensagens flash (sucesso/erro/aviso)
│   ├── notificacoes.php       # Helpers de notificação
│   ├── auditoria.php          # Registro de auditoria
│   ├── paginacao.php          # Paginação server-side das listagens
│   ├── respostas.php          # Mensagem flash + redirect padronizados
│   └── turnstile.php          # Verificação server-side do Turnstile
├── js/main.js                 # Máscaras, wizard, áudio, notificações, filtros
├── pages/
│   ├── auth/                  # Login, logout e perfil ("Meus dados")
│   ├── clientes/              # CRUD + detalhe do cliente (histórico)
│   ├── funcionarios/          # CRUD de funcionários/usuários
│   ├── veiculos/              # CRUD de veículos
│   ├── ordens_servico/        # Criação (wizard), fila, detalhe e processamento
│   ├── pedidos_pecas/         # Solicitação, validação, pedido e recebimento
│   ├── orcamentos/            # Documento comercial + relatório
│   ├── notificacoes/          # Central de notificações
│   ├── auditoria/             # Trilha de auditoria (admin)
│   ├── backup/                # Backup do banco (admin)
│   ├── pecas/                 # Módulo legado restrito (catálogo/estoque)
│   ├── servicos/              # Módulo legado fora da navegação principal
│   └── agendamentos/          # Módulo legado fora da navegação principal
├── sql/mecanica_teste.sql     # Banco completo com dados de demonstração
└── uploads/                   # Áudios das tarefas e backups gerados

Esta documentação não faz parte do sistema: ela vive em um site estático na pasta irmã mecanica-docs/, fora do repositório, e não exige login para ser lida.

O arquivo DOCUMENTACAO_SISTEMA.md na raiz do projeto é o mesmo conteúdo desta documentação em Markdown, útil para anexar ao relatório do Projeto Integrador.