Stack tecnológica

Produto: GV - Gestor de Vendas
Última atualização: 25/07/2026
Referência: código e dependências do repositório gv-dbai

Este documento lista as tecnologias usadas no projeto, a finalidade de cada uma e o estado atual de adoção. Versões indicadas correspondem às versões declaradas no repositório.

Resposta rápida

O GV - Gestor de Vendas é uma aplicação web em TypeScript, organizada como um monorepo npm com dois componentes implantáveis:

• frontend React 19 com TanStack Start, TanStack Router, TanStack Query, Vite e Tailwind CSS;
• backend REST em Node.js 22 e NestJS 10;
• PostgreSQL 16 com Prisma 6;
• Redis 7 provisionado para evolução de filas e processamento assíncrono;
• autenticação JWT, controle de acesso por perfil e escopo de lojas;
• integração REST com o ERP Protheus;
• operação em VPS Linux com CloudPanel e HTTPS.

Visão arquitetural

Navegador / tablet
        |
        | HTTPS
        v
Frontend React + TanStack Start
        |
        | REST JSON / Bearer JWT
        v
API Node.js + NestJS
        |
        +---- PostgreSQL 16 / Prisma
        |
        +---- Protheus REST
        |
        +---- Redis 7 (provisionado para evolução)

O backend é um monólito modular NestJS. Não há microserviços separados no estado atual. Frontend e API são aplicações distintas e possuem domínio, processo e porta próprios no ambiente de homologação.

Runtime e linguagem

Node.js 20.19+ também é compatível segundo a configuração do projeto, mas o ambiente atual utiliza Node.js 22.

Frontend

Núcleo da aplicação

Interface e design system

Outros componentes de interface:

• cmdk para menus de comando;
• vaul para drawers;
• embla-carousel-react para carrosséis;
• react-day-picker para calendários;
• react-resizable-panels para painéis redimensionáveis;
• input-otp para campos de código;
• @dnd-kit/core para arrastar vendedores na lista da vez.

Formulários, dados e utilitários

Tablet, PWA e operação offline

O tablet funciona como experiência web/PWA. Eventos de atendimento são armazenados no IndexedDB quando necessário e enviados em lote à API.

Backend

Plataforma

Arquitetura da API

• API REST com prefixo versionado /api/v1;
• controllers NestJS por domínio;
• services para regras de negócio;
• Prisma para persistência;
• JSON como formato principal;
• multipart/form-data para planilhas e fotos;
• arquivos de fotos em diretório persistente e somente a URL no banco;
• CORS configurável por ambiente;
• health check em /api/v1/health;
• logs de integração e trilha de auditoria persistidos no banco.

Módulos implementados:

• autenticação;
• empresas, lojas, usuários e vendedores;
• metas e distribuição diária;
• campanhas e motivos de perda;
• feriados, lotações, transferências e ausências;
• tablet, eventos e atendimentos;
• vendas e importações;
• validação diária e Validador NF;
• dashboard, relatórios e feedbacks;
• configurações, auditoria e integração Protheus.

Autenticação e segurança

Papéis principais:

• SUPER_ADMIN e ADMIN;
• DIRECTOR;
• REGIONAL_MANAGER;
• STORE_MANAGER;
• SELLER;
• DEVICE.

Banco de dados

Recursos de persistência:

• schema Prisma versionado;
• migrations incrementais;
• seed de desenvolvimento/homologação;
• restrições e chaves únicas;
• auditoria de alterações;
• logs de integração;
• armazenamento do payload recebido do Protheus;
• controle de versões e divergências de NF.

Redis e processamento assíncrono

O Redis faz parte da infraestrutura preparada, porém a API atual não o consome. O agendador Protheus utiliza um temporizador interno do processo NestJS. Para produção com múltiplas instâncias, é recomendado migrar os trabalhos agendados e filas para um mecanismo distribuído baseado em Redis.

Integrações e arquivos

Protheus

IBGE Localidades

Planilhas

• formatos aceitos: XLSX, XLS e CSV;
• biblioteca: SheetJS xlsx;
• upload multipart;
• limite atual de 10 MB;
• importação de vendas e script de importação de metas;
• relatório de linhas criadas, atualizadas e rejeitadas.

Infraestrutura local

PostgreSQL e Redis sobem com Docker Compose:

npm run dev:infra

Frontend e API são executados separadamente:

npm run dev:web
npm run dev:api

Hospedagem e deploy

Ambiente atual de homologação

Domínios da homologação:

• frontend: https://technos.projeto.dbai.com.br;
• API: https://api.technos.projeto.dbai.com.br/api/v1.

O uso de vite preview é adequado para a homologação atual, mas deve ser substituído por um runtime final validado antes da produção definitiva.

Cloudflare

O repositório contém:

• @cloudflare/vite-plugin;
• configuração wrangler.jsonc;
• compatibilidade nodejs_compat.

Essa configuração prepara o build para Cloudflare, mas o ambiente de homologação atual está na VPS/CloudPanel. Cloudflare não é a hospedagem operacional atual.

Desenvolvimento e qualidade

Comandos principais:

npm install
npm run dev:web
npm run dev:api
npm run build
npm run build:api
npm run lint
npm run format

Estado dos testes e automação

Antes de produção definitiva, recomenda-se priorizar testes automatizados dos fluxos de autenticação, permissões, metas, integração Protheus, validações e tablet.

O que não faz parte da stack atual

Para evitar respostas imprecisas:

• não há arquitetura de microserviços;
• não há Kubernetes;
• não há BullMQ ou fila Redis conectada à API;
• não há código Android nativo específico de negócio; o APK usa Capacitor/WebView;
• não há Swagger/OpenAPI gerado;
• não há suíte Playwright, Cypress, Vitest ou Jest configurada;
• não há armazenamento S3 ou serviço equivalente configurado;
• não há pipeline CI/CD versionado no repositório;
• Cloudflare está preparado no build, mas não hospeda a homologação atual.

Arquivos que comprovam a stack

Perguntas e respostas rápidas

Qual é a stack principal?
React, TypeScript, TanStack Start, Vite, Tailwind CSS, NestJS, Prisma e PostgreSQL.

É SPA ou SSR?
O frontend usa TanStack Start e possui entrada de servidor compatível com SSR. A operação atual também utiliza navegação cliente e consumo de API REST.

É monolito ou microserviços?
É um monorepo com frontend e API separados. A API é um monólito modular NestJS.

Qual banco é usado?
PostgreSQL 16, acessado pelo Prisma 6.

Como funciona a autenticação?
JWT com access e refresh tokens, senhas/PINs em scrypt, papéis e escopo por loja.

Tem integração com ERP?
Sim. O Protheus é consumido por REST com sincronizações horária, diária e mensal.

O tablet funciona offline?
Os eventos operacionais usam IndexedDB e sincronização em lote quando a conexão volta. Não há service worker avançado configurado.

Redis é usado?
Está provisionado, mas ainda não conectado ao código. É a base prevista para filas e jobs distribuídos.

Onde está hospedado?
A homologação está em VPS Linux com CloudPanel, Node.js, Docker, PostgreSQL e Redis.

Existe aplicativo Android?
Sim. A experiência web/tablet está empacotada com Capacitor 6. O APK aceita instalação técnica a partir do Android 5.1 (minSdkVersion 22), mas o mínimo operacional indicado é Android 10, 3 GB de RAM e 32 GB; para novas compras, recomenda-se Android 12 ou superior, 4 GB de RAM e 64 GB.

Existem testes automatizados?
Ainda não há suíte configurada. O projeto possui lint, build e roteiros de QA manual.