Um sistema de gestão de armazéns moderno, reativo e distribuído, construído com foco em alta performance, rastreabilidade em tempo real e arquitetura multi-tenant.
O CoreWMS não é apenas um CRUD. Ele é uma plataforma arquitetada para resolver os desafios reais do chão de fábrica e da expedição, unindo um backend robusto em .NET, um frontend reativo em React e um agente local descentralizado para comunicação direta com hardware de impressão.
O ecossistema é dividido em três camadas principais, cada uma com responsabilidades estritas e tecnologias específicas:
API RESTful construída em .NET 10, utilizando princípios de Vertical Slice Architecture (VSA), Domain-Driven Design (DDD) e CQRS.
- CQRS & Mediator: Padrão implementado com
MediatR. Separação clara entre Commands (escrita/mudança de estado) e Queries (leitura). - Mapeamento: Mapeamento automático com Mapster
- Validação:
FluentValidationinjetado diretamente no pipeline do MediatR. Requisições inválidas geram erro 400 antes mesmo de tocarem nos Handlers. - Dados Relacionais:
Entity Framework Corecom suporte a Multi-Tenancy nativo (Filtros Globais por Empresa/Tenant). - Dados Não-Relacionais (Auditoria):
MongoDBpara gravação assíncrona de logs de auditoria em formato de Snapshot (imutabilidade temporal). - Comunicação em Tempo Real:
SignalRpara rastreamento de conexões ativas e envio instantâneo de comandos (ex: WebSockets para impressão). - Tratamento Global de Erros: Exceções de domínio e bibliotecas interceptadas nativamente pelo
GlobalExceptionHandler, mantendo os Handlers livres de blocostry/catch. - Segurança: Autenticação via JWT (com Refresh Tokens) e Autorização baseada em Permissões (Custom Filters).
Single Page Application (SPA) ultrarrápida desenvolvida com React e Vite.
- Design System:
Tailwind CSSaliado aos componentes acessíveis e modulares doshadcn/ui. - Gerenciamento de Estado de Formulários:
React Hook Formcombinado comZodpara validações declarativas espelhadas no backend. - Sincronização de API (The Magic):
Orvalpara geração automática de Hooks doTanStack React Querye tipagens TypeScript diretamente do Swagger da API. - Estado Global:
Zustandpara controle de sessão (Auth) e seleção de Empresa (Multi-tenant).
Um Worker Service (Instalável via Windows Service ou Linux Systemd) que roda na rede local do cliente.
- Resiliência Offline: Utiliza SQLite local (
print_queue.db) para guardar na fila requisições de impressão caso a rede oscile. - Protocolos de Impressão: Comunicação direta RAW TCP Socket (Zebra/Epson), Spooler nativo do Windows (winspool) e CUPS do Linux.
- Conexão Global: Mantém um túnel persistente via SignalR com a nuvem, aguardando comandos ZPL em tempo real e reportando status (Online/Offline/Sucesso/Erro).
- System Tray: Uso do Ayatana App Indicator para ícone da barra de tarefas (gir1.2-ayatanaappindicator3-0.1)
- Gestão de Usuários e Perfis (Roles).
- Controle Granular de Permissões (Cache em memória para alta performance).
- O sistema é 100% Multi-Tenant. Um usuário pode pertencer a várias empresas e alternar entre elas, o que altera o contexto global da API de forma transparente.
- Agentes Globais: Cadastro das máquinas físicas (PCs) que rodam o Worker Service. O status (Online/Offline) é monitorado em tempo real pelo SignalR Connection Manager.
- Impressoras: Mapeamento de impressoras (IP:Porta, LPT, USB) atreladas a um Agente.
- Templates ZPL: Cadastro de layouts (etiquetas) diretamente no sistema. Disparo de impressões de teste via painel administrativo que chegam em milissegundos no chão de fábrica.
- Processamento e validação de esquemas XML (XSD) nativos da SEFAZ para NFe e CTe.
- Consultas de status e cadastros sincronizados.
- Logs interceptados via
IHostedService(Background Worker) para não penalizar o tempo de resposta das requisições HTTP. - Os registros salvam o nome das entidades e usuários no exato momento da ação, garantindo que o histórico permaneça legível mesmo se as entidades originais forem apagadas do banco de dados relacional (Proteção contra exclusão em cascata de logs).
Para manter a base de código escalável e limpa, a equipe deve seguir estes preceitos inegociáveis:
-
Isolamento VSA (Vertical Slice Architecture): O padrão ouro do projeto. Cada funcionalidade (Feature) deve ter seu próprio arquivo físico isolado, contendo estritamente o Request/Query, o Handler com a regra de negócio e o Endpoint de mapeamento. É terminantemente proibido espalhar lógicas de uma mesma feature em pastas genéricas de
ControllersouServices. Lógicas compartilhadas devem ser extraídas para serviços de domínio estritos. -
Performance de Dados (EF Core): O uso de
.AsNoTracking()é obrigatório em todas as rotas de leitura pura (Queries). O desenvolvedor deve garantir a prevenção de N+1 queries utilizandoInclude/SplitQueryadequadamente, além de certificar que buscas pesadas e paginações estão cobertas por índices no banco de dados. -
Segurança e Multi-Tenant: O isolamento de dados é vital. O
Tenant IDdeve ser injetado e respeitado em todas as transações, garantindo que nenhuma empresa veja dados de outra. Todo e qualquer novo endpoint REST deve ser explicitamente blindado com o filtro de extensão.RequirePermission(Permissions.Modulo.Acao). -
Geração de API Front-end (Orval): Nunca crie requisições Axios/Fetch manualmente. Sempre que o Backend sofrer alterações (novos endpoints ou mudanças de DTOs), compile a API e rode o gerador no frontend:
npm run generate:api
-
Encapsulamento de Entidades (DDD): As entidades do CoreWMS (ex:
Printer.cs,Company.cs) possuemprivate set;em suas propriedades. Atualizações de estado devem ser feitas através de métodos de domínio (ex:Update(...),RegenerateApiKey(...)), nunca por atribuição direta nos Handlers. -
Validações Duplas (Front + Back): Toda regra de negócio ou obrigatoriedade de campo deve existir em dois lugares: no esquema do
Zod(para UX imediata no frontend) e noFluentValidation(para proteção real do backend).
Na raiz do projeto, suba os serviços de dependência (PostgreSQL, MongoDB, Redis) através do Docker Compose:
docker-compose up -d --build
cd CoreWMS.Api
dotnet run
A API iniciará, aplicará as migrações (EF Core) e o Database Seeder criará os usuários e permissões padrões do sistema.
cd corewms-web
npm install
npm run dev
cd CoreWMS.PrintAgent
dotnet run
CoreWMS - Construído com ❤️ e foco na excelência arquitetural.