🚚 Sistema de Gerenciamento de Entregas - Gás e Água

Sistema completo para gerenciamento de entregas de gás e água com notificações automáticas via WhatsApp.

📋 Índice

Sobre o Projeto
Tecnologias
Pré-requisitos
Instalação e Configuração
Como Rodar o Projeto
Como Usar
Estrutura do Projeto
API Endpoints
Troubleshooting

🎯 Sobre o Projeto

Sistema web completo para gerenciar entregas de botijões de gás e galões de água, com:

✅ Gestão de Clientes - Cadastro completo com padrão de consumo
✅ Gestão de Produtos - Controle de estoque e preços
✅ Gestão de Pedidos - Criação e acompanhamento de entregas
✅ Notificações WhatsApp - Confirmações automáticas de pedidos e entregas
✅ Lembretes Inteligentes - Sistema automático baseado no padrão de consumo
✅ Dashboard - Visão geral do negócio em tempo real
✅ Autenticação JWT - Sistema seguro de login

🛠️ Tecnologias

Backend

Python 3.11+
FastAPI - Framework web moderno e rápido
PostgreSQL - Banco de dados relacional
SQLAlchemy - ORM
Alembic - Migrações de banco
JWT - Autenticação
APScheduler - Agendador de tarefas

Frontend

React 18 - Biblioteca JavaScript
TypeScript - Tipagem estática
Vite - Build tool
TailwindCSS - Framework CSS
Axios - Cliente HTTP
React Router - Roteamento
React Hook Form - Formulários

📦 Pré-requisitos

Antes de começar, você precisa ter instalado:

Obrigatórios:

Python 3.11 ou superior - Download
Node.js 18 ou superior - Download
PostgreSQL 15 ou superior - Download
Git - Download

Opcional:

pgAdmin - Interface gráfica para PostgreSQL
Postman - Testar API endpoints

Verificar Instalações:

# Python
python --version
# Deve mostrar: Python 3.11.x ou superior

# Node.js
node --version
# Deve mostrar: v18.x.x ou superior

# PostgreSQL
psql --version
# Deve mostrar: psql (PostgreSQL) 15.x ou superior

# Git
git --version
# Deve mostrar: git version 2.x.x

🚀 Instalação e Configuração

Passo 1: Clone o Repositório

git clone https://github.com/seu-usuario/delivery-system.git
cd delivery-system

Passo 2: Configure o Backend

2.1 - Entre na pasta do backend:

cd backend

2.2 - Crie o ambiente virtual Python:

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

Windows (CMD):

python -m venv venv
venv\Scripts\activate.bat

Mac/Linux:

python3 -m venv venv
source venv/bin/activate

✅ Você verá (venv) no início da linha do terminal

2.3 - Instale as dependências:

pip install -r requirements.txt

⏱️ Isso pode levar alguns minutos...

2.4 - Configure o PostgreSQL:

Opção A - Via psql (Terminal):

psql -U postgres
CREATE DATABASE delivery_db;
\q

Opção B - Via pgAdmin:

Abra o pgAdmin
Clique com botão direito em "Databases"
Create → Database
Nome: delivery_db
Save

2.5 - Configure as variáveis de ambiente:

Crie um arquivo .env na pasta backend/:

# Windows (PowerShell)
Copy-Item .env.example .env

# Mac/Linux
cp .env.example .env

Edite o arquivo .env com suas configurações:

# Database (IMPORTANTE: ajuste usuário e senha)
DATABASE_URL=postgresql://postgres:SUA_SENHA_AQUI@localhost:5432/delivery_db

# JWT (gere uma chave forte)
SECRET_KEY=sua-chave-secreta-super-forte-aqui
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# WhatsApp API (opcional por enquanto)
WHATSAPP_API_URL=https://waba.360dialog.io/v1/messages
WHATSAPP_API_TOKEN=seu-token-aqui
WHATSAPP_PHONE_NUMBER_ID=seu-id-aqui

# Application
APP_NAME=Delivery Management System
DEBUG=True
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Scheduler
SCHEDULER_ENABLED=True
REMINDER_CHECK_HOUR=9
REMINDER_CHECK_MINUTE=0

🔐 Gerar SECRET_KEY forte:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Copie o resultado e cole no .env no campo SECRET_KEY

2.6 - Execute as migrações do banco:

alembic upgrade head

✅ Se aparecer "Running upgrade ... -> ..., OK!" está correto!

Passo 3: Configure o Frontend

3.1 - Abra um NOVO terminal e entre na pasta frontend:

cd frontend

⚠️ IMPORTANTE: Não feche o terminal do backend!

3.2 - Instale as dependências:

npm install

⏱️ Isso pode levar alguns minutos...

3.3 - Configure as variáveis de ambiente:

Crie um arquivo .env na pasta frontend/:

# Windows (PowerShell)
Copy-Item .env.example .env

# Mac/Linux
cp .env.example .env

Edite o arquivo .env:

VITE_API_URL=http://localhost:8000/api/v1

▶️ Como Rodar o Projeto

Terminal 1 - Backend (FastAPI)

# 1. Entre na pasta backend
cd backend

# 2. Ative o ambiente virtual
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# Mac/Linux:
source venv/bin/activate

# 3. Inicie o servidor
uvicorn app.main:app --reload

✅ Você deve ver:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

🌐 Backend rodando em: http://localhost:8000
📚 Documentação API: http://localhost:8000/docs

Terminal 2 - Frontend (React)

# 1. Entre na pasta frontend
cd frontend

# 2. Inicie o servidor de desenvolvimento
npm run dev

✅ Você deve ver:

VITE v5.0.8  ready in 1234 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

🌐 Frontend rodando em: http://localhost:5173

🎮 Como Usar

1. Acesse o Sistema

Abra seu navegador e acesse: http://localhost:5173

Você verá a tela de login.

2. Crie o Primeiro Usuário

Como ainda não há usuários no sistema, você precisa criar um:

Opção A - Via Swagger (Recomendado):

Acesse: http://localhost:8000/docs
Procure por POST /api/v1/auth/register
Clique em "Try it out"
Preencha o JSON:

{
  "email": "admin@empresa.com",
  "full_name": "Administrador",
  "password": "senha123"
}

Clique em "Execute"
Se retornar 201 Created, usuário criado com sucesso! ✅

Opção B - Via cURL:

curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@empresa.com",
    "full_name": "Administrador",
    "password": "senha123"
  }'

3. Faça Login

Volte para: http://localhost:5173
Digite:
- Email: admin@empresa.com
- Senha: senha123
Clique em "Entrar"

✅ Você será redirecionado para o Dashboard!

4. Explore o Sistema

📊 Dashboard

Visualize estatísticas gerais
Veja pedidos recentes
Monitore o status das entregas

👥 Clientes

Clique em "Clientes" no menu lateral
Clique em "Novo Cliente"
Preencha:
- Nome: João Silva
- Telefone: 27999999999
- Endereço: Rua das Flores, 123, Vila Velha - ES
- Padrão de consumo: 30 dias
Clique em "Criar"

📦 Produtos

Clique em "Produtos"
Clique em "Novo Produto"
Preencha:
- Nome: Botijão de Gás P13
- Descrição: Botijão de gás 13kg
- Tipo: Gás
- Preço: 110.00
- Estoque: 50
- Status: Ativo
Clique em "Criar"

🛒 Pedidos

Clique em "Pedidos"
Clique em "Novo Pedido"
Selecione o cliente criado
Clique em "+ Adicionar Item"
Selecione o produto e quantidade
Adicione observações (opcional)
Clique em "Criar Pedido"

✅ Pedido criado! WhatsApp enviado automaticamente! 🎉

✔️ Concluir Entrega

No pedido criado, clique em "Iniciar Entrega"
Status muda para "Em Entrega"
Clique em "Concluir Entrega"
Status muda para "Concluído"
WhatsApp de confirmação enviado! 📱

📁 Estrutura do Projeto

delivery-system/
│
├── backend/                      # Backend FastAPI
│   ├── app/
│   │   ├── api/                  # Endpoints da API
│   │   │   └── v1/
│   │   │       ├── auth.py       # Login/Registro
│   │   │       ├── customers.py  # CRUD Clientes
│   │   │       ├── products.py   # CRUD Produtos
│   │   │       ├── orders.py     # CRUD Pedidos
│   │   │       └── users.py      # Usuários
│   │   ├── core/                 # Configurações
│   │   │   ├── config.py         # Variáveis ambiente
│   │   │   ├── database.py       # Conexão DB
│   │   │   └── security.py       # JWT/Auth
│   │   ├── models/               # Modelos ORM
│   │   │   ├── user.py
│   │   │   ├── customer.py
│   │   │   ├── product.py
│   │   │   └── order.py
│   │   ├── schemas/              # Schemas Pydantic
│   │   │   ├── user.py
│   │   │   ├── customer.py
│   │   │   ├── product.py
│   │   │   └── order.py
│   │   ├── services/             # Lógica de negócio
│   │   │   ├── whatsapp.py       # WhatsApp API
│   │   │   ├── orders.py         # Regras pedidos
│   │   │   └── notifications.py  # Lembretes
│   │   ├── utils/                # Utilitários
│   │   │   └── scheduler.py      # Agendador
│   │   └── main.py               # App principal
│   ├── migrations/               # Alembic
│   ├── tests/                    # Testes
│   ├── .env                      # Variáveis (criar)
│   ├── .env.example              # Exemplo
│   ├── requirements.txt          # Dependências Python
│   └── alembic.ini               # Config Alembic
│
├── frontend/                     # Frontend React
│   ├── src/
│   │   ├── components/           # Componentes
│   │   │   ├── Layout.tsx
│   │   │   ├── Navbar.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   ├── Modal.tsx
│   │   │   ├── OrderCard.tsx
│   │   │   └── Loading.tsx
│   │   ├── context/              # Context API
│   │   │   └── AuthContext.tsx   # Autenticação
│   │   ├── hooks/                # Custom Hooks
│   │   │   └── useAuth.ts
│   │   ├── pages/                # Páginas
│   │   │   ├── Login.tsx
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Customers.tsx
│   │   │   ├── Products.tsx
│   │   │   └── Orders.tsx
│   │   ├── services/             # API Services
│   │   │   ├── api.ts            # Axios config
│   │   │   ├── auth.ts
│   │   │   ├── customers.ts
│   │   │   ├── products.ts
│   │   │   └── orders.ts
│   │   ├── types/                # TypeScript types
│   │   │   └── index.ts
│   │   ├── utils/                # Utilitários
│   │   │   └── formatters.ts
│   │   ├── App.tsx               # App principal
│   │   ├── main.tsx              # Entry point
│   │   └── index.css             # Estilos globais
│   ├── public/                   # Assets estáticos
│   ├── .env                      # Variáveis (criar)
│   ├── .env.example              # Exemplo
│   ├── package.json              # Dependências Node
│   ├── tsconfig.json             # Config TypeScript
│   ├── vite.config.ts            # Config Vite
│   └── tailwind.config.js        # Config Tailwind
│
├── README.md                     # Este arquivo
├── INTEGRATION_GUIDE.md          # Guia integração
├── TEST_CONNECTION.md            # Testes
└── .gitignore                    # Git ignore

📡 API Endpoints

Autenticação

POST /api/v1/auth/register - Registrar usuário
POST /api/v1/auth/login - Login
GET /api/v1/users/me - Dados do usuário atual

Clientes

GET /api/v1/customers/ - Listar clientes
POST /api/v1/customers/ - Criar cliente
GET /api/v1/customers/{id} - Buscar cliente
PUT /api/v1/customers/{id} - Atualizar cliente
DELETE /api/v1/customers/{id} - Excluir cliente

Produtos

GET /api/v1/products/ - Listar produtos
POST /api/v1/products/ - Criar produto
GET /api/v1/products/{id} - Buscar produto
PUT /api/v1/products/{id} - Atualizar produto
DELETE /api/v1/products/{id} - Excluir produto

Pedidos

GET /api/v1/orders/ - Listar pedidos
POST /api/v1/orders/ - Criar pedido (envia WhatsApp)
GET /api/v1/orders/{id} - Buscar pedido
PUT /api/v1/orders/{id} - Atualizar pedido
POST /api/v1/orders/{id}/complete - Concluir (envia WhatsApp)
GET /api/v1/orders/customer/{id}/history - Histórico

📚 Documentação interativa: http://localhost:8000/docs

🐛 Troubleshooting

❌ Backend não inicia

Erro: "ModuleNotFoundError"

cd backend
pip install -r requirements.txt

Erro: "Database connection failed"

# Verifique se PostgreSQL está rodando
# Windows:
Get-Service postgresql*

# Mac/Linux:
ps aux | grep postgres

# Verifique o .env
# DATABASE_URL deve estar correto

Erro: "Address already in use"

# Mude a porta
uvicorn app.main:app --reload --port 8001

❌ Frontend não inicia

Erro: "Cannot find module"

cd frontend
rm -rf node_modules package-lock.json
npm install

Erro: "EACCES: permission denied"

# Windows (execute PowerShell como Administrador)
# Mac/Linux:
sudo npm install

Erro: "Port 5173 already in use"

# Vite usa outra porta automaticamente (3000, 5174, etc)

❌ Login não funciona

Erro: "Network Error"

Verifique se backend está rodando: http://localhost:8000/docs
Verifique VITE_API_URL no frontend/.env

Erro: "401 Unauthorized"

Verifique email e senha
Registre usuário novamente via Swagger

Erro: "CORS Error"

# backend/.env
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

❌ WhatsApp não envia

WhatsApp precisa de configuração adicional:

Crie conta em 360Dialog
Obtenha API Token e Phone Number ID
Atualize backend/.env:

WHATSAPP_API_URL=https://waba.360dialog.io/v1/messages
WHATSAPP_API_TOKEN=seu-token-real
WHATSAPP_PHONE_NUMBER_ID=seu-id-real

Reinicie o backend

⚠️ Sem configuração, pedidos funcionam mas WhatsApp não envia

📞 Suporte

Problemas? Siga estes passos:

Verifique os logs:
- Backend: Terminal onde rodou uvicorn
- Frontend: Console do navegador (F12)
Teste endpoints:
- http://localhost:8000/health
- http://localhost:8000/docs
Verifique arquivos .env:
- backend/.env existe e está configurado?
- frontend/.env existe e está configurado?
Consulte documentação:
- INTEGRATION_GUIDE.md
- TEST_CONNECTION.md

🎉 Pronto para Produção?

Consulte DEPLOY.md para instruções de deploy.

📄 Licença

Este projeto está sob a licença MIT.

👨‍💻 Desenvolvido com ❤️

Sistema criado para facilitar o gerenciamento de entregas de gás e água.

Versão: 1.0.0
Última atualização: Setembro 2025

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
backend		backend
frontend		frontend
venv		venv
.gitignore		.gitignore
INTEGRATION_GUIDE.md		INTEGRATION_GUIDE.md
README.md		README.md
TEST_CONNECTION.md		TEST_CONNECTION.md

Folders and files

Latest commit

History

Repository files navigation

🚚 Sistema de Gerenciamento de Entregas - Gás e Água

📋 Índice

🎯 Sobre o Projeto

🛠️ Tecnologias

Backend

Frontend

📦 Pré-requisitos

Obrigatórios:

Opcional:

Verificar Instalações:

🚀 Instalação e Configuração

Passo 1: Clone o Repositório

Passo 2: Configure o Backend

2.1 - Entre na pasta do backend:

2.2 - Crie o ambiente virtual Python:

2.3 - Instale as dependências:

2.4 - Configure o PostgreSQL:

2.5 - Configure as variáveis de ambiente:

2.6 - Execute as migrações do banco:

Passo 3: Configure o Frontend

3.1 - Abra um NOVO terminal e entre na pasta frontend:

3.2 - Instale as dependências:

3.3 - Configure as variáveis de ambiente:

▶️ Como Rodar o Projeto

Terminal 1 - Backend (FastAPI)

Terminal 2 - Frontend (React)

🎮 Como Usar

1. Acesse o Sistema

2. Crie o Primeiro Usuário

Opção A - Via Swagger (Recomendado):

Opção B - Via cURL:

3. Faça Login

4. Explore o Sistema

📊 Dashboard

👥 Clientes

📦 Produtos

🛒 Pedidos

✔️ Concluir Entrega

📁 Estrutura do Projeto

📡 API Endpoints

Autenticação

Clientes

Produtos

Pedidos

🐛 Troubleshooting

❌ Backend não inicia

❌ Frontend não inicia

❌ Login não funciona

❌ WhatsApp não envia

📞 Suporte

🎉 Pronto para Produção?

📄 Licença

👨‍💻 Desenvolvido com ❤️

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages