@lojasquare/core

Core library for LojaSquare frontends — business logic, API services, and utilities.

Índice

• Visão Geral
• Arquitetura
• Quando Usar Services vs Use Cases
• Configuração Inicial
• Services
• Use Cases
• Repositories
• Models
• Adapters
• Utils
• Cenários de Teste
• Licença

Visão Geral

A biblioteca @lojasquare/core centraliza toda a lógica de negócio, chamadas de API e utilitários para aplicações LojaSquare. Foi projetada para ser agnóstica de framework e reutilizável em diferentes frontends (Angular, React, Vue).

Total de Funções:

• Services: 86 funções
• Use Cases: 7 casos de uso
• Repositories: 6 repositórios
• Models: 4 arquivos de interface
• Adapters: 2 adaptadores (HTTP + Storage)
• Utils: 25 funções utilitárias

Arquitetura

┌──────────────┐
│   Frontend   │ (Angular/React/Vue Component)
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Use Cases   │ ← Orquestração de fluxos complexos (recomendado)
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Services   │ ← Lógica de negócio + Chamadas API
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Repositories │ ← Chamadas HTTP puras
└──────┬───────┘
       │
       ▼
┌──────────────┐
│     API      │
└──────────────┘

Quando Usar Services vs Use Cases

Use Use Cases quando:

• Implementando fluxo completo de uma funcionalidade (ex: login, checkout, adicionar produto)
• Precisa de validações antes de chamar API
• Precisa orquestrar múltiplos services
• O componente deve ter mínima lógica
• Quer testabilidade e reuso de lógica

Use Services diretamente quando:

• Precisa de funções utilitárias (ex: formatCurrency, isInStock)
• Fazendo cálculos locais sem API (ex: calculateCartTotal)
• Manipulando storage (ex: getCart, saveCart)
• Operações simples e atômicas

Regra Geral:

Componentes de UI → Use Cases → Services → Repositories → API

Configuração Inicial

import { 
  configureLojaSquare,
  configureRepository,
  BrowserStorageAdapter, 
  setStorageAdapter 
} from '@lojasquare/core';

// 1. Configurar biblioteca
configureLojaSquare({
  apiBaseUrl: 'https://api.lojasquare.net/v1',
  debug: true
});

// 2. Configurar storage (browser)
setStorageAdapter(new BrowserStorageAdapter());

// 3. Configurar HTTP client
configureRepository(
  {
    baseUrl: 'https://api.lojasquare.net/v1',
    getAuthHeader: async () => ({ Authorization: 'your-key' })
  },
  angularHttpAdapter // ou AxiosAdapter, FetchAdapter
);

Services

Documentação completa em: src/lib/services/README.md

| Service | Descrição | Quando usar | README | |---------|-----------|-------------|--------| | AuthService | Autenticação, tokens JWT, sessão | Token/username storage, decode JWT, headers | README_AUTH_SERVICES.md | | CarrinhoService | Carrinho de compras, validações, cálculos | CRUD carrinho, cálculos de total, validação estoque | README_CARRINHO_SERVICES.md | | ItensService | Catálogo de produtos, filtros, ordenação | Filtros, ordenação, formatação, verificação de estoque | README_ITENS_SERVICES.md | | SiteService | Configuração do site, cache, status | Identificação do site, cache c/ TTL, status servidor | README_SITE_SERVICES.md | | ValidationService | Validações de domínio | Pré-validação de checkout, player, cupom | README_VALIDATION_SERVICES.md |

Use Cases

Documentação completa em: src/lib/use-cases/README.md

| Use Case | Descrição | Quando usar | README | |----------|-----------|-------------|--------| | LoginUseCase | Fluxo completo de login | Tela de login | README_LOGIN_USECASE.md | | RegisterUseCase | Fluxo completo de registro | Tela de criação de conta | README_REGISTER_USECASE.md | | AddProductUseCase | Adicionar produto ao carrinho | Botão "Adicionar ao Carrinho" | README_ADD_PRODUCT_USECASE.md | | ApplyCouponUseCase | Aplicar cupom de desconto | Formulário de cupom no carrinho | README_APPLY_COUPON_USECASE.md | | CheckoutUseCase | Finalizar compra | Botão "Finalizar Compra" | README_CHECKOUT_USECASE.md | | CheckoutFlowUseCase | Orquestrador de checkout com UI | Checkout completo c/ wizard de dados + PIX + progress bar | README_CHECKOUT_FLOW_USECASE.md | | LoadProductsUseCase | Carregar e filtrar produtos | Página de produtos, catálogo, busca | README_LOAD_PRODUCTS_USECASE.md |

Repositories

Documentação completa em: src/lib/repositories/README.md

| Repository | Descrição | Quando usar | README | |------------|-----------|-------------|--------| | AuthRepository | API de autenticação | Chamadas diretas de login/register/validate (prefira AuthService) | README_AUTH_REPOSITORY.md | | BaseRepository | HTTP client wrapper, configuração | Configuração inicial da lib + helpers seguros | README_BASE_REPOSITORY.md | | CarrinhoRepository | API de carrinho, cupom, checkout | Chamadas de cupom/pagamento/gateways (prefira CarrinhoService) | README_CARRINHO_REPOSITORY.md | | ContentRepository | API de conteúdo estático | Regras, equipe, notícias, termos, hooks, transações | README_CONTENT_REPOSITORY.md | | ItensRepository | API de produtos, servidores, categorias | Produtos, servidores e categorias (prefira ItensService) | README_ITENS_REPOSITORY.md | | SiteRepository | API de site, menu, status servidor | Site info, menu, status MTA (prefira SiteService) | README_SITE_REPOSITORY.md |

Models

Documentação completa em: src/lib/models/README.md

| Arquivo | Interfaces | Quando usar | |---------|-----------|-------------| | auth.model.ts | InfosLogin, InfosRegister, JWTDecode, LoginResult, RegisterResult, AuthValidationResult | Tipos de autenticação | | carrinho.model.ts | Carrinho, ItemCarrinho, DadosPagamento, GatewayInfo, CheckoutDTO, PagamentoDTO | Tipos de carrinho/checkout | | produto.model.ts | Produtos, Servidores, Categorias | Tipos de catálogo | | site.model.ts | Site, Menu, StatusServer, MsgOptions, DetalhesSite, IdentificaSite | Tipos de configuração do site |

Adapters

Documentação completa em: src/lib/adapters/README.md

| Adapter | Descrição | Quando usar | |---------|-----------|-------------| | HttpAdapter | Interface HTTP agnóstica de framework | Configuração inicial — crie implementações p/ Angular/Axios/Fetch | | StorageAdapter | Interface de storage (localStorage/memory) | Configuração inicial — use MemoryStorageAdapter p/ SSR/testes |

Utils

Documentação completa em: src/lib/utils/README.md

| Utilitário | Arquivo | Quando usar | README | |------------|---------|-------------|--------| | String Utils | string.util.ts | Formatação de string, moeda, email, slug | README_STRING_UTIL.md | | Date Utils | date.util.ts | Timestamp, formatação de data, dias entre datas | README_DATE_UTIL.md | | Validation Utils | validation.util.ts | Validação de CPF, username, senha, telefone | README_VALIDATION_UTIL.md |

Cenários de Teste

Matriz de Cobertura de Testes

Services (Testados em Isolamento)

• AuthService: Token management, username, routes
• CarrinhoService: CRUD carrinho, validações, cálculos
• ItensService: Filtros, ordenação, formatação
• SiteService: Cache, identificação, helpers
• ValidationService: Validações de domínio

Use Cases (Testados com Mocks de Services/Repositories)

• LoginUseCase: Validações + fluxo completo
• RegisterUseCase: Validações + fluxo completo
• AddProductUseCase: Validações de estoque + carrinho
• ApplyCouponUseCase: Validação de cupom + API
• CheckoutUseCase: Validações completas + pagamento
• LoadProductsUseCase: Filtros + ordenação + API

Utils (Testes Unitários Puros)

• String Utils: Formatações e validações de string
• Date Utils: Formatações e cálculos de data
• Validation Utils: CPF, username, senha

Critérios de Aceite Globais

1. Todas as funções devem:

   • Ter documentação clara (JSDoc)
   • Ter testes unitários
   • Tratar erros gracefully
   • Retornar tipos consistentes

2. Use Cases devem:

   • Validar inputs antes de chamar API
   • Retornar objetos com success: boolean
   • Incluir error ou validationErrors em falhas
   • Ser stateless (sem side effects ocultos)

3. Services devem:

   • Ser funções puras quando possível
   • Documentar side effects (API calls, storage)
   • Usar StorageAdapter para testes
   • Não duplicar lógica dos Use Cases

4. Utils devem:

   • Ser 100% puros (sem side effects)
   • Funcionar sem DI
   • Ter cobertura de testes > 90%

Licença

UNLICENSED - LojaSquare Proprietary