Introdução & Destaques de Engenharia no Back-end
A API do Marketplace foi projetada para lidar com requisições com baixa latência, gestão modular por casos de uso e alto padrão de segurança para proteger a comunidade privada de equipistas.
🔒 Ambiente Seguro & Privado
Acesso e negociação exclusiva para membros autenticados e validados, utilizando JWT e regras de permissão regional e administrativa.
🧱 Arquitetura Modular (Use Cases)
Clean Architecture com regras de negócio isoladas em casos de uso desacoplados, facilitando a manutenção e a escalabilidade.
🗄️ Persistência Relacional com Migrations
Prisma ORM integrado ao PostgreSQL (Supabase) com controle de setores, representantes, histórico financeiro e integridade referencial.
🛡️ Gestão Regional e Setorial
Mapeamento de setores geográficos com representantes dedicados para moderar membros locais e supervisionar anúncios.
🖼️ Processamento de Mídia em Memória (Sharp)
Inspeciona e comprime buffers de imagem no próprio servidor antes do envio ao Supabase Storage, reduzindo consumo de banda e armazenamento.
🔐 Autenticação & Hashing Seguro (BcryptJS)
Criptografia de ponta para senhas de membros e representantes com BcryptJS, assegurando proteção contra ataques cibernéticos.
⚡ Compilação Ultrarrápida com SWC Core
Ambiente de build e execução otimizado com compiler Rust (@swc/core e tsx) substituindo compiladores tradicionais.
📡 Comunicação em Tempo Real (WebSockets)
Infraestrutura pronta para notificações em tempo real e atualização instantânea de eventos no ecossistema via biblioteca ws.
📄 Documentação Interativa & Swagger UI
Especificação OpenAPI/Swagger (swagger-ui-express) integrada para teste, validação e consumo interativo de todos os endpoints da API.
Diagrama de Arquitetura do Back-end
Etapas do Projeto & Módulos do Back-end
Permite o registro de novos membros recebendo os dados estruturados do DTO (ICreateUserDTO).
Valida credenciais do usuário com BcryptJS e gera o token JWT para autenticação em rotas protegidas.
O middleware ensureAuthenticated.ts intercepta requisições, valida o token e injeta o ID e perfil do usuário no contexto Express.
Permite a criação e organização das regiões geográficas (nome, equipe, cidade e estado) para vincular membros e filtrar produtos.
Cadastro e manutenção de representantes atrelados aos setores regionais para supervisão comunitária.
Permite que os representantes gerenciem especificamente os equipistas vinculados ao seu setor regional (alterando status, editando dados ou moderando contas).
Manutenção dos dados próprios de acesso do representante.
Obtenção e atualização das informações de perfil do equipista logado (incluindo biografia e link do Instagram).
Upload, compressão/redimensionamento com Sharp e publicação de imagens de perfil e capa no Supabase Storage.
Permite que o próprio equipista encerre e remova sua conta da plataforma.
Permite ao equipista cadastrar produtos com upload otimizado de múltiplas imagens tratadas no servidor.
Listagem completa do marketplace para visitantes/compradores e visualização filtrada por vendedor ou por anúncios próprios.
Gerenciamento completo dos anúncios pertencentes ao equipista logado.
Adiciona ou remove um produto da lista de desejos do equipista utilizando IToggleFavoriteDTO.
Exibe os itens favoritados pelo usuário e contabiliza a popularidade de produtos e de anúncios do vendedor.
Criação, atualização e remoção de notas e comentários sobre os produtos adquiridos.
Cálculo de médias e exibição das estatísticas de avaliação de produtos e de vendedores.
Gerenciamento do histórico de itens adquiridos pelo equipista comprador.
Relatórios detalhados, contagem e consolidação das métricas financeiras de compras do usuário.
Consolidação do histórico de saídas e vendas efetuadas pelos vendedores.
Visão financeira com totais acumulados e detalhes históricos das negociações do vendedor.
Cadastro único de endereço físico por usuário (CEP, rua, bairro, número) para facilitar encontros e retiradas comunitárias.
Painel administrativo restrito para controle total de membros, alteração de status (ativo/inativo/suspenso), edição e exclusão global de contas.
Estrutura do Banco de Dados (PostgreSQL via Prisma)
Entidade: Setor (sectors)
| Campo | Tipo | Descrição |
|---|---|---|
id | String (UUID) | ID único do setor (Chave Primária). |
nome | String | Nome do setor regional (Único). |
equipe | String? | Nome opcional da equipe associada. |
cidade | String | Cidade do setor. |
estado | String | UF do setor. |
createdAt / updatedAt | DateTime | Timestamps de criação e atualização. |
Entidade: Representante (representatives)
| Campo | Tipo | Descrição |
|---|---|---|
id | String (UUID) | ID único do representante (Chave Primária). |
nome | String | Nome completo do representante. |
telefone | String | Telefone de contato. |
email | String | E-mail único de acesso. |
senha | String? | Senha hash para autenticação do representante. |
sectorId | String | FK do setor supervisionado (Cascade deletion). |
createdAt / updatedAt | DateTime | Timestamps de criação e atualização. |
Entidade: Usuário (users)
| Campo | Tipo | Descrição |
|---|---|---|
id | String | ID único do usuário (Chave Primária). |
email | String | E-mail único do equipista. |
cpf | String? | CPF opcional do equipista (Único). |
nome | String | Nome completo do equipista. |
telefone | String | Telefone / WhatsApp de contato. |
biografia | String? | Biografia e apresentação no perfil público. |
avatarUrl | String? | URL da foto de perfil (Avatar). |
coverUrl | String? | URL da imagem de capa (Banner). |
instagramUrl | String? | Link ou usuário oficial do Instagram. |
status | String | Status da conta (Default: INATIVO). |
role | String | Nível de acesso (Default: USER). |
sectorId | String? | FK do setor associado ao membro (SetNull on delete). |
createdAt / updatedAt | DateTime | Timestamps de criação e atualização. |
Entidade: Produto (products)
| Campo | Tipo | Descrição |
|---|---|---|
id | String (UUID) | ID único do produto (Chave Primária). |
nome | String | Título do anúncio. |
preco | Float | Preço de venda do item. |
descricao | String | Descrição detalhada. |
imagens | String[] | Lista de URLs de fotos do produto. |
categoria | ProductCategory | Enum (COMIDA, ROUPAS, COSMETICOS, ELETRONICOS, SAUDE, CASA, BRINQUEDOS, LIVROS, ESPORTES, AUTOMOTIVO, OUTROS). |
userId | String | FK do equipista anunciante (Cascade deletion). |
Entidades Complementares e Relacionamentos
| Tabela | Campos Principais | Restrições / Regras |
|---|---|---|
addresses |
cep, rua, numero, bairro, cidade, estado, complemento, userId |
Garante no máximo 1 endereço por usuário (@unique [userId]). |
favorites |
userId, productId, createdAt |
Chave única composta para evitar múltiplos favoritos no mesmo item (@unique([userId, productId])). |
ratings |
nota, comentario, userId, productId |
Uma avaliação por produto por usuário (@unique([userId, productId])). |
purchased_products |
userId, productId, quantidade |
Consolidação de histórico de compras do usuário. |
sold_products |
userId, productId, quantidade |
Registro de vendas efetuadas pelo vendedor. |
Estrutura de Repositório (Back-end)
MARKETPLACE-ENTRE-EQUIPISTAS/
├── prisma/
│ ├── migrations/ # Histórico de migrations do PostgreSQL
│ └── schema.prisma # Schemas Prisma (Sector, Representative, User, Product, Address, etc.)
├── src/
│ ├── @types/ # Tipagens globais do Express (Ex: express.d.ts)
│ ├── modules/ # Módulos desacoplados em Use Cases
│ │ ├── addresses/ # Gerenciamento de endereços
│ │ ├── admin/ # Moderação e controle global de usuários
│ │ ├── auth/ # Autenticação (signIn, signUp)
│ │ ├── favorites/ # Favoritamento e contagem de itens
│ │ ├── products/ # Anúncios, catálogo e gestão de produtos
│ │ ├── purchasedProducts/ # Registro e métricas de produtos adquiridos
│ │ ├── ratings/ # Sistema de qualificações, notas e comentários
│ │ ├── representativeActions/ # Ações moderativas do representante em seu setor
│ │ ├── representatives/ # Cadastro e gestão de representantes
│ │ ├── sectors/ # Cadastro e manutenção dos setores regionais
│ │ ├── soldProducts/ # Métricas e relatórios de produtos vendidos
│ │ └── users/ # Perfil de usuário, biografia, avatares e capa
│ ├── shared/ # Recursos compartilhados e infraestrutura
│ │ ├── docs/ # Especificação da API (swagger.json)
│ │ ├── errors/ # Tratamento global de exceções (AppError.ts)
│ │ ├── infra/ # Rotas HTTP, cliente Prisma, seeds e Supabase
│ │ └── middlewares/ # Middlewares de segurança (ensureAuthenticated.ts)
│ └── server.ts # Inicialização do servidor Express
Demonstração Interativa das Telas
Selecione o perfil de uso e o modo de exibição para visualizar a experiência do usuário:
Introdução & Destaques de Engenharia no Front-end
O front-end combina elegância visual com rigor técnico: validações dinâmicas no cliente, visualização gráfica de métricas de vendas, experiência responsiva impecável e alternância instantânea entre Light/Dark Mode.
🚀 Navegação Otimizada
Utilização do Next.js App Router para renderização veloz, rotas dinâmicas e transições fluidas.
✂️ Corte Interativo de Mídia
Integração com react-easy-crop para pré-visualização, zoom e ajuste exato de fotos de perfil (1:1) e capas (4:1) antes do upload.
🔌 Camada de Serviços Unificada
Requisições HTTP fortemente tipadas e centralizadas na pasta services/, separando a lógica da interface.
👤 Autenticação & Contexto Global
Gerenciamento de sessão e contexto do usuário autenticado integrado via AuthContext com suporte aos 4 perfis de uso.
📊 Dashboards Analíticos (Recharts)
Gráficos interativos para monitorar faturamento, volume de itens vendidos, reputação por estrelas e mapas de distribuição regional.
📝 Formulários Performáticos (Hook Form + Zod)
Validação estrita de esquema (preços, categorias, DTOs de cadastro) com tempo de renderização minimizada no React 19.
🎨 Design System Acesível (Radix UI + Tailwind 4)
Componentes atômicos com acessibilidade (ARIA) nativa, animações fluidas e suporte a temas globais com next-themes.
🎠 Vitrines & Experiência de Mídia (Embla Carousel)
Carrossel leve e sensível ao toque no mobile para galeria de produtos, destaques e capas em alta definição.
🔔 Notificações e Feedback (Sonner & Toasts)
Sistema de alertas flutuantes e toasters interativos para confirmações imediatas de ações (compras, vendas, erros e favoritos).
Diagrama de Módulos do Front-end
Módulos & Organização de Código
Vitrine pública aberta a visitantes com filtros de categorias, busca por texto, filtro regional de setores, carrossel de ofertas e grid de produtos.
Página de acesso para membros, representantes e administradores, com validações de entrada e gestão de estado.
Gestão de anúncios, publicação de itens, histórico financeiro de vendas e compras, avaliações recebidas, biografia e corte de foto de perfil/capa.
Painel de supervisão para representantes gerenciarem membros e cadastros vinculados ao seu setor regional específico.
Interface do administrador global para controle total do sistema, mapa de presença, gestão de setores e representantes com Recharts.
Componentes do admin: AdminMetrics, AdminModals, BrazilMap, EditUserModal, RepresentativeModal, RepresentativesTable, SectorModal, SectorsTable e UserTable.
Componentes da vitrine pública: banner-carousel, header, LocationFilterModal, product-card, product-grid, seller-card, seller-grid e sidebar-filters.
Componentes do representante: EditProfileModal, RepresentativeMetrics e SectorUserTable.
Componentes e abas do vendedor: my-ratings-tab, product-image-carousel, product-ratings-dialog, seller-address-dialog, seller-addresses-tab, seller-favorites-tab, seller-product-dialog, seller-products-tab, seller-public-header, seller-purchased-tab e seller-stats-cards.
Biblioteca Radix UI Primitives (Accordion, Dialog, Select, Toast, Tabs, Tooltip, etc.) e provedor next-themes para alternância de temas.
Integração fortemente tipada com Axios: addressesService, adminService, authService, favoritesService, productsService, purchasedProductsService, ratingsService, representativeActionsService, representativesService, sectorsService, soldProductsService e userService.
Estrutura do Repositório (Front-end)
MARKETPLACE-EQUIPISTAS/
├── app/ # App Router (Páginas e Rotas)
│ ├── admin/ # Painel de administração global
│ ├── login/ # Tela de autenticação
│ ├── representative/ # Painel de supervisão do representante de setor
│ ├── vendedores/[id]/ # Perfil público do vendedor
│ ├── vender/ # Painel do Vendedor e publicação de itens
│ ├── globals.css # Estilos globais e temas
│ ├── layout.tsx # Layout raiz com provedores
│ └── page.tsx # Vitrine principal do marketplace (Visitante / Usuário)
├── components/ # Componentização da interface
│ ├── admin/ # Métricas, tabelas, modais e mapa do admin
│ ├── marketplace/ # Vitrine pública, filtros de local/categoria, cards
│ ├── representative/ # Métricas e tabela de membros do setor
│ ├── seller/ # Abas, modais, estatísticas e header do vendedor
│ ├── ui/ # Componentes atômicos de UI (Radix UI)
│ └── theme-provider.tsx # Provedor de Tema (Light / Dark)
├── contexts/ # Contextos React (AuthContext.tsx)
├── hooks/ # Custom Hooks (use-mobile.ts, use-toast.ts)
├── lib/ # Utilitários (cropImage.ts, utils.ts)
├── services/ # Módulos de integração HTTP com a API
└── types/ # Tipagens TypeScript (addresses, admin, representativeActions, sectors, etc.)