Sobre o Projeto
Visão geral e objetivos do sistema
Objetivo
O HRagro PDV é um sistema de ponto de venda completo desenvolvido sob medida para as necessidades da agropecuária HRagro em Piracaia-SP. O sistema gerencia todo o ciclo de vendas — do atendimento ao cliente até o fechamento do caixa — com suporte a múltiplas formas de pagamento, controle de estoque, receituários agronômicos, importação de notas fiscais e relatórios gerenciais.
O desenvolvimento segue um plano de hardening para produção com 18 tarefas organizadas em 5 fases, das quais 14 já foram concluídas, cobrindo segurança, UX, qualidade de backend e infraestrutura.
Dados da Loja
| Razão Social | HRagro |
| Nome Fantasia | HRagro Agropecuária |
| Cidade | Piracaia — SP |
| Telefone | (11) 4036-6393 |
| hragropiracaia@gmail.com | |
| Segmento | Agropecuária / Veterinária |
Números do Sistema
O que já está construído
Arquitetura do Sistema
Tecnologias e camadas da aplicação
Estrutura de Projetos
📁
Hragro.Pdv.Api/ — Backend📁
Hragro.Pdv.Core/ — Entidades📁
Hragro.Pdv.Infra/ — EF Core📁
hragro-pdv-web/ — Angular📁
docker/ — Config Docker
Principais Entidades
ItemVenda Caixa
MovimentoCaixa
VendaParcela Devolucao
ReceituarioAgronomico
DocumentoFiscal Loja
Logging (Serilog)
logs/app-YYYY-MM-DD.log✅ Retenção 30 dias
✅ Eventos auditáveis:
• Login / Logout
• Abertura / Fechamento de caixa
• Vendas realizadas (valor, op.)
• Descontos autorizados
• Devoluções
• Ajustes de estoque
Segurança & Autenticação
JWT + bcrypt + autorização por perfil
Perfis de Usuário
| Perfil | Código | Permissões |
|---|---|---|
| Caixa | 1 |
Registrar vendas, consultar produtos |
| Vendedor | 2 |
Caixa + cadastros básicos |
| Gerente | 3 |
Descontos, cancelamentos, fechar caixa, relatórios |
| Admin | 4 |
Acesso total, configurações, usuários |
O que foi implementado
POST /api/auth/login e POST /api/usuarios/validar-pin não requerem JWT. Todos os demais endpoints rejeitam requisições sem token válido com HTTP 401.
Telas do Sistema
15 páginas completas com guarda de rota
Login
Autenticação via PIN numérico. Suporte a teclado numérico em tablet. Erro genérico sem revelar existência do usuário.
Dashboard
KPIs do dia: faturamento, quantidade de vendas, ticket médio, devoluções, saldo do caixa, alertas de estoque baixo e contas vencidas.
PDV — Ponto de Venda
Tela principal de vendas. Busca de produto por código de barras ou nome (autocomplete ≥3 chars). Atalhos F2/F9/Esc. Múltiplas formas de pagamento.
Histórico de Vendas
Lista paginada com filtros por caixa e data. Totalizadores computados. Visualização de itens, pagamentos e parcelas de cada venda.
Caixa
Abertura com saldo inicial, suprimento e sangria durante o turno, fechamento com saldo calculado automaticamente. Histórico de movimentos.
Estoque
Ajuste manual de estoque, entrada por compra vinculada à nota fiscal, histórico de movimentos por produto com origem rastreada.
Produtos
Cadastro e edição de produtos com validação FluentValidation (NCM 8 dígitos, preço positivo). Filtro por categoria e busca por nome/código.
Clientes
Cadastro com validação de CPF e CNPJ (algoritmo completo). Busca por nome ou documento. Histórico de compras e parcelamentos vinculados.
Devoluções
Registro de devoluções e trocas vinculadas a vendas existentes. Estorno automático no caixa e retorno ao estoque. Motivo documentado.
Receituários Agronômicos
Emissão e consulta de receituários com número, cliente e dados do produto agroquímico. Obrigatório para defensivos agrícolas.
Contas a Receber
Controle de parcelas em aberto por cliente. Identificação de vencidas e vencendo hoje. Baixa manual de pagamento. Resumo financeiro.
Relatórios
Relatório de vendas por período, ranking de produtos mais vendidos e análise por forma de pagamento. Exportável para impressão.
Formas de Pagamento
Cadastro e ativação de formas de pagamento. Configuração de parcelamento por forma. Suporte nativo a Dinheiro, Débito, Crédito e Pix.
Usuários
Cadastro de operadores com perfil (Caixa, Vendedor, Gerente, Admin). PIN configurável com hash automático. Inativação sem exclusão.
Configurações
Dados cadastrais da loja (nome, CNPJ, telefone, endereço, logo). Aparece no cabeçalho dos recibos e documentos emitidos.
Fluxo de Vendas
Do atendimento ao recibo
Passo a passo da venda
Operador informa saldo inicial. Sistema registra abertura com timestamp.
Busca por código de barras, código interno ou nome (autocomplete). F2 abre busca.
Requer validação de PIN de gerente. Registrado com quem autorizou.
Multi-pagamento (ex: parte em dinheiro + parte no pix). Troco calculado automaticamente.
Divide em N parcelas com vencimentos. Vai para Contas a Receber automaticamente.
Modal de recibo exibido após confirmação. Imprime via
window.print() compatível com impressora térmica 80mm.Modelo de Recibo (80mm)
Gestão de Caixa
Controle completo de movimentações financeiras
Abertura de Caixa
Operador informa saldo inicial em dinheiro. Sistema bloqueia abertura de segundo caixa simultâneo. Registrado com data/hora e operador.
Suprimento e Sangria
Adição de troco (suprimento) ou retirada de valores (sangria) durante o turno, com observação opcional e rastreabilidade completa.
Fechamento
Saldo calculado automaticamente: saldo inicial + vendas + suprimentos − sangrias − estornos. Apenas gerentes podem fechar.
Tipos de Movimentação
| Tipo | Sinal | Origem | Quem pode |
|---|---|---|---|
| Abertura | + | Saldo inicial ao abrir o caixa | Qualquer perfil |
| Venda | + | Toda venda realizada no caixa | Automático |
| Suprimento | + | Adição de dinheiro ao caixa | Qualquer perfil |
| Sangria | − | Retirada de dinheiro do caixa | Qualquer perfil |
| Devolução | − | Estorno de venda devolvida | Automático |
| Fechamento | — | Registro de saldo final | Gerente+ |
Estoque & Importação de NF
Controle de estoque com rastreabilidade de movimentos
Controle de Estoque
Importação de Nota Fiscal
Upload de XML diretamente do sistema, com criação ou atualização automática de produtos.
| Tipo | Formato |
|---|---|
| NF-e | XML SEFAZ (namespace nfeProc) |
| NFC-e | XML SEFAZ (nota do consumidor) |
| CF-e SAT | XML CFe SAT fiscal |
| NFS-e | XML padrão ABRASF |
✅
aplicarEstoque=true dá entrada no estoque✅ Log de quantos criados/atualizados
Relatórios Gerenciais
Análises de desempenho para tomada de decisão (acesso exclusivo Gerente+)
Vendas por Período
Total faturado, quantidade de vendas e ticket médio em qualquer intervalo de datas. Agrupamento diário para análise de tendência.
Por Forma de Pagamento
Breakdown de quanto foi recebido em dinheiro, débito, crédito e Pix. Identifica o mix de pagamentos do negócio.
Produtos Mais Vendidos
Ranking dos N produtos com maior faturamento. Quantidade vendida, total faturado e número de vendas por produto.
Integrações
Módulos conectados e stubs prontos para ativação futura
Integrações Implementadas
| Integração | Status | Observação |
|---|---|---|
| Importação NF-e/NFC-e | ✓ Ativo | Parse de XML SEFAZ real |
| Importação CF-e SAT | ✓ Ativo | XML SAT fiscal |
| Impressão de Recibo | ✓ Ativo | Impressora 80mm via CSS |
| PIX (cobrança) | Stub | Requer contrato PSP |
| NF-e / NFC-e Emissão | Stub | Requer certificado A1/A3 |
| Balança | Stub | Interface pronta |
| Impressora Fiscal | Stub | Interface pronta |
Receituário Agronômico
Módulo específico para agropecuárias — obrigatório para venda de defensivos agrícolas pela legislação brasileira (Decreto 4.074/2002).
API Endpoints
Referência completa da API REST (.NET 8 Minimal APIs)
https://hragro.ajudei.com.br/api/ |
Autenticação: Todos os endpoints (exceto /auth/login) requerem header Authorization: Bearer <jwt>
| Método | Endpoint | Descrição | Auth |
|---|---|---|---|
| POST | /api/auth/login | Login via PIN — retorna JWT + dados do usuário | Público |
| POST | /api/usuarios/validar-pin | Valida PIN com perfil mínimo (ex: desconto) | Público |
| Método | Endpoint | Descrição | Auth |
|---|---|---|---|
| GET | /api/produtos?busca=&categoria=&page=&pageSize= | Listar produtos com busca e paginação | JWT |
| GET | /api/produtos/{id} | Buscar produto por ID | JWT |
| GET | /api/produtos/barcode/{codigo} | Buscar por código de barras ou código interno | JWT |
| POST | /api/produtos | Cadastrar produto (com validação FluentValidation) | JWT |
| PUT | /api/produtos/{id} | Atualizar produto | JWT |
| DELETE | /api/produtos/{id} | Inativar produto (soft delete) | Gerente |
| Método | Endpoint | Descrição | Auth |
|---|---|---|---|
| POST | /api/vendas | Registrar venda (multi-pagamento, troco, parcelamento) | JWT |
| GET | /api/vendas?caixaId=&data=&page=&pageSize= | Listar vendas com filtros e paginação | JWT |
| GET | /api/vendas/{id} | Detalhar venda com itens, pagamentos e parcelas | JWT |
| Método | Endpoint | Descrição | Auth |
|---|---|---|---|
| POST | /api/caixa/abrir | Abrir caixa com saldo inicial | JWT |
| GET | /api/caixa/aberto | Obter caixa em aberto (se existir) | JWT |
| POST | /api/caixa/fechar/{id} | Fechar caixa com cálculo de saldo | Gerente |
| POST | /api/caixa/suprimento | Registrar suprimento | JWT |
| POST | /api/caixa/sangria | Registrar sangria | JWT |
| GET | /api/caixa | Listar últimos 30 caixas | JWT |
| GET | /api/caixa/{id}/movimentos | Movimentos de um caixa | JWT |
| Método | Endpoint | Descrição | Auth |
|---|---|---|---|
| GET | /api/dashboard | KPIs do dia (faturamento, estoque, caixa) | Gerente |
| GET | /api/relatorios/vendas | Relatório por período com agrupamento diário | Gerente |
| GET | /api/relatorios/formas-pagamento | Breakdown por forma de pagamento | Gerente |
| GET | /api/relatorios/produtos | Ranking de produtos mais vendidos | Gerente |
Outros Endpoints
GET/POST/PUT/DELETE | /api/clientes |
GET/POST/PUT/DELETE | /api/usuarios |
GET/POST/PUT/DELETE | /api/formas-pagamento |
GET/PUT | /api/loja |
POST/GET | /api/estoque/ajustar, entrada, movimentos |
POST/GET | /api/devolucoes |
POST/GET | /api/receituarios |
GET/POST | /api/contas-receber |
POST | /api/importacoes/notas, produtos |
GET | /api/categorias |
GET/POST | /api/pix/cobrancas (stub) |
GET/POST | /api/fiscal/emitir, documentos (stub) |
Padrão de Resposta
O sistema segue padrões REST e RFC 7807 para erros:
{
"items": [...],
"total": 150,
"page": 1,
"pageSize": 20,
"totalPages": 8,
"hasNext": true
}
{
"type": "validation-error",
"title": "Erro de Validação",
"status": 400,
"errors": {
"Nome": ["O nome é obrigatório"]
}
}
Qualidade de Backend
Robustez, validação e rastreabilidade em produção
Global Exception Middleware
Todas as exceções não tratadas são capturadas e retornam ProblemDetails RFC 7807 com status HTTP correto. Nenhum stack trace vaza para o cliente em produção.
FluentValidation
Validação de entidades com regras de negócio: CPF e CNPJ por algoritmo, NCM com 8 dígitos, preço positivo, desconto máximo 50%, estoque não-negativo.
Serilog Structured Logging
Logs estruturados com MachineEnricher e contexto de request. Arquivo rotativo diário com 30 dias de retenção. Fácil integração futura com Seq ou Datadog.
Paginação
PagedResult<T> genérico em todos os endpoints de lista. Parâmetros ?page=1&pageSize=20. Metadados: total, totalPages, hasNext, hasPrev.
Swagger UI
Documentação automática de todos os endpoints em desenvolvimento (/swagger). Todos os endpoints têm summary e description configurados.
EF Core + Migrations
Banco de dados versionado com migrations automáticas. Seed automático de formas de pagamento, produtos demo e usuários iniciais na primeira execução.
Infraestrutura
Docker Compose + Nginx + PostgreSQL no servidor OVH
Docker Compose (Produção)
PostgreSQL 16 Alpine
volume persistente
healthcheck automático
Build via Dockerfile
Aguarda banco estar saudável
Ambiente: Production
Build via Dockerfile
Serve a aplicação web
depends_on: api
Roteamento Nginx
| Rota | Destino | Descrição |
|---|---|---|
/api/* | API interna | .NET 8 API |
/* | Frontend interno | Angular SPA |
✅ Acesso externo somente via HTTPS
✅ Banco de dados não exposto na rede pública
✅ Restart automático em caso de falha
GET /health em desenvolvimento.
Plano de Entrega — Production Hardening
18 tarefas organizadas em 5 fases — 14 concluídas
Fase 1 — Segurança & Autenticação ✓ Completa
Tornar o sistema seguro para produção — nenhum endpoint acessível sem autenticação válida.
Fase 2 — UX/UI Design System ✓ Completa
Experiência consistente com Angular Material M3 e funcionalidades de UX faltantes implementadas.
Fase 3 — Qualidade de Backend ✓ Completa
Robustez, manutenibilidade e rastreabilidade em produção.
Fase 4 — Testes Automatizados Em progresso
Cobertura mínima de 70% em código crítico — backend e frontend.
Fase 5 — Infraestrutura & CI/CD Pendente
Pipeline automatizado e deploy confiável.
GET /health) + GitHub Actions CI