✂️ NextCut

🚀 Modernizando o atendimento da barbearia com tecnologia em tempo real

Transforme o antigo caderno físico em uma experiência digital inteligente, rápida e profissional.

🛠️ Início rápido (desenvolvimento)

Pré-requisitos:

Node.js 20+
Java 17+
Maven 3.9+

Backend (Javalin + Maven):

cd backend
mvn test
mvn exec:java "-Dexec.mainClass=com.nextcut.app.App"

Por padrão, a API sobe em http://localhost:8080.

Important

Aviso para uso no GitHub Codespaces: O backend rodando na porta 8080 precisa estar com a visibilidade Pública para o frontend conseguir acessá-lo sem ser bloqueado pela tela de autenticação do GitHub. Rode no terminal: gh codespace ports visibility 8080:public -c $CODESPACE_NAME (A porta 8081 do Robô NÃO precisa ser pública, o Java acessa ela internamente).

Micro-serviço WhatsApp (Node.js): Responsável por enviar os códigos OTP (4 dígitos) via WhatsApp Web de forma invisível.

cd whatsapp-service
npm install
npm start

(Um QR Code aparecerá no terminal para você escanear e conectar)

Frontend (Vite + React + Tailwind):

cd frontend
npm install

Configuração de Ambiente (.env): O frontend precisa saber onde o backend está, e o backend precisa saber onde o WhatsApp está.

Frontend: Copie cp .env.example .env.
Backend: Copie cp .env.example .env e mantenha EVOLUTION_API_URL=http://localhost:8081. Preencha os dados do PIX (opcional) se for testar a geração de QR Code.

Inicie o servidor frontend:

npm run dev

Testes (local e CI):

cd frontend && npm test
cd backend && mvn test

📌 Sobre o Projeto

NextCut é uma plataforma web de fila virtual para barbearias que desejam abandonar métodos manuais e oferecer uma experiência moderna aos clientes.

🎯 Estado atual: frontend React com telas de cliente (incluindo verificação de telefone via código OTP de 4 dígitos), acompanhamento da fila, login e painel administrativo; backend Java com Javalin, JDBC/PostgreSQL, autenticação BCrypt, fila FIFO com tratamento para clientes IN_SERVICE e WAITING, além de WebSocket para atualização em tempo real. Algumas ações administrativas exibidas na UI ainda dependem de endpoints backend futuros, conforme planejamento do projeto.

🎯 Problema Resolvido

Antes:

Caderno físico
Confusão na ordem
Cliente preso no local
Falta de previsibilidade
Gestão manual

Depois:

Entrada via link
Fila em tempo real
Senha automática
Acompanhamento remoto
Painel administrativo

🌟 Principais Funcionalidades

👤 Cliente

Entrar na fila com nome + telefone
Receber senha sequencial automática
Acompanhar posição em tempo real
Ver estimativa de espera
Sair da fila

💈 Barbeiro (Admin)

Login seguro
Visualizar fila completa
Chamar próximo cliente
Remover clientes (previsto no planejamento)
Abrir/Fechar atendimento (previsto no planejamento)
Ajustar tempo médio de serviço (previsto no planejamento)

🧠 Arquitetura do Sistema

flowchart LR
    A[Cliente / Barbeiro Frontend React] --> B[HTTP REST API]
    A --> C[WebSocket Tempo Real]
    B --> D[Javalin Controllers]
    C --> E[WebSocket Manager]
    D --> F[Service Layer]
    E --> F
    F --> G[DAO Layer]
    G --> H[(Supabase PostgreSQL)]
    F --> W[Node.js WPPConnect Bot]

🏗️ Clean Architecture

flowchart TD
    UI[Frontend React] --> Controller
    Controller --> Service
    Service --> DAO
    DAO --> Database[(Supabase)]
    Service --> QueueMemory[(ArrayDeque FIFO)]
    Service --> NodeBot[WhatsApp Bot]

📂 Estrutura de Pastas

nextcut/
│
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── routes/
│   │   └── tests/
│
├── backend/
│   ├── src/main/java/com/nextcut/
│   │   ├── controller/
│   │   ├── service/
│   │   ├── dao/
│   │   ├── model/
│   │   ├── websocket/
│   │   ├── config/
│   │   └── util/
│   │
│   └── src/test/
│
├── whatsapp-service/ (Node.js WPPConnect)
│
└── docs/

⚙️ Stack Tecnológica

🎨 Frontend

React JS
Vite
TailwindCSS
Vitest (com jsdom)
Axios
React Router
Context API
WebSocket

🛠️ Backend (Core)

Java 17+
Javalin
Maven
JDBC
BCrypt
JUnit
Mockito

🤖 Backend (Micro-serviço Mensageria)

Node.js 20+
Express
WPPConnect (WhatsApp Web JS)

🗄️ Banco de Dados

Supabase PostgreSQL
JDBC
Scripts SQL em docs/sql/
Autenticação própria com BCrypt
Atualização em tempo real via WebSocket Javalin

🔁 Fluxo Principal do Sistema

sequenceDiagram
    participant Cliente
    participant Frontend
    participant Backend
    participant NodeBot
    participant DB
    participant WebSocket

    Cliente->>Frontend: Preenche nome + telefone
    Frontend->>Backend: POST /queue/request-otp
    Backend->>NodeBot: POST /message/sendText (WPPConnect)
    NodeBot-->>Cliente: Envia WhatsApp real
    Backend-->>Frontend: 200 OK (Código salvo)
    Cliente->>Frontend: Digita código de 4 dígitos na tela de OTP
    Frontend->>Backend: POST /queue/verify-otp
    Backend->>DB: Salva entrada
    Backend->>Backend: Atualiza ArrayDeque
    Backend->>WebSocket: Broadcast atualização
    WebSocket-->>Frontend: Nova posição
    Frontend-->>Cliente: Exibe senha e posição

📋 Regras de Negócio

🔒 Regras Obrigatórias

FIFO (First In, First Out)
Senha sequencial
Telefone único
Cliente não duplica
Apenas admin gerencia fila
Atualização em tempo real
Persistência híbrida (memória + banco)

🗃️ Modelagem de Dados

Tabela: `barber`

Campo	Tipo
id	UUID
username	VARCHAR
password_hash	TEXT
avg_service_minutes	INT
is_open	BOOLEAN
created_at	TIMESTAMP

Tabela: `queue_entries`

Campo	Tipo
id	UUID
ticket_number	INT
client_name	VARCHAR
client_phone	VARCHAR
status	VARCHAR
position	INT
entered_at	TIMESTAMP
called_at	TIMESTAMP
paid_amount	DOUBLE
tip_amount	DOUBLE

🌐 Endpoints da API

Estado atual do backend:

Cliente

GET /
POST /queue/request-otp
POST /queue/verify-otp
POST /queue/join (Legado interno)
GET /queue/status/{phone}
POST /queue/leave/{phone}

Admin

POST /login
POST /admin/next
POST /admin/payment/request
POST /admin/finish
POST /pix/gerar

Planejados para o painel administrativo:

POST /admin/remove/{id}
POST /admin/toggle

WebSocket

/ws/queue

🔐 Segurança

Implementado:

BCrypt password hashing
Validação de telefone (OTP via WhatsApp)
Proteção contra duplicidade
Proteção de Rate Limiting (Anti-spam OTP)
Token de sessão simples para o painel
Erros controlados

🧪 Testes

Issue #9: o frontend usa Vitest + Testing Library (padrão recomendado com Vite); o comando continua sendo npm test, como nos critérios de aceite.

Backend

QueueService
AuthService
DatabaseConfig
FIFO
Duplicidade por telefone

Frontend

Componentes base
Renderização com Testing Library
Estados visuais de botao

flowchart LR
    A[Testes Unitários] --> B[Testes Integração]
    B --> C[Testes Fluxo Crítico]
    C --> D[Deploy]

✔ 📄 Documentação e Planejamento

Veja os arquivos de especificação para detalhes:

agents.md — Guia mestre para agentes de IA e developers
specs.md — Especificações técnicas
requirements.md — Requisitos funcionais
docs/git-workflow.md — Fluxo Git, branches e checklist de PR
CONTRIBUTING.md — Como contribuir e padrões do repositório

📈 Roadmap

✏️ Fundação do Projeto

🔨 Fase 1: MVP Core

Estrutura base (frontend + backend)
Banco de dados via JDBC/PostgreSQL
Login admin
Entrada na fila com validação OTP via WhatsApp
Tela de acompanhamento
Tempo real (WebSocket)
Completar endpoints administrativos de remover cliente e alternar atendimento

🚀 Fase 2: Melhorias

🎨 Diferenciais

💥 O que torna o NextCut especial:

Velocidade

Fila instantânea e atualizações em segundos

Profissionalismo

Visual moderno e experiência premium

Escalabilidade

Base pronta para crescimento

Didático

Código estruturado para aprendizado

🤝 Contribuição

Padrões:

Clean Architecture
SOLID
DRY
KISS
Testes obrigatórios

📜 Licença

Este projeto pode ser adaptado para fins acadêmicos, comerciais ou evolutivos conforme necessidade.

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
docs		docs
frontend		frontend
whatsapp-service		whatsapp-service
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
agents.md		agents.md
requirements.md		requirements.md
specs.md		specs.md

Latest commit

History

Folders and files

Repository files navigation

✂️ NextCut — Fila Virtual para Barbearia