Sistema completo de gerenciamento hoteleiro com dashboard interativo, gestão de quartos, clientes e reservas.
Backend: FastAPI, SQLAlchemy, MySQL, JWT
Frontend: Nuxt 3, Vue 3, TypeScript, Tailwind CSS
Testes: pytest (100% cobertura)
Deploy: Hostinger (https://plataformahotel.online)
- 📊 Dashboard com métricas em tempo real
- 🏠 Gestão completa de quartos (CRUD, filtros, calendário)
- 👥 Gerenciamento de clientes e histórico
- 📅 Sistema de reservas com validações
- 🔐 Autenticação segura (JWT + OAuth2)
- 🎨 Interface moderna com tema claro/escuro (SweetAlert2)
- 📱 Design responsivo
- 🧪 30 testes automatizados (100% aprovação)
- 🔒 Auditoria completa de operações
- API Docs: https://plataformahotel.online/docs (Swagger - apenas desenvolvimento)
- Postman: Coleção completa da API
- Cobertura de Testes: COBERTURA_TESTES.md
- Segurança: SECURITY.md
- Deploy: PRODUCTION_CHECKLIST.md
cd backend
# Criar ambiente virtual
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Instalar dependências
pip install -r requirements.txt
# Configurar variáveis de ambiente
cp .env.example .env
nano .env # Editar com suas credenciaisArquivo .env mínimo necessário:
DATABASE_URL=mysql+pymysql://root:sua_senha@localhost:3306/HOTEL_APP
SECRET_KEY=gere-com-python-c-import-secrets-print-secrets-token-urlsafe-32
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000
ENVIRONMENT=developmentGerar SECRET_KEY segura:
python -c "import secrets; print(secrets.token_urlsafe(32))"Configurar banco de dados:
# Conectar ao MySQL
mysql -u root -p
# Criar banco
CREATE DATABASE HOTEL_APP CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit
# Inicializar tabelas
mysql -u root -p HOTEL_APP < database/init.sqlExecutar servidor:
uvicorn main:app --reload --host 0.0.0.0 --port 8000uvicorn main:app --reload --host 0.0.0.0 --port 8000
### Frontend
```bash
cd frontend
npm install
npm run dev
Acesso:
- Backend: http://localhost:8000
- Frontend: http://localhost:3000
O sistema possui 4 níveis hierárquicos de permissão:
👑 MASTER (Administrador Master)
- Nível: 1 (Mais Alto)
- Acesso: TOTAL e IRRESTRITO ao sistema
- Permissões:
- Criação de usuários com qualquer nível de permissão
- Gerenciamento completo de usuários (criar, editar, excluir)
- Acesso total a quartos, clientes, reservas
- Configurações avançadas do sistema
- Visualização de logs de auditoria
- Acesso a métricas e relatórios completos
- Responsável: Adalberto Ribeiro (Desenvolvedor/Proprietário)
🔧 ADMIN (Administrador)
- Nível: 2
- Acesso: Gerencial Completo
- Permissões:
- Gestão completa de quartos (CRUD)
- Gestão completa de clientes e reservas
- Visualização de dashboard e relatórios
- Sem acesso a criação de usuários
- Sem acesso a configurações críticas do sistema
📋 RECEPTIONIST (Recepcionista)
- Nível: 3
- Acesso: Operacional
- Permissões:
- Cadastro e edição de clientes
- Criação e consulta de reservas
- Consulta de quartos disponíveis
- Visualização limitada do dashboard
- Sem acesso a exclusões ou configurações
👁️ VIEWER (Visualizador)
- Nível: 4 (Mais Baixo)
- Acesso: SOMENTE LEITURA
- Permissões:
- Visualização de dashboard (apenas consulta)
- Consulta de clientes (sem edição)
- Consulta de quartos (sem modificação)
- Consulta de reservas (sem alteração)
- Nenhuma permissão de criação, edição ou exclusão
- Uso: Contas criadas pelo MASTER têm este nível por padrão
⚠️ Importante: Apenas o usuário MASTER pode criar novos usuários. Novos usuários são criados automaticamente com nível VIEWER e devem ter suas permissões elevadas manualmente pelo MASTER.
- Senhas: Mínimo 6 caracteres, criptografadas com bcrypt
- Tokens JWT: Expiração configurável (padrão: 30 dias)
- Bloqueio: Conta bloqueada após 5 tentativas de login falhas
- Auditoria: Todas as ações são registradas no sistema
- Hierarquia: Usuários só podem gerenciar contas de nível inferior ao seu
# Backend
cd backend && pytest -v
# Frontend
cd frontend && npm run testhotel_app/
├── 📂 backend/ # API FastAPI
│ ├── 📂 api/ # Endpoints da API
│ │ └── endpoints/ # Rotas organizadas por módulo
│ ├── 📂 core/ # Configurações principais
│ │ ├── database.py # Configuração MySQL/SQLite
│ │ └── security.py # JWT e autenticação
│ ├── 📂 models/ # Modelos SQLAlchemy
│ ├── 📂 schemas/ # Schemas Pydantic
│ ├── 📂 services/ # Lógica de negócio
│ ├── 📂 tests/ # Testes automatizados
│ ├── 📂 database/ # Scripts SQL
│ │ └── init.sql # Inicialização do MySQL
│ ├── 📄 .env # Variáveis de ambiente
│ └── 📄 main.py # Ponto de entrada da API
│
├── 📂 frontend/ # App Nuxt 3
│ ├── 📂 components/ # Componentes Vue reutilizáveis
│ ├── 📂 pages/ # Páginas da aplicação
│ │ ├── index.vue # Dashboard
│ │ ├── login.vue # Autenticação
│ │ ├── quartos/ # Gestão de quartos
│ │ ├── clientes/ # Gestão de clientes
│ │ └── reservas/ # Gestão de reservas
│ ├── 📂 services/ # Integração com API
│ │ └── apiClient.ts # Cliente HTTP
│ ├── 📂 composables/ # Funções reutilizáveis
│ └── 📂 plugins/ # Plugins (v-money3, etc)
│
├── 📄 README.md # Documentação do projeto
└── 📂 docs/ # Documentação adicional
- FastAPI - Framework web moderno e rápido
- SQLAlchemy - ORM para Python
- Pydantic - Validação de dados
- PyMySQL - Driver MySQL
- python-jose - JWT tokens
- passlib - Hash de senhas
- pytest - Framework de testes
- Nuxt 3 - Framework Vue.js
- Vue 3 - Framework JavaScript reativo
- TypeScript - JavaScript tipado
- Tailwind CSS - Framework CSS utilitário
- v-money3 - Máscara monetária
- Pinia - Gerenciamento de estado
O sistema está hospedado na Hostinger com as seguintes especificações:
Servidor: VPS Ubuntu (srv1139419)
Domínio: https://plataformahotel.online
SSL: Certificado Let's Encrypt (HTTPS ativado)
Servidor Web: Nginx como proxy reverso
Gerenciamento de Processos: PM2
Serviços em Execução:
- Backend API: PM2 (hotel-api) - Porta 8000
- Frontend: PM2 (hotel-frontend) - Porta 3000
- Banco de Dados: MySQL 8.0
Documentação da API:
- Swagger UI: https://plataformahotel.online/docs
- ReDoc: https://plataformahotel.online/redoc
Características:
- ✅ Alta disponibilidade (PM2 auto-restart)
- ✅ HTTPS com certificado SSL
- ✅ Backup automático do banco de dados
- ✅ Monitoramento de recursos
- ✅ Deploy contínuo via Git
# Construir imagens
docker-compose build
# Executar containers
docker-compose up -d
# Verificar logs
docker-compose logs -f- Configurar variáveis de ambiente de produção
- Configurar banco MySQL em produção
- Build do frontend:
npm run build - Deploy do backend:
gunicornouuvicorn
✨ Projeto Hotel Management App - Gerenciamento de hotéis moderno e eficiente!
- Python 3.10+
- Node.js (LTS recomendado) e npm ou yarn
- Git
backend/
├── main.py # Ponto de entrada da API
├── core/ # Configurações e database
├── models/ # Modelos SQLAlchemy
├── schemas/ # Validação Pydantic
├── services/ # Lógica de negócio
└── api/endpoints/ # Rotas da API
frontend/
├── pages/ # Páginas (login, dashboard, etc)
├── components/ # Componentes reutilizáveis
├── composables/ # Lógica compartilhada
├── middleware/ # Proteção de rotas
└── services/ # Cliente API
Hospedado por: Hostinger
© 2025 Plataforma Hotel. Todos os direitos reservados.
# Clone o repositório (se necessário)
git clone [URL_DO_SEU_REPOSITORIO]
cd hotel-app/backend
# Crie e ative o ambiente virtual
python -m venv .venv
# Ative o ambiente virtual
# No macOS/Linux:
source .venv/bin/activate
# No Windows:
# .venv\Scripts\activate
# Verifique se o ambiente está ativo (deve mostrar (.venv) no prompt)
which python # Deve mostrar o caminho do .venv# Instale todas as dependências
pip install --upgrade pip
pip install -r requirements.txt
# Verifique se todas foram instaladas
pip list# IMPORTANTE: Execute no diretório /backend e configure o PYTHONPATH
cd backend
# Instale dependências adicionais necessárias
pip install python-multipart "pydantic[email]"
# Execute a API com PYTHONPATH correto (obrigatório)
PYTHONPATH=/caminho/completo/para/hotel_app/backend python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Ou em background (recomendado para testes):
nohup python3 -c "import sys; sys.path.insert(0, '.'); from main import app; import uvicorn; uvicorn.run(app, host='0.0.0.0', port=8000)" > server.log 2>&1 &A API estará acessível em:
- URL Base:
http://127.0.0.1:8000 - Documentação Swagger:
http://127.0.0.1:8000/docs - Documentação ReDoc:
http://127.0.0.1:8000/redoc - Health Check:
http://127.0.0.1:8000/health
| Método | Endpoint | Descrição | Autenticação |
|---|---|---|---|
GET |
/ |
Informações da API | Não |
GET |
/health |
Status da aplicação | Não |
POST |
/api/v1/auth/register |
Registrar novo usuário | Não |
POST |
/api/v1/auth/token |
Login (obter JWT) | Não |
-
Acesse:
http://127.0.0.1:8000/docs -
Registrar usuário:
- Clique em
POST /api/v1/auth/register - Clique em "Try it out"
- Use o exemplo:
{ "username": "testuser", "password": "123456" }- Clique em "Execute"
- Clique em
-
Fazer login:
- Clique em
POST /api/v1/auth/token - Use "form-data" com:
username: testuserpassword: 123456
- Copie o
access_tokenda resposta
- Clique em
# 1. Registrar usuário
curl -X POST "http://127.0.0.1:8000/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"password": "123456"
}'
# 2. Fazer login
curl -X POST "http://127.0.0.1:8000/api/v1/auth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=testuser&password=123456"
# 3. Health check
curl -X GET "http://127.0.0.1:8000/health"import requests
# Base URL da API
BASE_URL = "http://127.0.0.1:8000"
# 1. Registrar usuário
response = requests.post(f"{BASE_URL}/api/v1/auth/register", json={
"username": "testuser",
"password": "123456"
})
print("Registro:", response.json())
# 2. Fazer login
response = requests.post(f"{BASE_URL}/api/v1/auth/token", data={
"username": "testuser",
"password": "123456"
})
token_data = response.json()
token = token_data["access_token"]
print("Token:", token)
# 3. Usar token em requisições futuras
headers = {"Authorization": f"Bearer {token}"}
# response = requests.get(f"{BASE_URL}/protected-endpoint", headers=headers)# SOLUÇÃO: Configure o PYTHONPATH corretamente
cd backend
PYTHONPATH=$(pwd) python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000# SOLUÇÃO: Execute no diretório correto com PYTHONPATH
cd backend # OBRIGATÓRIO estar neste diretório
PYTHONPATH=/caminho/completo/para/backend python3 -m uvicorn main:app --reload# SOLUÇÃO: Instale dependências adicionais
pip install python-multipart "pydantic[email]"# SOLUÇÃO: Crie o arquivo tsconfig.json
cd frontend
echo '{"extends": "./.nuxt/tsconfig.json"}' > tsconfig.json
npm install --save-dev vue-tsc typescript# SOLUÇÃO: Instale dependências de desenvolvimento
npm install --save-dev vue-tsc typescript# Backend: Use porta diferente
uvicorn main:app --reload --port 8001
# Frontend: Use porta diferente
npx nuxt dev --port 3001# O arquivo app.db será criado automaticamente na primeira execução
# Se houver problemas, delete e reinicie:
rm app.db
PYTHONPATH=$(pwd) python3 -m uvicorn main:app --reloadcd frontend
# Instale as dependências do Nuxt 3
npm installO arquivo .env já está configurado na pasta frontend:
# .env
API_BASE_URL=http://localhost:8000# IMPORTANTE: Execute no diretório /frontend
cd frontend
# Instale dependências adicionais necessárias (se não instaladas)
npm install --save-dev vue-tsc typescript
# Crie o tsconfig.json (se não existir)
echo '{"extends": "./.nuxt/tsconfig.json"}' > tsconfig.json
# Execute o servidor de desenvolvimento do Nuxt 3
npm run dev
# Ou use npx diretamente:
npx nuxt dev --port 3000O Frontend estará acessível em http://localhost:3000.
Como boa prática, execute regularmente as verificações de lint e tipos antes de enviar alterações:
# Verificar regras de estilo e padrões do projeto
npm run lint
# Validar os tipos TypeScript sem gerar arquivos
npm run lint:typesSe algum erro aparecer, corrija os arquivos indicados até que ambos os comandos terminem sem falhas.
# Teste o Backend
curl http://localhost:8000/health
# Resposta esperada: {"status":"healthy","message":"API is running"}
# Teste o Frontend (abra no navegador)
# http://localhost:3000 - deve carregar a página de login
# http://localhost:8000/docs - documentação da APIA tela abaixo demonstra o dashboard que o usuário visualiza após autenticação bem-sucedida:
- Backend: Logs aparecem no terminal onde foi executado
- Frontend: Logs do Nuxt aparecem no terminal + logs do browser (F12)
- Erros TypeScript: São exibidos no terminal do frontend (não impedem funcionamento)
-
Sistema de Autenticação Completo
- Página de login funcional (
/login) - Middleware de proteção de rotas
- Composable
useAuth()para gerenciamento de estado - Armazenamento seguro de token JWT
- Página de login funcional (
-
Dashboard Principal (
/)- Página protegida por middleware
auth - Estatísticas do hotel (cards informativos)
- Links de navegação para futuras páginas
- Timeline de atividades recentes
- Botão de logout funcional
- Página protegida por middleware
-
Arquitetura Moderna
- Vue 3 com Composition API
- TypeScript para type safety
- Tailwind CSS para estilização
- Estrutura escalável e modular
- Dashboard Principal (
/) - Visão geral do hotel com estatísticas - Sistema de Login (
/login) - Autenticação JWT completa - Gerenciamento de Clientes (
/clients) - CRUD completo implementado - Middleware de Proteção - Rotas protegidas automaticamente
- API REST Completa - Endpoints para todas as operações
- Upload de imagens (quartos e clientes)
- Notificações em tempo real
- CI/CD pipeline
- Containerização Docker
A API segue uma arquitetura modular para separação de responsabilidades:
backend/
├── main.py # 🚀 Ponto de entrada da aplicação
├── requirements.txt # 📦 Dependências Python
│
├── core/ # ⚙️ Configurações centrais
│ ├── database.py # 🗄️ Configuração do banco de dados
│ └── config.py # 🔧 Configurações da aplicação
│
├── models/ # 📊 Modelos SQLAlchemy
│ ├── base.py # 🏗️ Base declarativa
│ ├── user_model.py # 👤 Modelo de usuário
│ └── client_model.py # 👥 Modelo de cliente
│
├── schemas/ # ✅ Schemas Pydantic (validação)
│ ├── user_schema.py # 👤 Schemas de usuário
│ └── client_schemas.py # 👥 Schemas de cliente
│
├── api/ # 🔗 Rotas da API
│ ├── api.py # 🎯 Agregador de rotas
│ └── endpoints/ # 📍 Endpoints específicos
│ ├── auth.py # 🔐 Autenticação e registro
│ └── clients.py # 👥 CRUD de clientes
│
├── services/ # 🔄 Lógica de negócio
│ ├── auth_service.py # 🔐 Serviços de autenticação
│ └── client_service.py # 👥 Serviços de clientes
│
└── dependencies/ # 🔗 Dependências injetáveis
└── auth.py # 🔐 Dependências de autenticação
O frontend segue a arquitetura do Nuxt 3 com organização modular:
frontend/
├── package.json # 📦 Dependências Node.js
├── nuxt.config.ts # ⚙️ Configuração do Nuxt 3
├── tailwind.config.js # 🎨 Configuração do Tailwind CSS
├── app.vue # 🏠 Componente raiz da aplicação
│
├── assets/ # 🎨 Assets e estilos
│ └── css/
│ └── main.css # 🎨 Estilos globais Tailwind
│
├── components/ # 🧩 Componentes reutilizáveis
│ └── (componentes futuros)
│
├── composables/ # 🔄 Composables Vue 3
│ └── useAuth.ts # 🔐 Gerenciamento de autenticação
│
├── middleware/ # 🛡️ Middleware de rotas
│ └── auth.ts # 🔐 Proteção de rotas autenticadas
│
├── pages/ # 📄 Páginas da aplicação
│ ├── index.vue # 🏠 Dashboard principal
│ ├── login.vue # 🔐 Página de login
│ └── clients/
│ └── index.vue # 👥 CRUD completo de clientes
│
├── services/ # 🔗 Serviços de API
│ └── apiClient.ts # 🔗 Cliente HTTP com auth
│
└── FRONTEND_SETUP.md # 📚 Documentação específica
│ └── auth_service.py # Serviços de autenticação
└── dependencies/ # Dependências FastAPI
└── auth.py # Dependências de auth
| Módulo | Método | Endpoint | Descrição | Auth |
|---|---|---|---|---|
| Root | GET |
/ |
Informações da API | ❌ |
| Health | GET |
/health |
Status da aplicação | ❌ |
| Auth | POST |
/api/v1/auth/register |
Registrar novo usuário | ❌ |
| Auth | POST |
/api/v1/auth/token |
Login e geração de JWT | ❌ |
| Clients | GET |
/api/v1/clients |
Listar clientes | ✅ |
| Clients | POST |
/api/v1/clients |
Criar novo cliente | ✅ |
| Clients | GET |
/api/v1/clients/{id} |
Buscar cliente por ID | ✅ |
| Clients | PUT |
/api/v1/clients/{id} |
Atualizar cliente | ✅ |
| Clients | DELETE |
/api/v1/clients/{id} |
Excluir cliente | ✅ |
| Clients | GET |
/api/v1/clients/search |
Buscar clientes | ✅ |
- Backend FastAPI completo - API REST funcional
- Sistema de Autenticação - JWT + OAuth2 Password Flow
- Frontend Nuxt 3 - Interface moderna e responsiva
- Dashboard Principal - Visão geral do hotel
- CRUD de Clientes - Gerenciamento completo de clientes
- Middleware de Proteção - Rotas autenticadas
- Banco de Dados SQLite - Modelos User e Client
- Documentação Completa - APIs documentadas no Swagger
- Upload de Imagens - Fotos de quartos e clientes
- Notificações - Sistema de alertas em tempo real
- Configurar Docker - Containerização completa
- Implementar CI/CD - Pipeline de deploy automatizado
- FastAPI - Framework web moderno, rápido e com docs automáticas
- SQLAlchemy - ORM para mapeamento objeto-relacional
- Pydantic - Validação de dados e serialização
- JWT + OAuth2 - Autenticação stateless e segura
- Bcrypt - Hash seguro de senhas com salt
- SQLite - Banco de dados leve para desenvolvimento
- Uvicorn - Servidor ASGI para produção
- Nuxt 3 - Framework Vue.js com SSR e SPA
- Vue 3 - Framework reativo com Composition API
- TypeScript - JavaScript tipado para maior segurança
- Tailwind CSS - Framework CSS utilitário e responsivo
- Composables - Lógica reutilizável do Vue 3
- Middleware - Proteção automática de rotas
- Git - Controle de versão
- npm - Gerenciador de pacotes Node.js
- pip - Gerenciador de pacotes Python
- VS Code - Editor de código recomendado
- Swagger/OpenAPI - Documentação automática da API
- SQLite - Desenvolvimento local
- PostgreSQL - Produção (futuro)
- Migrações - SQLAlchemy Alembic
- Schemas - Validação Pydantic
- Axios - Cliente HTTP
- Linguagens: Python, TypeScript, Vue, CSS
- Arquivos Principais: ~30 arquivos organizados
- Endpoints API: 11 endpoints funcionais
- Páginas Frontend: 3 páginas completas (Dashboard, Login, Clientes)
- Modelos de Dados: 2 modelos (User, Client)
- Componentes: 1 middleware + 1 composable
- Linhas de Código: ~2000+ linhas
- ✅ Sistema de Autenticação JWT - Login/logout seguro
- ✅ Dashboard Interativo - Visão geral com estatísticas
- ✅ CRUD Completo de Clientes - Create, Read, Update, Delete
- ✅ Proteção Automática de Rotas - Middleware de autenticação
- ✅ API REST Documentada - Swagger UI automático
- ✅ Interface Responsiva - Design mobile-first Tailwind
- Backend completo com FastAPI e banco de dados
- Frontend moderno com Nuxt 3 e Tailwind CSS
- Sistema de autenticação robusto e seguro
- CRUD funcional para gerenciamento de clientes
- Documentação completa e código limpo
- Arquitetura escalável pronta para expansão
O sistema está 100% funcional para uso em ambiente de desenvolvimento e pode ser facilmente expandido com novas funcionalidades como reservas, quartos e relatórios.
Status: ✅ COMPLETO E OPERACIONAL ✅
