🛒 SAECOMP Lojinha - Backend API

Backend da aplicação da Lojinha do SAECOMP, desenvolvida para gerenciar um sistema de e-commerce interno com funcionalidades de carrinho, pagamentos via PIX e sistema de pontuação.

📋 Descrição

Esta API REST fornece todas as funcionalidades necessárias para o funcionamento da lojinha online do SAECOMP, incluindo:

• Gerenciamento de Produtos: CRUD completo de produtos com categorias
• Sistema de Carrinho: Adicionar, remover e gerenciar itens no carrinho
• Pagamentos: Integração com Mercado Pago para pagamentos PIX
• Sistema de Pontuação: Controle de pontos dos usuários
• Comentários: Sistema de avaliações e comentários
• Autenticação: Controle de acesso baseado em permissões
• Painel Administrativo: Gerenciamento completo da loja

🚀 Tecnologias

• Node.js com TypeScript
• Express.js - Framework web
• PostgreSQL - Banco de dados
• Zod - Validação de schemas
• Mercado Pago SDK - Integração de pagamentos e geração de códigos PIX
• Multer - Upload de arquivos

📁 Estrutura do Projeto

src/
├── controllers/          # Controladores das rotas
│   ├── admin/           # Controladores administrativos
│   └── client/          # Controladores do cliente
├── repositories/        # Camada de dados
├── services/           # Serviços externos
├── middlewares/        # Middlewares personalizados
├── schemas/           # Validação com Zod
├── routers/           # Definição das rotas
├── interfaces/        # Tipos TypeScript
├── database/         # Conexão com banco
└── errors/          # Tratamento de erros

🔧 Instalação e Configuração

Pré-requisitos

• Node.js (v16+)
• PostgreSQL
• npm

1. Clone o repositório

git clone https://github.com/SAEComp/site-saecomp-back-lojinha.git
cd site-saecomp-back-lojinha

2. Instale as dependências

npm install

3. Configure as variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

# Banco de dados
DB_HOST=localhost
DB_PORT=5432
DB_NAME=saecomp_lojinha
DB_USER=your_user
DB_PASSWORD=your_password

# Servidor
PORT=3000

4. Configure o banco de dados

Execute o script SQL para criar as tabelas:

psql -U your_user -d saecomp_lojinha -f create_tables.sql

5. Inicie o servidor

# Desenvolvimento
npm run dev

# O servidor estará rodando em http://localhost:3000

📚 Documentação da API

Documentação interativa (Swagger)

Uma documentação interativa (Swagger UI) está disponível enquanto o servidor estiver rodando em:

• http://localhost:3000/api/lojinha/docs

Ela permite testar endpoints, ver schemas de request/response e executar chamadas diretamente do navegador.

Endpoints Principais

🛍️ Produtos

• GET /api/lojinha/products - Lista produtos com paginação
• GET /api/lojinha/product - Detalhes de um produto
• POST /api/lojinha/admin/product - Criar produto (admin)
• PUT /api/lojinha/admin/product - Editar produto (admin)
• DELETE /api/lojinha/admin/product - Remover produto (admin)
• POST /api/lojinha/admin/product/image - Upload da imagem do produto (admin)

🛒 Carrinho

• GET /api/lojinha/cart - Visualizar carrinho
• POST /api/lojinha/cart - Adicionar item ao carrinho
• DELETE /api/lojinha/cart - Limpar carrinho
• DELETE /api/lojinha/item - Remover item específico

Endpoints adicionais de cliente:

• GET /api/lojinha/pending-payments - Listar pagamentos pendentes do usuário
• POST /api/lojinha/register-payment - Registrar pagamento manual (ex.: quando confirmado fora do fluxo automático)

💳 Pagamentos

• POST /api/lojinha/finish-order - Finalizar pedido
• GET /api/lojinha/listen-payment - Verificar status do pagamento
• POST /api/lojinha/confirm-payment - Webhook Mercado Pago
• POST /api/lojinha/register-payment - Registrar pagamento manual

Notas sobre pagamentos:

• O fluxo principal utiliza Mercado Pago para gerar preferências/QR codes PIX. O projeto possui um endpoint que recebe webhooks do Mercado Pago (POST /api/lojinha/confirm-payment) e atualiza pedidos automaticamente.
• Há também endpoints de escuta de eventos (GET /api/lojinha/listen-payment) para que o front possa receber os estados de pagamento de um pedido finalizado.

⭐ Pontuação

• GET /api/lojinha/punctuation - Ver pontuação do usuário
• GET /api/lojinha/punctuations - Ranking de pontuações

💬 Comentários

• POST /api/lojinha/comment - Adicionar comentário

🔧 Administração

• GET /api/lojinha/admin/statistics - Estatísticas da loja
• GET /api/lojinha/admin/orders - Gerenciar pedidos
• GET /api/lojinha/admin/entry-history - Histórico de entradas
• POST /api/lojinha/admin/pix-key - Configurar chave PIX

Rotas administrativas adicionais (além das listadas acima):

• GET /api/lojinha/admin/pix-key - Recuperar chave PIX configurada
• DELETE /api/lojinha/admin/pix-key - Remover chave PIX
• DELETE /api/lojinha/admin/product - Remover produto (aceita id)

Permissões

O sistema usa permissões granulares:

• lojinha:product-home - Ver produtos
• lojinha:cart - Gerenciar carrinho
• lojinha:finish-order - Finalizar pedidos
• lojinha:admin - Acesso administrativo

🗄️ Esquema do Banco de Dados

Tabelas Principais

• products: Catálogo de produtos
• buy_orders: Pedidos dos usuários
• items: Itens dos pedidos
• punctuations: Pontuação dos usuários
• comments: Comentários dos produtos
• pix_keys: Chaves PIX para pagamento
• entry_histories: Registros de entrada/saída de estoque por produto
• pix_payments: Dados do pagamento PIX associados a um pedido

Tipos Enums

• category_t: 'sweet', 'salty', 'drink'
• status_t: 'cart', 'pendingPayment', 'canceled', 'finishedPayment'

🔄 Fluxo de Pagamento

1. Adicionar produtos ao carrinho
2. Finalizar pedido → Gera QR Code PIX e e itens são decrementados do estoque
3. Usuário paga via PIX
4. Webhook ou endpoint de registro confirma pagamento
5. Pedido atualizado para "finishedPayment"
6. Pontos creditados ao usuário (quando aplicável)

📦 Scripts Disponíveis

# Desenvolvimento com hot reload
npm run dev

Outros scripts úteis (ver package.json):

• npm run build - Compila TypeScript
• npm start - Inicia o build compilado

Ver também o script auxiliar update-sub.sh que é usado para deploy/atualização em servidores de staging/produção simples.

👥 Equipe

Desenvolvido pela equipe do SAECOMP - Secretaria Acadêmica de Engenharia de Computação.

Para mais informações ou suporte, entre em contato com a equipe do SAECOMP.