🚗 Hub de Formação de Condutores

Plataforma bilateral que conecta candidatos à CNH a instrutores autônomos credenciados.

📋 Índice

Visão Geral
Contexto Regulatório
Funcionalidades
Arquitetura
Stack Tecnológica
Modelagem de Domínio
Roadmap
Como Executar
Estrutura do Projeto
Contribuição

🎯 Visão Geral

O Hub de Formação de Condutores é uma plataforma bilateral (marketplace) que resolve um problema estrutural no processo de habilitação brasileiro: a dependência obrigatória dos Centros de Formação de Condutores (CFCs), que concentram oferta, inflacionam preços e tornam o processo pouco transparente para o candidato.

A plataforma atua em dois eixos complementares:

Eixo	Descrição
Intermediação	Conecta candidatos diretamente a instrutores autônomos credenciados pelo Detran
Educação	Oferece módulos de estudo e simulados para a prova teórica do Detran

Lançamento: Aracaju-SE (mercado inicial para validação do modelo)

🏛️ Contexto Regulatório

A plataforma é viabilizada pela Medida Provisória nº 1.327/2025, que flexibilizou as regulamentações de trânsito no Brasil, permitindo que instrutores autônomos devidamente credenciados atuem de forma independente, sem obrigatoriedade de vínculo com um CFC.

⚠️ Todos os instrutores cadastrados na plataforma passam por verificação de credencial junto ao Detran antes de serem ativados.

✨ Funcionalidades

👩‍🎓 Para o Candidato (Aluno)

Cadastro simplificado com validação de CPF
Busca de instrutores por bairro, preço, tipo de câmbio e avaliação
Agendamento e cancelamento de aulas práticas
Pagamento integrado e seguro
Avaliação do instrutor após cada aula
Acesso a banco de questões e simulados do Detran

🚘 Para o Instrutor

Cadastro com envio de credenciais (CNH, CRLV, Licença Detran)
Gerenciamento de agenda e disponibilidade
Aceite ou recusa de solicitações de alunos
Confirmação de conclusão de aulas
Repasse automático via split de pagamento

⚙️ Para a Plataforma

Verificação manual de credenciais (com integração futura à API do Detran)
Split automático de pagamento (taxa da plataforma + repasse ao instrutor)
Painel administrativo de gestão

💰 Modelo de Negócios (Monetização)

A monetização do Hub é composta por duas linhas principais de receita, desenhadas para escalar junto com o volume de aulas e com a oferta de instrutores.

1) Comissão por Transação (Take Rate)

Em cada aula prática agendada e paga pelo aplicativo, a plataforma retém uma porcentagem fixa do valor total (take rate).
O repasse ao instrutor ocorre via Split de Pagamento no gateway:
- taxa_plataforma (receita da plataforma)
- valor_instrutor (repasse ao instrutor)
Benefícios de engenharia:
- Liquidação automatizada
- Menos risco operacional e contábil no repasse
- Base sólida para reconciliação e auditoria

2) Plano Premium de Impulsionamento (Ads Interno)

Instrutores podem assinar um plano mensal (ou comprar impulsionamentos avulsos) para ter o perfil:
- destacado
- priorizado no topo dos resultados de busca na sua região
Esse “ads interno” aumenta conversão e LTV do instrutor sem depender de mídia externa.
Implicações técnicas:
- Ranking de busca precisa considerar o status premium, janela de vigência e regras anti-abuso
- Cobrança do plano pode ser tratada como assinatura ou como transação recorrente no gateway

🏗️ Arquitetura

O sistema adota o padrão Client-Server com API RESTful stateless, garantindo alta coesão, baixo acoplamento e escalabilidade independente entre frontend e backend.

┌─────────────────────────────────────────────────────────┐
│                        CLIENTE                          │
│              (Web App / Mobile App)                     │
└───────────────────────┬─────────────────────────────────┘
                        │  HTTPS / JSON
                        ▼
┌─────────────────────────────────────────────────────────┐
│                    API GATEWAY                          │
│                   (FastAPI + JWT)                       │
├──────────────┬──────────────┬──────────────┬────────────┤
│   /alunos    │  /instrutores│    /aulas    │ /pagamentos│
└──────┬───────┴──────┬───────┴──────┬───────┴─────┬──────┘
       │              │              │             │
       ▼              ▼              ▼             ▼
┌─────────────────────────────────────────────────────────┐
│                   CAMADA DE DADOS                       │
│         PostgreSQL + PostGIS  |  MinIO / S3             │
└─────────────────────────────────────────────────────────┘

🛠️ Stack Tecnológica

Backend

Camada	Tecnologia	Justificativa
Linguagem	Python 3.12+	Produtividade, ecossistema maduro, familiaridade da equipe
Framework	FastAPI	Performance assíncrona, OpenAPI nativo, DI integrado
Banco de Dados	PostgreSQL 16+	Robusto, transacional, suporte a PostGIS para geo futura
ORM	SQLAlchemy	Abstração de BD, prevenção de SQL Injection
Migrações	Alembic	Versionamento de schema integrado ao SQLAlchemy
Autenticação	JWT + OAuth2	Padrão stateless, escalável
Hash de Senhas	Passlib (Bcrypt)	Algoritmo seguro e amplamente auditado
Storage	MinIO (dev) / AWS S3 (prod)	Compatibilidade S3, isolamento por ambiente
Infraestrutura	Docker + Docker Compose	Ambientes reproduzíveis, onboarding rápido

Integrações Planejadas

Serviço	Finalidade	Status
Gateway de Pagamento	Split de pagamento instrutor/plataforma	🔄 Em avaliação
API Detran	Validação automática de credenciais	📅 Fase 3
Serviço de Notificações	SMS/Email para agendamentos	📅 Fase 2

🧩 Modelagem de Domínio

Casos de Uso Principais

Aluno

Buscar instrutores (com filtros)
Visualizar perfil do instrutor e reputação
Agendar aula prática
Pagar aula no app (split automático)
Cancelar aula dentro das regras
Avaliar instrutor após a aula

Instrutor

Cadastrar-se e enviar credenciais
Configurar disponibilidade e gerenciar agenda
Aceitar/recusar solicitações de aula
Confirmar conclusão de aula
Receber repasses via split
Assinar plano premium de impulsionamento (mensal) ou comprar impulsionamento avulso
Acompanhar performance (visibilidade, conversão, avaliações) no painel

Plataforma/Admin

Verificar credenciais do instrutor (manual no MVP)
Configurar take rate e regras de split
Moderar perfis e avaliações (anti-fraude)
Monitorar pagamentos, repasses e reconciliação

Entidades Principais

Usuario (base)
├── id          UUID
├── nome        VARCHAR
├── email       VARCHAR (unique)
├── senhaHash   VARCHAR
├── role        ENUM (aluno/instrutor/admin)
└── dataCriacao TIMESTAMP

Aluno (perfil do candidato)          Instrutor (perfil profissional)
├── cpf         VARCHAR (unique)     ├── credencialDetran  VARCHAR
└── statusCnh   ENUM                 ├── valorHoraAula     DECIMAL
                                     ├── statusVerificacao ENUM
                                     ├── premiumStatus     ENUM (free/premium)
                                     └── premiumAte        TIMESTAMP

Veiculo (atrelado ao Instrutor)
├── placa        VARCHAR
├── modelo       VARCHAR
├── ano          INTEGER
├── cambio       ENUM (manual/automatico)
└── adaptadoPcd  BOOLEAN

Aula (entidade pivô de agendamento)
├── alunoId         FK → Aluno
├── instrutorId     FK → Instrutor
├── pagamentoId     FK → Pagamento
├── dataHoraInicio  TIMESTAMP
├── dataHoraFim     TIMESTAMP
├── status          ENUM
└── localEncontro   VARCHAR

Pagamento
├── valorTotal      DECIMAL
├── taxaPlataforma  DECIMAL
├── valorInstrutor  DECIMAL
├── statusPagamento ENUM (pendente/pago/estornado/falhou)
├── metodo          ENUM (pix/cartao/boleto/...)
└── gatewayRef      VARCHAR

Nota de design: A herança de Usuario é implementada via tabela única com campo role + tabelas de perfil separadas (alunos, instrutores), evitando complexidade de JOINs em queries de autenticação.

🗺️ Roadmap

Fase 1 — MVP (Aracaju-SE)

Fase 2 — Crescimento

Sistema de avaliações e reputação
Banco de questões e simulados teóricos
Upload e verificação manual de documentos
Notificações por WhatsApp/SMS
Painel de métricas para instrutores
Expansão para interior de Sergipe

Fase 3 — Escala

Geolocalização avançada com PostGIS
Integração com API do Detran para validação automática
App mobile (iOS / Android)
Expansão nacional

Extras -

Front-end exigir que o payload do registro venha acompanhado de um token de reCAPTCHA ou Cloudflare Turnstile, barrando bots automaticamente.

🚀 Como Executar

Pré-requisitos

Docker e Docker Compose instalados
Python 3.1 (para desenvolvimento local)

1. Clone o repositório

git clone https://github.com/seu-usuario/hub-formacao-condutores.git
cd hub-formacao-condutores

2. Configure as variáveis de ambiente

# Este projeto usa o arquivo .env na raiz
# Edite o arquivo .env com suas configurações

# .env
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=hubcnh

# Modo oficial: API em container -> host do banco = db
DATABASE_URL=postgresql://postgres:postgres@db:5432/hubcnh

SECRET_KEY=troque-por-uma-chave-secreta-longa-aqui
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_ENDPOINT=minio:9000

3. Suba os containers

docker compose up -d

4. Execute as migrações

docker compose exec api alembic upgrade head

5. Acesse a documentação

Serviço	URL
API Docs (Swagger)	http://localhost:8000/docs
API Docs (ReDoc)	http://localhost:8000/redoc
MinIO Console	http://localhost:9001

6. Conectar no PostgreSQL pelo pgAdmin (opcional)

No docker-compose.yml, o Postgres está publicado como 5433:5432.
Para acessar no host (pgAdmin), use:

Host: localhost
Port: 5433
Database: hubcnh
Username: postgres
Password: postgres

🔜 Próximos Passos do Backend

Prioridade para o próximo ciclo:

Estruturar rotas versionadas (/api/v1) e remover placeholders em api/schemas/services
Implementar autenticação JWT (cadastro, login, hash de senha, autorização por role)
Entregar CRUD de instrutores e veículos
Implementar busca de instrutores com filtros básicos (bairro, preço, câmbio)
Criar fluxo de agendamento de aulas (criar, listar, cancelar, validações)
Adicionar testes mínimos (health, auth, fluxo principal)
Atualizar documentação a cada entrega de endpoint

📁 Estrutura do Projeto

hub-formacao-condutores/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   ├── db/
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── services/
│   │   └── main.py
│   ├── alembic/
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                   
│   ├── src/
│   ├── Dockerfile
│   └── package.json
│
├── docker-compose.yml
├── .env
└── README.md

Desenvolvido em Aracaju, Sergipe 🦀

Name		Name	Last commit message	Last commit date
backend		backend
frontend/src		frontend/src
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation