Controle de Estoque API

API backend desenvolvida com C# e .NET 8 para gerenciamento de produtos, movimentações e níveis de estoque de forma eficiente e segura.

Objetivo

Centralizar e otimizar o controle de inventário, permitindo:

• Controle preciso de quantidade de produtos
• Registro de entradas e saídas
• Monitoramento de níveis mínimos de estoque
• Geração de relatórios operacionais
• Apoio à gestão de compras e vendas

---

Tecnologias

Tecnologia	Uso
.NET 8 / ASP.NET Core	Framework principal
Entity Framework Core	ORM e acesso ao banco de dados
SQLite	Banco de dados (padrão)
JWT Bearer	Autenticação e autorização
BCrypt	Hash seguro de senhas
Swagger / OpenAPI	Documentação interativa da API

---

Arquitetura

O projeto segue os princípios de Clean Architecture, com separação clara de responsabilidades entre as camadas:

ControleEstoque/
├── src/
│   ├── ControleEstoque.Domain/          # Entidades, interfaces e enums
│   ├── ControleEstoque.Application/     # Serviços, DTOs e casos de uso
│   ├── ControleEstoque.Infrastructure/  # EF Core, repositórios e segurança
│   └── ControleEstoque.API/             # Controllers, middlewares e configuração
└── ControleEstoque.sln

Camadas

Domain — núcleo da aplicação, sem dependências externas

• Entidades: Product, Category, StockMovement, User
• Enums: MovementType (Entry / Exit), UserRole (Admin / Manager / Operator)
• Interfaces: IRepository<T>, IUnitOfWork, repositórios específicos

Application — regras de negócio e casos de uso

• Serviços: ProductService, CategoryService, StockMovementService, UserService, StockReportService
• DTOs de entrada e saída para cada recurso
• Interfaces de serviço e IPasswordHasher

Infrastructure — implementações técnicas

• AppDbContext com configurações Fluent API
• Repositórios concretos com EF Core e padrão Unit of Work
• BcryptPasswordHasher e JwtAuthService

API — ponto de entrada HTTP

• Controllers REST com controle de acesso por role
• ExceptionMiddleware para tratamento global de erros
• Configuração de JWT, Swagger e CORS no Program.cs

---

Funcionalidades

Gestão de Produtos

• Cadastro, edição e exclusão (soft delete) de produtos
• Campos: nome, descrição, SKU, preço, quantidade e estoque mínimo
• Organização por categorias
• Consulta por SKU ou categoria
• Listagem de produtos com estoque abaixo do mínimo

Controle de Movimentações

• Registro de entradas (compras, reposições) e saídas (vendas, perdas)
• Atualização automática da quantidade em estoque
• Validação de estoque suficiente para saídas
• Histórico completo com filtros por produto, tipo e período

Relatórios

• Resumo geral do estoque (totais, alertas de baixo estoque)
• Relatório de movimentações por período com totais de entrada e saída

Autenticação e Segurança

• Login com e-mail e senha, retornando token JWT
• Proteção de endpoints por autenticação e role
• Senhas armazenadas com hash BCrypt

---

Controle de Acesso

Role	Permissões
Admin	Acesso total — incluindo gestão de usuários
Manager	Criar/editar produtos e categorias, registrar movimentações
Operator	Consultar dados e registrar movimentações

---

Endpoints

Autenticação

Método	Rota	Descrição	Acesso
POST	/api/auth/login	Autentica e retorna JWT	Público

Categorias

Método	Rota	Descrição	Acesso
GET	/api/categories	Lista todas as categorias	Autenticado
GET	/api/categories/{id}	Busca por ID	Autenticado
POST	/api/categories	Cria categoria	Admin, Manager
PUT	/api/categories/{id}	Atualiza categoria	Admin, Manager
DELETE	/api/categories/{id}	Remove categoria	Admin

Produtos

Método	Rota	Descrição	Acesso
GET	/api/products	Lista todos os produtos	Autenticado
GET	/api/products/{id}	Busca por ID	Autenticado
GET	/api/products/sku/{sku}	Busca por SKU	Autenticado
GET	/api/products/category/{id}	Lista por categoria	Autenticado
GET	/api/products/low-stock	Produtos com estoque baixo	Autenticado
POST	/api/products	Cadastra produto	Admin, Manager
PUT	/api/products/{id}	Atualiza produto	Admin, Manager
DELETE	/api/products/{id}	Remove produto	Admin

Movimentações

Método	Rota	Descrição	Acesso
GET	/api/stockmovements	Lista todas as movimentações	Autenticado
GET	/api/stockmovements/{id}	Busca por ID	Autenticado
GET	/api/stockmovements/product/{id}	Por produto	Autenticado
GET	/api/stockmovements/period?start=&end=	Por período	Autenticado
GET	/api/stockmovements/type/{type}	Por tipo (Entry/Exit)	Autenticado
GET	/api/stockmovements/report?start=&end=	Relatório por período	Autenticado
POST	/api/stockmovements	Registra movimentação	Autenticado

Relatórios

Método	Rota	Descrição	Acesso
GET	/api/reports/stock-summary	Resumo geral do estoque	Autenticado

Usuários

Método	Rota	Descrição	Acesso
GET	/api/users	Lista usuários	Admin
GET	/api/users/{id}	Busca por ID	Admin
POST	/api/users	Cria usuário	Admin
PUT	/api/users/{id}	Atualiza usuário	Admin
DELETE	/api/users/{id}	Remove usuário	Admin

---

Como executar

Pré-requisitos

• .NET 8 SDK

1. Restaurar dependências

dotnet restore

2. Criar e aplicar migrations

dotnet ef migrations add Initial --project src/ControleEstoque.Infrastructure --startup-project src/ControleEstoque.API
dotnet ef database update --project src/ControleEstoque.Infrastructure --startup-project src/ControleEstoque.API

3. Executar a API

dotnet run --project src/ControleEstoque.API

4. Acessar o Swagger

http://localhost:5000/swagger

---

Configuração

O arquivo src/ControleEstoque.API/appsettings.json contém as configurações principais:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=estoque.db"
  },
  "JwtSettings": {
    "SecretKey": "TROQUE_ESTA_CHAVE_POR_UMA_SEGURA_COM_32_CHARS_MINIMO!",
    "Issuer": "ControleEstoque.API",
    "Audience": "ControleEstoque.Clients",
    "ExpiresInHours": "8"
  }
}

Importante: Substitua o valor de SecretKey por uma chave segura antes de usar em produção. Nunca versione chaves reais.

Trocar banco de dados

Para usar PostgreSQL, altere o pacote e a connection string:

<!-- Infrastructure.csproj -->
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.4" />

// Program.cs
options.UseNpgsql(connectionString);

---

Autenticação via Swagger

1. Faça login em POST /api/auth/login com e-mail e senha
2. Copie o token retornado
3. Clique em Authorize no topo do Swagger
4. Informe: Bearer {token}

---

Banco de dados

O projeto utiliza SQLite por padrão, gerando o arquivo estoque.db na raiz do projeto da API. O banco é criado e migrado automaticamente na inicialização.

---

Possíveis evoluções

• Seed de dados iniciais (usuário Admin padrão)
• Validações com FluentValidation
• Paginação nas listagens
• Integração com leitura de código de barras / QR Code
• Controle de múltiplos estoques (multi-filial)
• Notificações automáticas de reposição
• Logs de auditoria detalhados
• Dashboard em tempo real com SignalR