Skip to content
BranchesTags

Repository files navigation

SIGMA — Sistema Integrado de Gestão Empresarial (ERP)

Node.js Fastify TypeScript Prisma PostgreSQL Docker React Material_UI Biome

Sistema de Gestão Empresarial (ERP) modular e desacoplado, focado em alta performance, consistência transacional e segurança rigorosa. Projetado para gerenciar operações completas de distribuição e manufatura: múltiplos armazéns, controle de estoque com reservas, catálogo hierárquico com variações dinâmicas de SKU, ciclo de vida de pedidos de compra e venda, controle de acesso baseado em funções (RBAC) e trilha de auditoria imutável.

Sumário

  1. Visão Geral e Contexto
  2. Destaques de Engenharia e Decisões de Arquitetura
  3. Arquitetura do Sistema
  4. Modelagem de Dados e Entidades
  5. Matriz de Controle de Acesso (RBAC)
  6. Catálogo Completo de Endpoints (API REST)
  7. Segurança e Tratamento de Exceções
  8. Frontend SPA (React 19 + MUI)
  9. Instalação e Execução
  10. Documentação Interativa (Swagger)
  11. Scripts do Projeto

Visão Geral e Contexto

O SIGMA foi desenvolvido como um projeto full-stack de nível empresarial para resolver os principais gargalos operacionais de empresas que lidam com múltiplos centros de distribuição e alta rotatividade de inventário:

  • Controle de Estoque Preciso: Separação lógica entre estoque físico disponível, estoque reservado para pedidos em processamento e limites de reposição (estoque mínimo).
  • Rastreabilidade de Movimentações: Registro obrigatório de tipo, quantidade, operador e documento de referência em cada movimentação física de mercadorias.
  • Flexibilidade de Catálogo: Suporte a produtos genéricos com múltiplos SKUs contendo atributos técnicos em JSON dinâmico (tensão, cor, lote, memória) e cubagem volumétrica (peso, largura, altura, profundidade).
  • Conformidade e Auditoria: Trilha de auditoria imutável (append-only) para ações críticas de sistema (criação, edição, deleção lógica e autenticação).

Destaques de Engenharia e Decisões de Arquitetura

Decisão Tecnologia / Abordagem Justificativa Técnica
HTTP Framework Fastify v5 Desempenho significativamente superior ao Express devido à arquitetura assíncrona baseada em eventos, compilação de schemas JSON e overhead mínimo de ciclo de vida.
Acesso a Dados Prisma ORM v7 + PostgreSQL 15 Segurança estrita de tipos em tempo de compilação (Type-safe queries), suporte a migrações declarativas versionadas e chave primária composta nativa.
Padrão de Camadas Controller-Repository-Schema Separação explícita de responsabilidades: validação na borda (Zod), orquestração HTTP (Controllers), abstração de persistência (Repositories) e integridade de banco (Prisma).
Criptografia de Senhas Argon2id Vencedor do Password Hashing Competition. Oferece resistência a ataques por hardware dedicado (ASIC/GPU) via parametrização de memória e tempo (t=3, m=65536, p=4).
Prevenção de Timing Attacks Dummy Hash Fallback Verificação temporal constante na autenticação: se o e-mail não existir, o sistema processa um hash falso para evitar enumeração de usuários por discrepância de latência.
Validação e Sanitização Zod Schemas Validação estrita de contratos de entrada, regex para bloqueio de tags HTML (prevenção a XSS armazenado), validação de formato de CPF/CNPJ e estados brasileiros (UF).
Controle de Acesso RBAC Granular Permissões atômicas por escopo (INVENTORY_READ, SALES_WRITE, etc.) com verificação via middleware na API e guardas de rota no frontend.
Auditoria Imutável Append-Only Logs O módulo de auditoria não possui rotas de alteração (PUT/PATCH) ou remoção (DELETE), garantindo histórico fidedigno de auditoria forense.

Arquitetura do Sistema

flowchart TD
    subgraph Client ["Frontend Client (SPA)"]
        UI["React 19 + Material UI"]
        RTR["React Router v7 (PermissionRoute)"]
        CTX["AuthContext (JWT Session)"]
        AX["Axios Client (Bearer Interceptor)"]
    end

    subgraph Backend ["Backend API (Fastify v5)"]
        MW["Middlewares (Helmet, CORS, RateLimit)"]
        AUTH["JWT Verification & RBAC Guard"]
        CTRL["Controllers (HTTP Handlers)"]
        VAL["Zod Schemas (Contract & XSS Sanitization)"]
        REP["Repositories (Domain Data Access)"]
        ERR["Global Error Handler (Prisma/Zod/JWT)"]
    end

    subgraph Database ["Persistence Layer"]
        PRISMA["Prisma ORM Client"]
        PG[("PostgreSQL 15 (Docker)")]
    end

    UI --> RTR
    RTR --> CTX
    CTX --> AX
    AX -- "HTTPS / JSON" --> MW
    MW --> AUTH
    AUTH --> VAL
    VAL --> CTRL
    CTRL --> REP
    REP --> PRISMA
    PRISMA --> PG
    CTRL -. "Exceções" .-> ERR
Loading

Modelagem de Dados e Entidades

O modelo relacional é estruturado para garantir integridade referencial estrita e isolamento transacional.

Diagrama UML

O diagrama vetorial completo está disponível em UML.pdf.

Dicionário de Entidades Principais

  1. User & Role:
    • Controle de operadores do sistema. Cada operador possui um vínculo obrigatório com uma Role, que define a lista de permissões (String[]).
  2. Category, Brand, Product & SKUItem:
    • Hierarquia de catálogo: Category (1:N) -> Product (N:1) <- Brand.
    • Cada Product se desdobra em múltiplos SKUItem, contendo código de barras/SKU único, preço de venda, dimensões físicas (peso, largura, altura, profundidade) e metadados flexíveis (attributes: Json).
  3. Warehouse, StockBalance & InventoryTransaction:
    • Suporte a múltiplos depósitos (Warehouse).
    • Saldo de estoque (StockBalance) mapeado por chave primária composta (skuId, warehouseId), controlando availableQuantity, reservedQuantity e minQuantity.
    • Cada movimentação física gera um registro em InventoryTransaction com tipo (PURCHASE_RECEIPT, SALES_DISPATCH, MANUAL_ADJUSTMENT, INTERNAL_TRANSFER), quantidade, notas e operador responsável.
  4. Supplier & Customer:
    • Entidades comerciais com validação discriminada de documento (CPF com 11 dígitos ou CNPJ com 14 dígitos), e-mail único e endereço estruturado com validação de UF.
  5. PurchaseOrder & PurchaseOrderItem:
    • Pedidos de compra vinculados a um fornecedor e armazém de destino.
    • Ciclo de estados: DRAFT $\rightarrow$ ORDERED $\rightarrow$ RECEIVED (gera entrada de estoque) $\rightarrow$ CANCELED.
  6. SalesOrder & SalesOrderItem:
    • Pedidos de venda vinculados a clientes.
    • Ciclo de estados: DRAFT $\rightarrow$ CONFIRMED (reserva estoque) $\rightarrow$ DISPATCHED $\rightarrow$ DELIVERED $\rightarrow$ CANCELED.
  7. AuditLog:
    • Registro cronológico imutável com tipo de ação (CREATE, UPDATE, DELETE, LOGIN, LOGOUT, STATUS_CHANGE), tipo de entidade, ID do recurso e operador.

Matriz de Controle de Acesso (RBAC)

O sistema utiliza controle de acesso granular baseado em escopos:

Escopo Permissões Concedidas
ALL Acesso irrestrito a todos os módulos e operações do sistema (Superadministrador).
INVENTORY_READ Consulta de categorias, marcas, produtos, SKUs, armazéns, saldos e movimentações.
INVENTORY_WRITE Criação, edição e exclusão lógica de catálogo, armazéns e realização de ajustes de estoque.
PURCHASE_READ Consulta de fornecedores, pedidos de compra e seus respectivos itens.
PURCHASE_WRITE Cadastro de fornecedores, criação de pedidos de compra e alteração de status (ORDERED, RECEIVED).
SALES_READ Consulta de clientes, pedidos de venda e itens de faturamento.
SALES_WRITE Cadastro de clientes, criação de pedidos de venda e atualização de status de entrega.
USERS_READ Visualização de usuários cadastrados e perfis de permissão (Roles).
USERS_WRITE Criação, alteração de dados, atribuição de perfis e desativação de usuários.
AUDIT_READ Consulta da trilha de auditoria e histórico de logs do sistema.
AUDIT_WRITE Emissão programática de logs de auditoria (uso interno dos serviços).

Catálogo Completo de Endpoints (API REST)

Todas as rotas (exceto /auth/login e /) exigem o cabeçalho Authorization: Bearer <JWT_TOKEN>.

Autenticação & Perfil

Método Endpoint Permissão Descrição Status Codes
POST /auth/login Público Autentica usuário via e-mail e senha. Rate limit de 10 req/min. 200, 401, 403, 429
GET /auth/me Autenticado Retorna dados do operador logado e escopos ativos. 200, 401, 404
GET / Público Health check e informações básicas da API. 200

Catálogo e Produtos

Método Endpoint Permissão Descrição Status Codes
GET /categories INVENTORY_READ Lista todas as categorias cadastradas. 200, 401, 403
GET /categories/:id INVENTORY_READ Retorna detalhes de uma categoria por UUID. 200, 404
POST /categories INVENTORY_WRITE Cadastra nova categoria com validação XSS. 201, 400
PUT /categories/:id INVENTORY_WRITE Atualiza dados cadastrais da categoria. 200, 400, 404
DELETE /categories/:id INVENTORY_WRITE Exclui categoria do sistema. 200, 404
GET /brands INVENTORY_READ Lista marcas cadastradas. 200, 401, 403
POST /brands INVENTORY_WRITE Cadastra nova marca. 201, 400
PUT /brands/:id INVENTORY_WRITE Atualiza marca existente. 200, 404
DELETE /brands/:id INVENTORY_WRITE Remove marca do sistema. 200, 404
GET /products INVENTORY_READ Lista produtos com vínculo de categoria e marca. 200, 401, 403
POST /products INVENTORY_WRITE Cadastra produto pai. 201, 400
PUT /products/:id INVENTORY_WRITE Atualiza dados do produto. 200, 404
DELETE /products/:id INVENTORY_WRITE Remove produto. 200, 404
GET /sku-items INVENTORY_READ Lista itens SKU com preços e cubagem física. 200, 401, 403
POST /sku-items INVENTORY_WRITE Cadastra SKU com validação de código único e atributos JSON. 201, 400, 409
PUT /sku-items/:id INVENTORY_WRITE Atualiza dados e dimensões do SKU. 200, 404
DELETE /sku-items/:id INVENTORY_WRITE Remove SKU. 200, 404

Armazéns e Controle de Estoque

Método Endpoint Permissão Descrição Status Codes
GET /warehouses INVENTORY_READ Lista centros de distribuição e depósitos. 200, 401, 403
POST /warehouses INVENTORY_WRITE Cadastra novo armazém com endereço validado. 201, 400
PUT /warehouses/:id INVENTORY_WRITE Atualiza endereço e dados do armazém. 200, 404
DELETE /warehouses/:id INVENTORY_WRITE Remove armazém. 200, 404
GET /stock-balances INVENTORY_READ Lista saldos consolidados por SKU e depósito. 200, 401, 403
GET /stock-balances/:skuId/:warehouseId INVENTORY_READ Consulta saldo de SKU em depósito específico. 200, 404
POST /stock-balances INVENTORY_WRITE Inicializa registro de saldo para chave composta. 201, 400, 409
PUT /stock-balances/:skuId/:warehouseId INVENTORY_WRITE Atualiza quantidades disponível, reservada e mínima. 200, 404
DELETE /stock-balances/:skuId/:warehouseId INVENTORY_WRITE Exclui registro de saldo. 200, 404
GET /inventory-transactions INVENTORY_READ Lista histórico completo de movimentações físicas. 200, 401, 403
POST /inventory-transactions INVENTORY_WRITE Registra movimentação de estoque com operador. 201, 400

Suprimentos (Compras) e Vendas

Método Endpoint Permissão Descrição Status Codes
GET /suppliers PURCHASE_READ Lista fornecedores com validação de documento. 200, 401, 403
POST /suppliers PURCHASE_WRITE Cadastra fornecedor (discrimina CPF/CNPJ). 201, 400, 409
PUT /suppliers/:id PURCHASE_WRITE Atualiza cadastro de fornecedor. 200, 404
DELETE /suppliers/:id PURCHASE_WRITE Remove fornecedor. 200, 404
GET /purchase-orders PURCHASE_READ Lista pedidos de compra emitidos. 200, 401, 403
POST /purchase-orders PURCHASE_WRITE Abre pedido de compra vinculado a fornecedor e CD. 201, 400
PUT /purchase-orders/:id PURCHASE_WRITE Atualiza status do pedido (ORDERED, RECEIVED). 200, 400, 404
POST /purchase-order-items PURCHASE_WRITE Adiciona item e custo unitário ao pedido de compra. 201, 400
GET /customers SALES_READ Lista clientes cadastrados. 200, 401, 403
POST /customers SALES_WRITE Cadastra cliente com validação estrita de CPF/CNPJ. 201, 400, 409
PUT /customers/:id SALES_WRITE Atualiza cadastro do cliente. 200, 404
DELETE /customers/:id SALES_WRITE Remove cliente. 200, 404
GET /sales-orders SALES_READ Lista pedidos de venda e status de faturamento. 200, 401, 403
POST /sales-orders SALES_WRITE Cria pedido de venda vinculado a cliente. 201, 400
PUT /sales-orders/:id SALES_WRITE Atualiza status do pedido de venda. 200, 400, 404
POST /sales-order-items SALES_WRITE Adiciona item e preço unitário ao pedido de venda. 201, 400

Gestão de Acessos e Auditoria

Método Endpoint Permissão Descrição Status Codes
GET /users USERS_READ Lista usuários e perfis vinculados. 200, 401, 403
POST /users USERS_WRITE Cria novo usuário com senha validada por regex e Argon2. 201, 400, 409
PUT /users/:id USERS_WRITE Atualiza usuário (re-hasheia senha se alterada). 200, 404
DELETE /users/:id USERS_WRITE Remove operador. 200, 404
GET /roles USERS_READ Lista perfis e escopos associados. 200, 401, 403
POST /roles USERS_WRITE Cria perfil de acesso com lista de permissões. 201, 400
PUT /roles/:id USERS_WRITE Atualiza escopos do perfil. 200, 404
DELETE /roles/:id USERS_WRITE Remove perfil de acesso. 200, 404
GET /audit-logs AUDIT_READ Consulta trilha de auditoria completa (Append-Only). 200, 401, 403
GET /audit-logs/:id AUDIT_READ Detalhes de um evento de auditoria por ID. 200, 404

Segurança e Tratamento de Exceções

1. Handler Centralizado de Erros (globalErrorHandler)

O sistema intercepta todas as exceções lançadas na pipeline e normaliza as respostas HTTP em formato padronizado:

  • Erros Zod (ZodError): Retorna código 400 Bad Request com array estruturado de campos inválidos (field, message).
  • Violação de Chave Única (Prisma P2002): Retorna código 409 Conflict identificando o campo duplicado (ex: e-mail, SKU, CPF/CNPJ).
  • Registro Inexistente (Prisma P2025): Retorna código 404 Not Found.
  • Restrição de Chave Estrangeira (Prisma P2003): Retorna código 400 Bad Request apontando a dependência inválida.
  • Falha de Autenticação (FST_JWT_*): Retorna código 401 Unauthorized.

2. Defesas Adicionais

  • Sanitização XSS: Regex estrito nos schemas Zod para bloquear strings contendo tags < e >.
  • Proteção contra Brute-Force: @fastify/rate-limit ativo globalmente e com política mais restrita (10 requisições/min) no endpoint de login.
  • Segurança de Cabeçalhos: @fastify/helmet ativo para proteção contra Clickjacking, MIME-sniffing e injeções de script.
  • Comparação Temporal Segura: Uso de crypto.timingSafeEqual para mitigação de ataques baseados em tempo.

Frontend SPA (React 19 + MUI)

O frontend foi desenvolvido com foco em produtividade, feedback visual imediato e integridade de sessão:

  • Autenticação Reativa: AuthContext decodifica claims do JWT no login e mantém o estado de autenticação em memória/armazenamento seguro.
  • Guardas de Rota RBAC: Componente PermissionRoute que intercepta acessos diretos por URL e redireciona usuários sem permissão para /dashboard.
  • Navegação Dinâmica: Sidebar do DashboardLayout renderiza apenas os módulos aos quais o usuário tem permissão explícita.
  • Tabelas com DataGrid: Listagens com paginação no servidor, ordenação dinâmica por coluna e filtros de busca.
  • Prevenção de Perda de Dados: Componente DirtyFormWarning que notifica o operador caso tente sair de uma tela com alterações não salvas no formulário.
  • Tema Customizável: Suporte a alternância dinâmica de tema Claro/Escuro via ThemeContext.

Instalação e Execução

Pré-requisitos

Passo 1: Clonar o Repositório e Configurar Variáveis

git clone https://github.com/alighieribot/SIGMA.git
cd SIGMA
cp .env.example .env

Passo 2: Inicializar o Banco de Dados (Docker)

Inicie o container PostgreSQL 15:

docker compose up -d

Passo 3: Instalar Dependências e Executar Migrações

npm install
npm run db:migrate
npm run db:seed

O seed inicial cria a seguinte conta de acesso:

  • E-mail: admin@sigma.com
  • Senha: Admin@123456
  • Perfil: Administrador (escopo total ALL)

Passo 4: Iniciar o Servidor Backend

npm run dev

O servidor estará respondendo em: http://localhost:3001.

Passo 5: Executar o Frontend SPA

Em um terminal separado:

cd ../SIGMA-FRONTEND/SIGMA
cp .env.example .env
npm install
npm run dev

Acesse a aplicação em: http://localhost:5173.

Documentação Interativa (Swagger)

Com a API em execução, acesse a documentação interativa OpenAPI no navegador:

http://localhost:3001/docs

Para executar requisições autenticadas no Swagger UI:

  1. Faça login na rota POST /auth/login informando as credenciais de teste.
  2. Copie o token retornado.
  3. Clique no botão Authorize (topo superior direito da página do Swagger) e insira o token no formato Bearer <SEU_TOKEN>.

Scripts do Projeto

Comando Descrição
npm run dev Inicia o servidor backend em modo de desenvolvimento com hot-reload (tsx).
npm run build Compila o código TypeScript para JavaScript na pasta dist/.
npm run start Executa o servidor compilado em ambiente de produção a partir de dist/server.js.
npm run db:migrate Aplica migrações pendentes do Prisma no banco de dados.
npm run db:seed Executa o script de seed para popular o banco de dados com dados iniciais.
npm run check Executa análise estática de linter e formatação com o Biome.
npm run lint Aplica correções automáticas de código com o Biome.
npm run format Formata todo o código-fonte de acordo com as diretrizes do Biome.

About

Modular ERP backend built with Fastify v5, Prisma ORM, and PostgreSQL. Multi-warehouse inventory, stock reservation, purchase/sales workflows, granular RBAC, and append-only audit logging.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages