StudentCard (Vou de Ônibus)

---

Visão geral

StudentCard é um sistema para emissão e gerenciamento de carteirinhas estudantis e monitoramento em tempo real de rotas de ônibus. O frontend é uma SPA em React + TypeScript que consome uma API REST construída em Spring Boot. Atualizações de localização são transmitidas em tempo real via WebSocket/STOMP e a última localização é armazenada em Redis.

Principais conceitos:

• Autenticação stateless via JWT
• Perfis: STUDENT, DRIVER, ADMIN
• Monitoramento em tempo real: motoristas enviam GPS; estudantes e admins consomem
• Arquitetura backend: Hexagonal (Ports & Adapters) + DDD
• Cache de localização: Redis; broadcast: STOMP

---

Frontend

• Stack: React 19, TypeScript, Vite, Tailwind CSS, Leaflet, axios, @stomp/stompjs + sockjs-client.
• Arquivos relevantes:
  • frontend/src/api.ts — instância axios e interceptor JWT
  • frontend/src/hooks/useWebSocket.ts — hook que encapsula STOMP/SockJS
  • frontend/src/App.tsx — rotas e proteção de páginas
  • frontend/src/storage.ts — helper que persiste dados por aba
• Fluxos principais:
  • Login/Register → salva token + metadados em storage
  • ProtectedRoute: valida token, userType e userStatus
  • Motorista transmite localização (navigator.geolocation) para /api/routes/{routeId}/location
  • Student/Admin assinam /topic/route/{routeId} via STOMP para receber atualizações
• Observação: atualmente frontend/src/api.ts tem baseURL hardcoded (http://localhost:8080). Recomenda-se usar VITE_API_URL e VITE_WS_URL.

---

Backend

• Stack: Java + Spring Boot, Spring Security (JWT), Spring Data JPA (Postgres), spring-data-redis (Redis), WebSocket/STOMP (SimpMessagingTemplate).
• Organização (Hexagonal / DDD):
  • domain/ — entidades, VOs, regras
  • application/ — casos de uso e ports (inbound/outbound)
  • infrastructure/ — adapters (REST controllers, JPA, Redis, STOMP, JWT, BCrypt)
• Principais responsabilidades:
  • Autenticação/Autorização: JWT stateless e SecurityFilter
  • Rotas: criação, início, pausa, retomada, fim, e publicação de eventos
  • Localização: motorista envia via REST; última posição salva em Redis e broadcast via STOMP

---

Variáveis de ambiente recomendadas

Backend (.env ou application.properties via import):

# JWT
jwt.secret=uma_chave_secreta_muito_segura
jwt.expiration=1440

# PostgreSQL
spring.datasource.url=jdbc:postgresql://localhost:5432/studentcard_db
spring.datasource.username=postgres
spring.datasource.password=postgres

# Redis
spring.redis.host=localhost
spring.redis.port=6379

# App
server.port=8080

Frontend (Vite .env):

VITE_API_URL=http://localhost:8080
VITE_WS_URL=http://localhost:8080/ws

---

Como rodar (local)

Backend

Pré-requisitos: Java, Maven (ou use ./mvnw), PostgreSQL e Redis.

Passos:

# na raiz do backend
./mvnw clean package
./mvnw spring-boot:run
# ou
java -jar target/studentcard-0.0.1-SNAPSHOT.jar

Frontend

Pré-requisitos: Node.js >= 18

Passos:

cd frontend
npm install
npm run dev

Observação: ajuste VITE_API_URL/VITE_WS_URL no frontend se o backend rodar em endpoint diferente.

---

Endpoints essenciais (resumo)

• Auth:
  • POST /api/auth/login — login (retorna token JWT e metadados)
  • POST /api/auth/register — registro
• Users (admin actions):
  • GET /api/users/{id}
  • POST /api/users/authorize/{id}
  • POST /api/users/block/{id}
• StudentCards:
  • POST /api/student-cards/issue
  • POST /api/student-cards/{id}/renew
  • GET /api/student-cards (admin)
• Routes / Location:
  • POST /api/routes — criar rota
  • POST /api/routes/{routeId}/start — iniciar
  • POST /api/routes/{routeId}/pause — pausar
  • POST /api/routes/{routeId}/resume — retomar
  • POST /api/routes/{routeId}/end — encerrar
  • POST /api/routes/{routeId}/location — motorista envia localização
  • GET /api/routes/{routeId}/location — obter última localização

---

WebSocket / STOMP

• Endpoint (SockJS): /ws
• Broker simple: enableSimpleBroker("/topic", "/queue")
• Prefixo de application destinations: /app
• Tópico para monitoramento de rota: /topic/route/{routeId}
• Autenticação: token JWT enviado no handshake (query param ?token= e/ou connectHeaders.Authorization)

Exemplo de payload (location update):

{
  "type": "location_update",
  "latitude": -12.9714,
  "longitude": -38.5014,
  "timestamp": 1670000000000
}

---

Galeria de screenshots

Tela de Login

Aqui está a tela de login:

---

Tela de Cadastro

Aqui está a tela de cadastro:

---

Completar Perfil — etapa 1

Aqui está a tela de completar perfil (etapa 1):

---

Completar Perfil — etapa 2

Continuação do fluxo de completar perfil:

---

Perfil em Análise

Tela indicando que o perfil está em análise:

---

Acesso Bloqueado

Tela de acesso bloqueado / restrição:

---

Dashboard do Estudante

---

Estudante com Localização (mapa)

---

Rota Ativa (motorista)

---

Admin — Rotas

---

Admin — Rota Ativa

---

Admin — Rota UEFS

---

Admin — Usuários Ativos

---

Admin — Usuários Pendentes

---

Admin — Carteiras

---

Motorista — Dashboard

---

Motorista — Criar Rotas

---