Hórus PDV

Hórus PDV é um PDV grátis para frente de caixa e gestão operacional de pequenos e médios comércios.

O projeto está em evolução ativa, com sistema de cadastro grátis para clientes, fornecedores e produtos, controle de estoque, vendas, caixa e relatórios. A base usa frontend em React, API em ASP.NET Core e persistência em SQL Server para os dados operacionais principais.

Página inicial do projeto: https://flaviooliveira-code.github.io/horus_pdv/

Sumário

• Status do Projeto
• Stack
• Funcionalidades
• Screenshots
• Estrutura
• Quick Start
• Variáveis de Ambiente
• Scripts
• Smoke Test
• Validação Local
• Autenticação e Segurança
• Padrões de Interface
• Módulos em Desenvolvimento
• Roadmap
• Contribuindo
• Licença
• Autor

Status do Projeto

Este repositório está em fase de desenvolvimento. O frontend já conversa com a API .NET e a API cria o banco HorusPdv no SQL Server local quando a aplicação sobe.

Stack

Frontend

• React 19
• TypeScript
• Vite
• Tailwind CSS
• Lucide React
• Recharts

Backend

• .NET 8
• ASP.NET Core Web API
• Swagger
• JWT em cookie HttpOnly
• Rate limit local
• Acesso manual ao SQL Server com Microsoft.Data.SqlClient
• SQL Server

Funcionalidades

• Login com sessão JWT em cookie HttpOnly.
• Cadastro público por CNPJ.
• Recuperação e redefinição de senha.
• Gestão de clientes, fornecedores e produtos.
• Frente de caixa com carrinho, pagamento e baixa de estoque.
• Abertura e fechamento de caixa.
• Histórico de vendas com valores, reimpressão e prévia de cupom não fiscal.
• Relatórios.
• Minha empresa, licença, perfil e configurações.
• Gestão de usuários.
• Gestão avançada: estoque, abertura/fechamento, compras, trocas/devoluções, CRM/fidelidade e omnichannel.
• Configuração SMTP por empresa.
• Tour guiado por tela.
• Temas light/dark.

Screenshots

Para visualizar em formato de slides, abra a página inicial e clique em qualquer screenshot:

https://flaviooliveira-code.github.io/horus_pdv/

Login	Dashboard
Clientes	Fornecedores
Produtos	Usuários
Frente de Caixa	Histórico de Vendas
Relatórios	Fiscal
Pagamentos Integrados	Estoque e Inventário
Abertura e Fechamento	Compras e Reposição
Trocas e Devoluções	CRM e Fidelidade
Omnichannel	Minha Empresa
Detalhes da Licença	Sobre PDV
Configurações	Perfil

Estrutura

horus_pdv/
├── API/
│   └── NETCORE/          # API ASP.NET Core
├── FRONTEND/             # Aplicação React + Vite
├── LICENSE
└── README.md

Quick Start

Requisitos

• Node.js 20+
• npm 10+
• .NET SDK 8+

1. Clonar o projeto

git clone https://github.com/flaviooliveira-code/horus_pdv.git
cd horus_pdv

2. Configurar o frontend

cd FRONTEND
cp .env.example .env
npm install

3. Subir a API .NET

O projeto espera um SQL Server local na porta 1433. Exemplo com Docker:

docker run -d \
  --name sqlserver2025 \
  -e ACCEPT_EULA=Y \
  -e SA_PASSWORD='Senha@12345' \
  -p 1433:1433 \
  mcr.microsoft.com/mssql/server:2025-latest

Se o container já existir e estiver parado:

docker start sqlserver2025

Em outro terminal:

cd API/NETCORE
dotnet restore
dotnet run --urls http://localhost:5260

Swagger local:

http://localhost:5260/swagger

4. Subir o frontend

cd FRONTEND
npm run dev

URL local padrão:

http://localhost:5173

Variáveis de Ambiente

O frontend usa um arquivo .env para mapear os endpoints da API.

Exemplo:

VITE_AUTH_API_URL=http://localhost:5260/api/Auth
VITE_PRODUTO_API_URL=http://localhost:5260/api/Produto
VITE_CLIENTE_API_URL=http://localhost:5260/api/Cliente
VITE_FORNECEDOR_API_URL=http://localhost:5260/api/Fornecedor
VITE_EMPRESA_API_URL=http://localhost:5260/api/Empresa
VITE_CAIXA_API_URL=http://localhost:5260/api/Caixa
VITE_HISTORICO_VENDAS_API_URL=http://localhost:5260/api/HistoricoVendas
VITE_RECAPTCHA_SITE_KEY=

Arquivos disponíveis:

• FRONTEND/.env.example
• FRONTEND/.env.development
• FRONTEND/.env.prod

Na API, API/NETCORE/appsettings.json fica sem segredos reais. Para desenvolvimento local, use API/NETCORE/appsettings.Development.json, variáveis de ambiente ou User Secrets. Em produção, configure connection string, Auth:JwtSecret, Security:EncryptionKey, CORS, reCAPTCHA e SMTP fora do repositório.

Scripts

Frontend

cd FRONTEND
npm run dev          # servidor local Vite
npm run dev:dev      # Vite em modo development
npm run dev:prod     # Vite em modo prod
npm run lint         # ESLint
npm run build:dev    # build usando env de desenvolvimento
npm run build:prod   # build usando env de produção
npm run preview      # preview do build
npm run smoke         # smoke test frontend + API
npm run smoke:headed  # smoke test com navegador visível
npm run smoke:keep    # smoke com navegador visível e dados mantidos para conferência
npm run demo:video    # grava docs/videos/horus-pdv-demo.webm para o GitHub Pages

Para ajustar o ritmo do vídeo demonstrativo:

DEMO_SLOW_MO=320 DEMO_PAUSE_MULTIPLIER=1.55 npm run demo:video

API .NET

cd API/NETCORE
dotnet restore
dotnet build
dotnet run --urls http://localhost:5260

Smoke Test

O smoke test sobe a API e o frontend automaticamente, cria uma conta pública, autentica com cookie HttpOnly, valida navegação, executa operações principais via API e limpa os dados criados com prefixo SMOKE_.

Pré-requisito: Docker Desktop e SQL Server local precisam estar rodando antes da execução.

Primeiro uso na máquina:

cd FRONTEND
npm run smoke:install
npm run smoke

Execução recorrente:

cd FRONTEND
npm run smoke

Execução para conferir dados no banco:

cd FRONTEND
npm run smoke:keep

Variáveis opcionais:

• SMOKE_APP_URL, padrão http://localhost:5173.
• SMOKE_API_URL, padrão http://localhost:5260/api.
• SMOKE_SQL_CONTAINER, padrão sqlserver2025.
• SMOKE_SQL_PASSWORD, padrão Senha@12345.
• SMOKE_KEEP_DATA=1, mantém os dados criados no banco para conferência manual.

O SQL Server Docker precisa estar rodando. O teste exige que o container configurado esteja com estado running; se ele estiver parado, o smoke falha antes de tentar docker exec. O teste desativa temporariamente o disparo real de e-mail da empresa durante a execução e restaura a configuração ao final. A validação de reset de senha não depende de SMTP externo.

Se o smoke falhar com erro de conexão no SQL Server, suba o Docker Desktop e inicie o container:

open -a Docker
docker start sqlserver2025

O script smoke:keep usa SMOKE_RUN_ID=SMOKE_CONFERE e SMOKE_KEEP_DATA=1. Se quiser outro prefixo manualmente:

cd FRONTEND
SMOKE_RUN_ID=SMOKE_CONFERE SMOKE_KEEP_DATA=1 npm run smoke

Depois procure no banco por SMOKE_CONFERE% em Usuarios, Clientes, Fornecedores, Produtos, Vendas, CaixaSessoes e ModuloMercadoRegistros.

Validação Local

Última validação local executada em 10/06/2026:

dotnet build API/NETCORE/HORUSPDV-API.sln
cd FRONTEND
npm run build
npm run smoke

Resultado: build da API, build do frontend e smoke test completo passaram.

Observação: durante a validação, o smoke encontrou um caixa antigo aberto fora do período permitido. O teste foi ajustado para fechar caixa expirado antes de abrir o caixa da execução atual, preservando a regra de negócio da API.

Autenticação e Segurança

O projeto já possui uma base de segurança para desenvolvimento:

• JWT assinado com sessão persistida.
• Cookie HttpOnly para sessão autenticada; o frontend não armazena token JWT em localStorage.
• Middleware de autenticação com suporte a cookie e Bearer token legado.
• Controle de sessão ativa.
• Rate limit local.
• Bloqueio por tentativas inválidas de login.
• Recuperação de senha por token temporário.
• reCAPTCHA v3 opcional para login, cadastro e recuperação de senha.
• CORS configurado para ambientes locais do frontend com credenciais.
• Swagger disponível apenas em ambiente Development.

Importante: antes de produção, defina Auth:JwtSecret, Security:EncryptionKey, connection string, CORS e reCAPTCHA por variável de ambiente ou secret manager. Não versionar segredos reais.

Padrões de Interface

Para escolhas booleanas voltadas ao usuário final, use sempre o controle segmentado Sim/Não, no padrão visual da página de Configurações.

Componente padrão:

FRONTEND/src/components/Form/YesNoSegmentedControl.tsx

Uso:

import { YesNoSegmentedControl } from "@/components/Form";
<YesNoSegmentedControl
value={enabled}
onChange={setEnabled}
ariaLabel="Ativar recurso"
/>

Não use checkbox cru para preferências como "ativar/desativar", "mostrar/ocultar", "enviar/não enviar" ou decisões equivalentes de Sim/Não.

Módulos em Desenvolvimento

Algumas áreas aparecem no menu para indicar a direção do produto, mas ainda não devem ser usadas em operação real:

• Fiscal NFC-e / NF-e.
• Pagamentos integrados.

Essas páginas mostram estado visual de "Em desenvolvimento" até as integrações e homologações ficarem prontas.

Dados e Persistência

A API usa SQL Server com scripts manuais, seguindo o padrão de DataBase/Resumo.sql. No start, a aplicação executa esse script para criar o banco, tabelas, relacionamentos e dados iniciais quando ainda não existirem.

O script também aplica ajustes seguros de schema já existentes e faz backfill de valores de vendas antigas quando VendaItens.UnitPrice ou VendaItens.ItemTotal ainda estiverem vazios/zerados.

Banco padrão:

HorusPdv

Tabelas principais:

• Usuarios, Sessoes, PasswordResetTokens
• Produtos, Fornecedores, Clientes
• Empresas
• CaixaSessoes
• Vendas, VendaItens
• ModulosMercado, ModuloMercadoRegistros

Script principal:

API/NETCORE/DataBase/Resumo.sql

Roadmap

• Versionar evoluções de banco em scripts SQL incrementais.
• Expandir seeds e rotinas de migração manual.
• Expandir testes automatizados.
• Consolidar regras fiscais.
• Integrar TEF/provedores de pagamento.
• Melhorar documentação técnica da API.
• Criar guias de deploy.

Contribuindo

Contribuições são bem-vindas.

Fluxo sugerido:

git checkout -b feature/minha-melhoria
npm --prefix FRONTEND run lint
npm --prefix FRONTEND run build:prod
dotnet build API/NETCORE

Antes de abrir um pull request:

• Explique o problema resolvido.
• Liste arquivos ou módulos impactados.
• Informe como validou a mudança.
• Evite misturar refatorações grandes com correções pequenas.

Licença

Este projeto está sob licença MIT. Consulte LICENSE.

Autor

Criado por Flávio Oliveira.

• GitHub: https://github.com/flaviooliveira-code
• LinkedIn: https://www.linkedin.com/in/fladoliveira