Pular para o conteúdo principal

Order Header Service

Gerencia operações relacionadas aos pedidos de venda, permitindo buscar histórico de pedidos com filtros por período, líder e usuário, além de consultar detalhes completos de pedidos específicos.

Visão Geral​

O OrderHeaderService é responsável por:

  • Buscar pedidos da API remota
  • Filtrar pedidos por período (data início/fim)
  • Filtrar pedidos por líder e usuário
  • Inicializar pedidos básicos para clientes
  • Consultar detalhes completos de um pedido específico
  • Atualizar pedidos existentes
  • Deletar pedidos
  • Fornecer informações de cabeçalho e itens do pedido
  • Acessar dados de empresa, cliente, forma de pagamento e tipo de operação

Os pedidos (order headers) representam as vendas realizadas no sistema, contendo todas as informações necessárias para gestão comercial, financeira e operacional.

Localização: services/order-header/order-header.service.ts

Endpoints Utilizados​

Base URL​

Todos os endpoints são relativos à base URL configurada em services/api.service.ts

Métodos​

fetchRemotePage(params, filter)​

Busca pedidos remotamente com paginação e filtros, retornando a resposta completa da API.

Endpoint: GET /cabecalhoPedido

Parâmetros:

params: FetchOrderHeadersParams; // Parâmetros de paginação e filtros
filter?: OrderHeaderFilter; // Filtros adicionais

Retorno:

Promise<PageResponse<OrderHeader>>;

Exemplo de uso:

const pageResponse = await orderHeaderService.fetchRemotePage({
  page: 0,
  size: 50,
});
console.log(pageResponse.content.length); // Número de pedidos na página

Tratamento de erros:

  • Lança Error se o status da resposta não for 2xx
  • Mensagem: OrderHeaderService.fetchRemotePage failed: {status}

registerFullOrderHeader(fullOrderHeader)​

Registra um pedido completo, incluindo cabeçalho e itens.

Endpoint: POST /cabecalhoPedido/completo

Parâmetros:

fullOrderHeader: RegisterFullOrderHeader; // Dados completos do pedido

Retorno:

Promise<OrderHeader>;

Exemplo de uso:

const fullOrder = await orderHeaderService.registerFullOrderHeader(
  fullOrderHeaderPayload,
);
console.log("Pedido completo registrado:", fullOrder.id);

Tratamento de erros:

  • Lança Error se o status da resposta não for 2xx
  • Mensagem: OrderHeaderService.registerFullOrderHeader failed: {status}

updateFullOrderHeader(orderHeaderId, orderHeaderUpdated)​

Atualiza um pedido completo, incluindo cabeçalho e itens.

Endpoint: PUT /cabecalhoPedido/completo/{orderHeaderId}

Parâmetros:

orderHeaderId: string; // ID do pedido a ser atualizado
orderHeaderUpdated: RegisterFullOrderHeader; // Dados atualizados do pedido

Retorno:

Promise<OrderHeader>;

Exemplo de uso:

const updatedFullOrder = await orderHeaderService.updateFullOrderHeader(
  "oh-001",
  updatedOrderPayload,
);
console.log("Pedido completo atualizado:", updatedFullOrder.id);

Tratamento de erros:

  • Lança Error se o status da resposta não for 2xx
  • Mensagem: OrderHeaderService.updateFullOrderHeader failed: {status}

finishOrderHeader(orderHeaderId)​

Finaliza um pedido específico.

Endpoint: PATCH /cabecalhoPedido/{orderHeaderId}/finalizado

Parâmetros:

orderHeaderId: string; // ID do pedido a ser finalizado

Retorno:

Promise<OrderHeader>;

Exemplo de uso:

const finishedOrder = await orderHeaderService.finishOrderHeader("oh-001");
console.log("Pedido finalizado:", finishedOrder.id);

Tratamento de erros:

  • Lança Error se o status da resposta não for 2xx
  • Mensagem: OrderHeaderService.finishOrderHeader failed: {status}

deleteOrderHeader(orderHeaderId)​

Deleta um pedido específico.

Endpoint: DELETE /cabecalhoPedido/{orderHeaderId}

Parâmetros:

orderHeaderId: string; // ID do pedido a ser deletado

Retorno:

Promise<void>;

Exemplo de uso:

await orderHeaderService.deleteOrderHeader("oh-001");
console.log("Pedido deletado com sucesso");

Tratamento de erros:

  • Lança Error se o status da resposta não for 2xx
  • Mensagem: OrderHeaderService.deleteOrderHeader failed: {status}

Estruturas de Dados​

Interface OrderHeader​

interface OrderHeader {
  id: string;
  cliente: Client;
  empresa: Company;
  formaPagamento: PaymentMethod;
  tipoOperacao: OperationType;
  itens: Item[];
  valor: number;
  nuNota: string;
  vinculos: OrderLinking[];
}

Interface Item​

interface Item {
  id: string;
  descricao: string;
  quantidade: number;
  valorUnitario: number;
  valorTotal: number;
}

Interface OrderLinking​

interface OrderLinking {
  codTip: string;
  descricao: string;
  observacao: string;
}

Casos de Uso​

Registrar Pedido Completo​

const fullOrder = await orderHeaderService.registerFullOrderHeader(
  fullOrderHeaderPayload,
);
console.log("Pedido completo registrado:", fullOrder.id);

Atualizar Pedido Completo​

const updatedOrder = await orderHeaderService.updateFullOrderHeader(
  "oh-001",
  updatedOrderPayload,
);
console.log("Pedido completo atualizado:", updatedOrder.id);

Finalizar Pedido​

const finishedOrder = await orderHeaderService.finishOrderHeader("oh-001");
console.log("Pedido finalizado:", finishedOrder.id);

Deletar Pedido​

await orderHeaderService.deleteOrderHeader("oh-001");
console.log("Pedido deletado com sucesso");

Testes​

Localização​

services/order-header/order-header.service.test.ts

Executar Testes​

# Teste específico do serviço
npx jest services/order-header/order-header.service.test.ts

# Modo watch
npx jest services/order-header/order-header.service.test.ts --watch

# Com coverage
npx jest services/order-header/order-header.service.test.ts --coverage

Casos de Teste​

  • ✅ fetchRemote: busca de pedidos com paginação
  • ✅ fetchRemoteById: busca de pedido específico por ID
  • ✅ initOrderHeader: inicialização de pedido básico
  • ✅ initOrderHeader: tratamento de erros para status não-2xx
  • ✅ updateOrderHeader: atualização de pedido
  • ✅ updateOrderHeader: tratamento de erros para status não-2xx
  • ✅ deleteOrderHeader: deleção de pedido
  • ✅ deleteOrderHeader: tratamento de erros para status não-2xx
  • ✅ registerOrderHeader: cadastro de pedido
  • ✅ registerOrderHeader: tratamento de erros para status não-2xx
  • ✅ fetchRemote: retorna content em status 2xx
  • ✅ fetchRemote: tratamento de erros para status não-2xx
  • ✅ fetchRemoteById: busca pedido específico por ID
  • ✅ fetchRemoteById: retorna data em status 2xx
  • ✅ fetchRemoteById: tratamento de erros para status não-2xx
  • ✅ fetchRemoteById: chama endpoint com parâmetro correto

Mocks​

Localização​

__mocks__/order-header.mock.ts

Dados Disponíveis​

Mock com pedido completo de exemplo:

  • orderHeaderResponse: Pedido completo com todos os dados
  • orderHeaderPagedResponse: Resposta paginada com múltiplos pedidos
  • orderHeaderPayloadMock: Payload para cadastro/atualização de pedido
  • Cabeçalho com empresa, cliente, pagamento, operação
  • Itens com produtos, quantidades e valores
  • Campos adicionais customizados

Exemplo de uso em testes:

import {
  orderHeaderResponse,
  orderHeaderPagedResponse,
} from "@/__mocks__/order-header.mock";

// Mock fetchRemote
const apiWithoutAccessToken: any = {
  get: jest.fn(async () => ({
    status: 200,
    data: orderHeaderPagedResponse,
  })),
};

const service = new OrderHeaderService({ apiWithoutAccessToken });
const result = await service.fetchRemote();

expect(result).toEqual(orderHeaderPagedResponse.content);

// Mock fetchRemoteById
const apiMock: any = {
  get: jest.fn(async () => ({
    status: 200,
    data: orderHeaderResponse,
  })),
};

const serviceById = new OrderHeaderService({
  apiWithoutAccessToken: apiMock,
});
const order = await serviceById.fetchRemoteById("oh-001");

expect(order).toEqual(orderHeaderResponse);

// Mock updateOrderHeader
import { orderHeaderPayloadMock } from "@/__mocks__/order-header.mock";

const updateApiMock: any = {
  put: jest.fn(async () => ({
    status: 200,
    data: orderHeaderResponse,
  })),
};

const updateService = new OrderHeaderService({
  apiWithoutAccessToken: updateApiMock,
});
const updated = await updateService.updateOrderHeader(
  "oh-001",
  orderHeaderPayloadMock,
);

expect(updated).toEqual(orderHeaderResponse);

// Mock registerOrderHeader
const registerApiMock: any = {
  post: jest.fn(async () => ({
    status: 200,
    data: orderHeaderResponse,
  })),
};

const registerService = new OrderHeaderService({
  apiWithoutAccessToken: registerApiMock,
});

const registered = await registerService.registerOrderHeader(
  orderHeaderPayloadMock,
);

expect(registered).toEqual(orderHeaderResponse);