EasyERP

Biblioteca TypeScript modular e agnóstica de banco de dados para acelerar o desenvolvimento de sistemas ERP, e-commerce, estoque, vendas e gestão empresarial — inspirada na simplicidade de uso do Express e do Prisma.

Status: 🚧 Em desenvolvimento ativo — Fase 1 concluída (arquitetura e infraestrutura do projeto). Veja o roadmap.

Por que EasyERP?

Todo sistema de gestão empresarial recria as mesmas funcionalidades: cadastro de clientes com validação de CPF/CNPJ, controle de estoque com lotes e validade, cálculo de pedidos com desconto e frete, contas a pagar/receber, RBAC, auditoria... A EasyERP existe para eliminar esse retrabalho, oferecendo módulos prontos, testados e 100% tipados, mantendo a aplicação livre para escolher seu próprio banco de dados.

Instalação

npm install easyerp

Uso

import { EasyERP } from "easyerp";

const erp = new EasyERP();

await erp.clientes.create({ nome: "Pedro", cpf: "00000000000" });
await erp.produtos.create({ nome: "Notebook", preco: 3500 });
await erp.estoque.entrada({ produto: 1, quantidade: 10 });
await erp.pedidos.create({ cliente: 1 });

Também é possível importar módulos individualmente, reduzindo o bundle:

import { ClientesModule } from "easyerp/clientes";

Arquitetura

A EasyERP segue Clean Architecture e SOLID, com cada módulo de domínio organizado em camadas isoladas e testáveis:

src/<modulo>/
├── controller/     # Camada de entrada (orquestra validação + service)
├── service/        # Regras de negócio puras
├── repository/     # Acesso a dados via DatabaseAdapter
├── <modulo>.module.ts
└── index.ts         # Barrel export

Independência de banco de dados

A biblioteca não depende de nenhum ORM. Toda persistência passa pela interface DatabaseAdapter (padrão Adapter):

interface DatabaseAdapter<TEntity> {
  create(data): Promise<TEntity>;
  findById(id): Promise<TEntity | null>;
  findMany(params): Promise<PaginatedResult<TEntity>>;
  update(id, data): Promise<TEntity>;
  delete(id): Promise<void>;
  exists(id): Promise<boolean>;
}

Por padrão, a EasyERP usa um InMemoryAdapterFactory (zero-config, ideal para testes e prototipagem). Adapters para Prisma, TypeORM, Drizzle, MongoDB, PostgreSQL, MySQL, SQLite e Supabase estão no roadmap e serão plugáveis via injeção de dependência:

const erp = new EasyERP({ database: new PrismaAdapterFactory(prismaClient) });

Padrões de projeto utilizados

| Padrão | Onde | |---|---| | Facade | EasyERP (entrypoint único) | | Adapter | DatabaseAdapter / DatabaseAdapterFactory | | Factory | *AdapterFactory.getAdapter() | | Repository | src/<modulo>/repository | | Builder/Options | resolveConfig(options) | | Strategy | Validadores plugáveis por módulo (CPF/CNPJ, regras de desconto) | | Dependency Injection | Adapter e config injetados no construtor de EasyERP |

Tratamento de erros

Hierarquia única de exceções (AppError), com subtipos previsíveis: NotFoundError, ValidationError, BusinessRuleError, ConflictError, UnauthorizedError, ForbiddenError, InfrastructureError.

Módulos

| Módulo | Responsabilidade | Status | |---|---|---| | clientes | CRUD, CPF/CNPJ, endereço, contato, histórico | 🚧 Fase 2 | | produtos | CRUD, categorias, SKU, código de barras, estoque min/max | 🚧 Fase 3 | | estoque | Entrada/saída, inventário, lotes, validade, alertas | 🚧 Fase 4 | | pedidos | Criação, cálculo de total/desconto/frete, status | 🚧 Fase 5 | | financeiro | Contas a pagar/receber, fluxo de caixa, juros/multa | 🚧 Fase 6 | | usuarios / auth | Cadastro, login, JWT, refresh token, perfis | 🚧 Fase 7 | | permissoes | RBAC por módulo e ação | 🚧 Fase 8 | | auditoria | Log de todas as ações (quem, quando, o quê, resultado) | 🚧 Fase 8 | | relatorios | Relatórios de clientes, produtos, estoque, financeiro, pedidos | 🚧 Fase 9 |

Scripts de desenvolvimento

npm run build          # Build ESM + CJS + .d.ts (tsup)
npm run dev             # Build em modo watch
npm run typecheck       # Checagem de tipos (tsc --noEmit)
npm test                # Testes (Vitest)
npm run test:coverage   # Testes com cobertura (mínimo 90%)
npm run lint             # ESLint (zero warnings tolerados)
npm run format            # Prettier
npm run docs                # Gera documentação da API (TypeDoc)

Roadmap

• [x] Fase 1 — Arquitetura, estrutura de pastas, configuração (TypeScript, ESLint, Prettier, tsup, Vitest, npm publish)
• [ ] Fase 2 — Módulo clientes
• [ ] Fase 3 — Módulo produtos
• [ ] Fase 4 — Módulo estoque
• [ ] Fase 5 — Módulo pedidos
• [ ] Fase 6 — Módulo financeiro
• [ ] Fase 7 — Módulos usuarios + auth
• [ ] Fase 8 — Módulos permissoes + auditoria
• [ ] Fase 9 — Módulo relatorios
• [ ] Fase 10 — Adapters oficiais (Prisma, TypeORM, Drizzle, Mongo, Supabase)

Contribuindo

Contribuições são bem-vindas! Abra uma issue descrevendo a mudança proposta antes de enviar um PR. Todo PR deve passar em npm run lint, npm run typecheck e npm test (cobertura mínima de 90%).

Licença

MIT