arcadia-admin
/
arcadiasuite
mirror of https://github.com/jonaspachecoometas/arcadiasuite.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
arcadiasuite/RELATORIO_TECNICO_RETAIL.md

46 KiB
Raw Permalink Blame History

Relatório Técnico Completo - Módulo Retail (Arcádia Suite)

Versão 1.0 - Fevereiro 2026

SUMÁRIO

  1. Visão Geral do Módulo
  2. Banco de Dados - Schema Completo
  3. Dashboard - Painel Principal
  4. PDV - Ponto de Venda
  5. Trade-In - Gestão de Troca
  6. Checklist de Avaliação
  7. Ordens de Serviço
  8. Devoluções e Trocas
  9. Estoque e Depósitos
  10. Comissões e Metas
  11. Relatórios
  12. Cadastros
  13. Compras e Aquisições
  14. Créditos de Cliente
  15. Integração com Plus (Laravel)
  16. API - Endpoints Completos
  17. Segurança e Multi-Tenant

1. VISÃO GERAL

1.1 Propósito

O módulo Arcádia Retail é o front-office da Suite, projetado especificamente para o segmento de Loja de Celulares e Assistência Técnica. Ele cobre todo o ciclo operacional: venda de dispositivos, avaliação de trade-in, ordens de serviço, gestão de estoque por IMEI, comissões de vendedores, e fechamento de caixa diário.

1.2 Métricas do Módulo

Métrica Valor
Frontend 10.067 linhas (ArcadiaRetail.tsx)
Backend 5.218 linhas (routes.ts)
Sync Plus 542 linhas (plus-sync.ts)
TradeIn Form 988 linhas (TradeInForm.tsx)
Total ~16.815 linhas de código
Tabelas no banco 40+ tabelas
Endpoints de API ~130 endpoints REST
Abas da interface 11 abas principais

1.3 Abas da Interface

# Aba Descrição
1 Dashboard Visão geral com KPIs, feed de atividades e alertas
2 PDV Ponto de Venda com carrinho, pagamento múltiplo e trade-in
3 Pessoas Cadastro unificado (clientes, fornecedores, técnicos)
4 Estoque Depósitos, saldos, movimentações, inventários e séries
5 Serviços Ordens de Serviço (externas e internas)
6 Trade-In Avaliações de dispositivos usados
7 Compras Pedidos de compra e recebimento de mercadoria
8 Cadastros Formas de pagamento, vendedores, planos, promoções, tipos
9 Relatórios 6 relatórios operacionais + detalhamento de vendas
10 Comissões Dashboard de comissões, metas e fechamento
11 Configuração Integração Plus, empresas, sincronização

2. BANCO DE DADOS - SCHEMA COMPLETO

2.1 Tabelas do Módulo Retail (40 tabelas)

Estrutura de Lojas e Depósitos

Tabela Campos-chave Descrição
retail_stores id, tenantId, code, name, storeType (holding/distributor/store), parentStoreId, cnpj, posEnabled, serviceEnabled, leaseEnabled Lojas e filiais na rede
retail_warehouses id, tenantId, storeId, code, name, type (store/central/transit/virtual), isMainWarehouse, isDefault, allowNegativeStock, visibleToAllCompanies Depósitos por loja ou central
retail_warehouse_stock warehouseId, productId, quantity, reservedQuantity, availableQuantity, minStock, maxStock Saldos por produto/depósito
retail_stock_movements warehouseId, productId, movementType (entry/exit/transfer/adjustment/return), operationType, quantity, previousStock, newStock, unitCost Movimentações detalhadas
retail_stock_transfers sourceWarehouseId, destinationWarehouseId, status (pending/in_transit/completed/cancelled) Transferências entre depósitos
retail_stock_transfer_items transferId, productId, requestedQuantity, transferredQuantity, receivedQuantity Itens da transferência
retail_transfer_serials transferItemId, serialId Séries/IMEIs vinculados
retail_product_serials productId, warehouseId, serialNumber, imei, imei2, status (in_stock/reserved/sold/returned/defective/in_transit), acquisitionCost, salePrice Números de série e IMEI
retail_inventories warehouseId, inventoryNumber, type (full/partial/cyclic), status (open/counting/adjusting/completed) Inventários
retail_inventory_items inventoryId, productId, systemQuantity, countedQuantity, difference, adjustmentApplied Itens do inventário

Dispositivos Móveis

Tabela Campos-chave Descrição
mobile_devices imei, imei2, brand, model, color, storage, ram, condition (new/refurbished/used), purchasePrice, sellingPrice, acquisitionType (trade_in/purchase/consignment), relatedEvaluationId, relatedServiceOrderId, personId, suggestedPrice, profitMargin, status (in_stock/sold/in_service/returned/damaged/leased) Celulares com IMEI
device_history deviceId, imei, eventType (received/transferred/sold/returned/service_in/service_out/leased/purchased), fromLocation, toLocation, referenceType, referenceId Histórico de movimentação por IMEI

PDV e Vendas

Tabela Campos-chave Descrição
pos_sessions storeId, cashierId, cashierName, openingBalance, closingBalance, totalSales, totalRefunds, netSales, cashPayments, cardPayments, pixPayments, otherPayments, transactionCount, status (open/closed/reconciled) Sessões de caixa
pos_sales saleNumber, saleType (direct_sale/lease_to_own), customerId, customerName, subtotal, discountAmount, discountPercent, tradeInValue, tradeInEvaluationId, totalAmount, paymentMethod (cash/debit/credit/pix/combined), paymentDetails (JSONB), soldBy, plusVendaId, plusSyncStatus, empresaId Vendas no PDV
pos_sale_items saleId, itemType (product/device/accessory/service), itemName, imei, deviceId, quantity, unitPrice, discountAmount, totalPrice Itens da venda
pos_cash_movements sessionId, storeId, type (withdrawal/reinforcement), amount, reason, performedBy, authorizedBy Sangria e reforço de caixa

Pagamentos e Parcelamento

Tabela Campos-chave Descrição
payment_plans saleId, customerId, totalAmount, downPayment, remainingAmount, numberOfInstallments, installmentAmount, interestRate, firstInstallmentDate, paidInstallments, status (active/completed/defaulted/cancelled) Planos de parcelamento
payment_plan_installments planId, installmentNumber, dueDate, amount, paidAmount, paidDate, paymentMethod, status (pending/paid/overdue/cancelled) Parcelas do plano

Locação com Opção de Compra

Tabela Campos-chave Descrição
lease_agreements agreementNumber, deviceId, imei, leaseStartDate, leaseEndDate, monthlyPayment, totalLeaseCost, purchaseOptionAvailable, purchasePrice, rentCreditPercent Contratos de locação
lease_payments leaseId, paymentNumber, dueDate, amount, paidAmount, status (pending/paid/overdue) Pagamentos da locação

Trade-In e Avaliações

Tabela Campos-chave Descrição
device_evaluations imei, brand, model, personId, 19 campos de checklist booleano (cada com campo de notas), batteryHealth, estimatedValue, acquisitionValue, status (pending/analyzing/approved/rejected), linkedServiceOrderId, maintenanceOrderId, creditGenerated, creditId Avaliações de Trade-In
trade_in_checklist_templates name, deviceCategory (smartphone/tablet/laptop/smartwatch), isActive Templates de checklist customizáveis
trade_in_checklist_items templateId, category (visual/funcional/acessorios/documentacao), itemName, evaluationType (condition/boolean/percentage/text), options (JSON), impactOnValue (% impacto), isRequired, displayOrder Itens do template
trade_in_evaluation_results evaluationId, checklistItemId, result, percentValue, notes Resultados por item
trade_in_transfer_documents evaluationId, documentNumber, customerName/CPF/RG/address, deviceBrand/Model/IMEI/IMEI2, agreedValue, customerSignature (Base64), termsAccepted, status (draft/pending_signature/signed/completed) Documento de transferência de posse
retail_acquisitions type (trade_in/purchase/consignment), sourceEvaluationId, sourceServiceOrderId, deviceId, acquisitionCost, repairCost, totalCost, suggestedPrice, finalPrice, status (pending/ready_for_stock/in_stock/sold) Aquisições processadas

Ordens de Serviço

Tabela Campos-chave Descrição
service_orders orderNumber, deviceId, imei, customerName, serviceType (repair/maintenance/internal_review/diagnostic), origin (customer_request/device_acquisition/warranty), assignedTo, technicianName, partsCost, laborCost, totalCost, isInternal, internalType (revision/cleaning/maintenance/quality_check/trade_in_diagnosis/trade_in_maintenance), sourceEvaluationId, checklistData (JSONB), status (12 estados) Ordens de Serviço
service_order_items serviceOrderId, productId, itemType (part/labor/accessory), itemName, quantity, unitPrice, totalPrice Peças e serviços da O.S.
service_warranties serviceOrderId, deviceId, imei, serviceType, warrantyDays, startDate, endDate, status (active/expired/claimed/voided) Garantias vinculadas

Devoluções

Tabela Campos-chave Descrição
return_exchanges returnNumber, originalSaleId, returnType (return/exchange), reason, refundAmount, refundMethod, status (pending/approved/rejected/processed) Devoluções e trocas
return_exchange_items returnId, itemName, imei, deviceId, reason, refundAmount Itens devolvidos

Cadastros e Configurações

Tabela Campos-chave Descrição
retail_payment_methods name, type (cash/debit/credit/pix/boleto/financing), brand (visa/mastercard/elo/amex/hipercard), feePercent, fixedFee, installmentsMax, installmentFees (JSONB), daysToReceive Formas de pagamento
retail_sellers personId, code, name, storeId, commissionPlanId, hireDate, isActive Vendedores
retail_commission_plans name, type (fixed/percent/tiered/per_product), baseValue, basePercent, rules (JSONB) Planos de comissão
retail_seller_goals sellerId, month, year, goalAmount, goalType (sales/units/margin), achievedAmount, achievedPercent, bonus Metas de vendedor
retail_store_goals storeId, month, year, goalAmount, achievedAmount, achievedPercent Metas da loja
retail_commission_closures sellerId, periodType (daily/monthly/custom), periodStart, periodEnd, totalSales, totalReturns, netSales, commissionRate, commissionAmount, bonusAmount, status (open/closed/paid) Fechamento de comissão
retail_commission_closure_items closureId, saleId, returnId, itemType (sale/return), amount, commission Vendas do fechamento
retail_price_tables name, customerType (retail/wholesale/vip/employee), discountPercent, markupPercent, validFrom, validTo Tabelas de preço
retail_price_table_items priceTableId, productId, deviceId, customPrice, discountPercent Preços por produto
retail_promotions name, type (percent_off/fixed_off/buy_x_get_y/bundle), discountValue, discountPercent, applyTo (all/category/product/brand), validFrom, validTo Promoções
retail_product_types name, category (device/accessory/part/service), requiresImei, requiresSerial, ncm, cest, origem, cstIcms, csosn, cfops (4 tipos), alíquotas (ICMS/PIS/COFINS/IPI), aliqIbs, aliqCbs Tipos com atributos fiscais
retail_activity_feed activityType, entityType, entityId, title, description, metadata (JSONB), severity (info/success/warning/error) Feed de atividades
retail_reports name, type (sales/inventory/commissions/financial/custom), query, filters (JSONB), columns (JSONB) Relatórios customizáveis

Créditos

Tabela Campos-chave Descrição
customer_credits personId, customerName, amount, remainingAmount, origin (trade_in/return/manual/promotion), status (active/used/expired/cancelled), expiresAt Créditos de cliente

3. DASHBOARD - PAINEL PRINCIPAL

3.1 KPIs em Tempo Real (5 Cards)

Card Fonte de Dados Cálculo
Dispositivos em Estoque mobile_devices WHERE status = 'in_stock' COUNT total
Vendas Hoje pos_sales WHERE DATE(created_at) = hoje AND status = 'completed' SUM(total_amount) + COUNT
OS Abertas service_orders WHERE status NOT IN ('completed','cancelled') COUNT
Trade-In Pendentes device_evaluations WHERE status = 'pending' COUNT
Ticket Médio Derivado todaySalesTotal / todaySalesCount

3.2 Componentes do Dashboard

Componente Descrição
Últimas Ordens de Serviço Lista das 5 O.S. mais recentes com número, dispositivo, cliente, status e valor
Avaliações de Trade-In Lista das 5 avaliações mais recentes com IMEI, dispositivo, cliente, condição, valor e status
Produtos com Estoque Baixo Alertas de produtos com stockQty < minStock, exibidos com badge vermelho
Feed de Atividades Timeline em tempo real (atualiza a cada 30s) com ícones por tipo (venda/serviço/avaliação), severidade colorida (info/success/warning/error), indicador de não-lido

3.3 Endpoint do Dashboard Stats

GET /api/retail/dashboard-stats

Queries executadas:

  1. COUNT de dispositivos em estoque
  2. SUM e COUNT de vendas do dia
  3. COUNT de O.S. abertas
  4. COUNT de avaliações pendentes

4. PDV - PONTO DE VENDA

4.1 Pré-requisitos para Usar o PDV

  1. Sessão de Caixa ativa (abertura obrigatória com saldo inicial)
  2. Empresa selecionada (seletor de empresa na barra superior)
  3. Vendedor selecionado (obrigatório para registrar vendas)

4.2 Layout do PDV (Grid 5 Colunas)

┌─────────────────────────────────────────┬───────────────────────┐
│   CATÁLOGO DE ITENS (3 colunas)         │   CARRINHO (2 colunas)│
│                                         │                       │
│   [Dispositivos] [Produtos] [Faturar OS]│   Lista de itens      │
│                                         │   Subtotal            │
│   Busca + Filtro                        │   - Desconto          │
│   Lista de itens disponíveis            │   - Trade-In          │
│   com preço e botão "Adicionar"         │   - Crédito           │
│                                         │   = TOTAL             │
│                                         │                       │
│                                         │   [Trade-In]          │
│                                         │   [FINALIZAR VENDA]   │
└─────────────────────────────────────────┴───────────────────────┘

4.3.1 Dispositivos (Celulares)

  • Busca: IMEI, marca, modelo, cor, armazenamento, preço
  • Filtro: Somente status "in_stock"
  • Exibição: Marca + Modelo, Storage | Cor | IMEI, Badge de condição (new/refurbished/used), Badge do depósito, Preço de venda
  • Ação: Botão "Adicionar" (desabilitado se IMEI já está no carrinho)
  • Tipo no carrinho: device com IMEI vinculado

4.3.2 Produtos (Acessórios, Peças)

  • Busca: Nome, código, descrição, código de barras, NCM
  • Filtro: Somente status "active"
  • Exibição: Nome, Código | Categoria, Badge de estoque (quantidade + unidade), Preço de venda
  • Ação: Botão "Adicionar" com quantidade editável
  • Tipo no carrinho: product

4.3.3 Faturar O.S. (Ordens de Serviço)

  • Busca: Número da O.S. ou nome do cliente
  • Filtro: O.S. com status "ready_pickup" (aguardando faturamento)
  • Exibição: Número da O.S., Cliente, Marca + Modelo, Descrição, Valor total
  • Ação: Botão "Faturar" (vincula a O.S. à venda)
  • Tipo no carrinho: service com serviceOrderId vinculado

4.4 Carrinho de Compras

Campo Descrição
Itens Lista com nome, descrição, badge de tipo (Celular/Serviço), preço unitário, botão remover
Subtotal Soma de todos os itens
Desconto Desconto em R$ ou % (configurável)
Trade-In Valor de abatimento de avaliação aprovada
Crédito Crédito disponível do cliente (trade-in anterior, devolução)
Total Subtotal - Desconto - TradeIn - Crédito

4.5 Ações do PDV

Botão Função
Sangria Retirada de dinheiro do caixa (exige motivo)
Reforço Adição de dinheiro ao caixa (exige motivo)
Devolução Abre fluxo de devolução/troca
Selecionar Cliente Busca/cadastro de pessoa unificada
Limpar Remove todos os itens do carrinho
Trade-In Inicia avaliação de dispositivo do cliente
Finalizar Venda Abre modal de pagamento

4.6 Fluxo de Finalização de Venda

1. Usuário clica "Finalizar Venda"
2. Modal de pagamento abre com:
   - Forma de pagamento padrão: Dinheiro (valor total)
   - Opções: Cash, Débito, Crédito, PIX, Combinado
   - Para Crédito: campo de parcelas
   - Para Combinado: múltiplas linhas de pagamento
   - Desconto: campo de % e R$
3. Ao confirmar:
   a. Cria registro em pos_sales
   b. Cria registros em pos_sale_items
   c. Atualiza status dos dispositivos para "sold"
   d. Atualiza estoque dos produtos
   e. Registra no activity_feed
   f. Gera impressão da venda (PDF A4)
   g. Sincroniza com Plus (se configurado)
   h. Limpa o carrinho

4.7 Impressão da Venda (PDF A4)

A impressão é chamada ANTES de limpar o carrinho para preservar os dados:

  • Formato: A4 (595 x 842pt)
  • Conteúdo: Número da venda, data/hora, dados da empresa, cliente, vendedor, lista de itens (produto, quantidade, unitário, total), subtotal, desconto, trade-in, total, forma de pagamento
  • Dispositivos: exibe IMEI
  • Produtos: exibe NCM (quando disponível)
  • Geração: via jspdf no navegador

4.8 Formas de Pagamento Suportadas

Método Campos
Dinheiro (cash) Valor
Débito (debit) Valor
Crédito (credit) Valor + Parcelas
PIX (pix) Valor
Combinado (combined) Múltiplas linhas (ex: R$ 500 PIX + R$ 300 Crédito 3x)

5. TRADE-IN - GESTÃO DE TROCA

5.1 Fluxo Completo do Trade-In (4 Etapas)

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  ETAPA 1     │    │  ETAPA 2     │    │  ETAPA 3     │    │  ETAPA 4     │
│  Avaliação   │───>│  Aprovação   │───>│  Revisão     │───>│  Estoque     │
│              │    │              │    │  (O.S. Int.) │    │              │
│ Checklist    │    │ Gera crédito │    │ Manutenção   │    │ Cria device  │
│ IMEI/Cliente │    │ Cria O.S.    │    │ Checklist    │    │ Preço suger. │
│ Valor estim. │    │ Registro     │    │ Peças/custos │    │ Disponível   │
│              │    │ IMEI history │    │              │    │ para venda   │
│ Status:      │    │ Status:      │    │ Status:      │    │ Status:      │
│ pending      │    │ approved     │    │ completed    │    │ in_stock     │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘

5.2 Etapa 1 - Avaliação

Dois modos de criação:

Avaliação Rápida (Dialog simples)

  • Campos: IMEI, Marca, Modelo, Cor, Cliente, Condição Geral, Valor Estimado
  • Uso: avaliação expressa sem checklist detalhado

Formulário Completo (TradeInForm - 988 linhas)

  • Dados do Cliente: Busca por nome/CPF na base de pessoas, cadastro rápido
  • Dados do Dispositivo: IMEI, Marca, Modelo, Cor, Armazenamento
  • Checklist Completo: 19 itens de verificação (ver seção 6)
  • Peças Necessárias: Lista de peças com valores
  • Valor de Avaliação: Calculado ou manual
  • Assinatura Digital: Canvas para assinatura do cliente (touchscreen/mouse)
  • Ações: Salvar, Imprimir PDF, Limpar

5.3 Etapa 2 - Aprovação

Endpoint: POST /api/retail/evaluations/:id/approve-and-process

O que acontece na aprovação:

  1. Status da avaliação muda para approved
  2. Cria O.S. Interna (INT${YYMM}RANDOM) com:
    • serviceType: "internal_review"
    • isInternal: true
    • internalType: "revision"
    • sourceEvaluationId: evaluationId
  3. Registra no IMEI History (ação: trade_in_approved, status: in_revision)
  4. Gera Crédito para o Cliente:
    • Busca pessoa pelo personId
    • Cria registro em customer_credits
    • Origem: trade_in
    • Status: active
    • Valor = estimatedValue da avaliação

5.4 Etapa 3 - Revisão (O.S. Interna)

A O.S. Interna segue o mesmo fluxo de uma O.S. normal mas com marcação isInternal = true:

  • Técnico pode preencher checklist de revisão
  • Adicionar peças utilizadas (custo de reparo)
  • Registrar mão de obra
  • Preencher diagnóstico

Endpoint de finalização: POST /api/retail/service-orders/:id/finalize-internal

5.5 Etapa 4 - Entrada no Estoque

Ao finalizar a O.S. Interna:

  1. Cria dispositivo em mobile_devices:
    • condition: "refurbished" (ou conforme avaliação)
    • acquisitionType: "trade_in"
    • acquisitionCost: estimatedValue + repairCost
    • relatedEvaluationId: evaluationId
    • relatedServiceOrderId: serviceOrderId
    • suggestedPrice: totalCost * (1 + profitMargin/100)
    • profitMargin: margem configurada (padrão 30%)
    • status: "in_stock"
  2. Registra no IMEI History (ação: entered_stock)
  3. Registra no Activity Feed (tipo: stock_in)

5.6 Consulta do Fluxo Completo

Endpoint: GET /api/retail/evaluations/:id/full-flow

Retorna:

{
  "evaluation": { ... },
  "serviceOrder": { ... },
  "device": { ... },
  "history": [ ... ],
  "flowStatus": "in_stock",
  "flowStep": 4,
  "steps": [
    { "step": 1, "name": "Avaliação", "status": "completed" },
    { "step": 2, "name": "Aprovação", "status": "completed" },
    { "step": 3, "name": "Revisão (O.S.)", "status": "completed" },
    { "step": 4, "name": "Estoque", "status": "completed" }
  ]
}

5.7 Uso do Crédito Trade-In no PDV

Quando o cliente com crédito ativo é selecionado no PDV:

  • Um banner azul aparece: "Crédito disponível: R$ X.XXX,XX"
  • O operador pode ativar "Usar crédito" como abatimento na compra
  • O crédito é deduzido automaticamente do total
  • Múltiplos créditos são somados (trade-in + devolução + manual)

6. CHECKLIST DE AVALIAÇÃO

6.1 Checklist Fixo (19 Itens Built-in)

O deviceEvaluations possui 19 campos booleanos fixos (cada um com campo de notas/observações):

# Campo Pergunta Tipo Impacto
1 powerOn Aparelho liga corretamente? Sim/Não Crítico
2 screenIssues Avarias, travamentos ou toque fantasma? Sim/Não Alto
3 screenSpots Manchas na tela? Sim/Não Médio
4 buttonsWorking Botões funcionando? Sim/Não Médio
5 wearMarks Marcas de uso? Sim/Não Baixo
6 wifiWorking Wi-Fi funcionando? Sim/Não Alto
7 simWorking Chip funcionando? Sim/Não Alto
8 mobileDataWorking 4G/5G funcionando? Sim/Não Alto
9 sensorsNfcWorking Sensores funcionando / NFC? Sim/Não Médio
10 biometricWorking Face ID / Touch ID funcionando? Sim/Não Alto
11 microphonesWorking Microfones funcionando? Sim/Não Alto
12 earSpeakerWorking Áudio auricular funcionando? Sim/Não Médio
13 loudspeakerWorking Áudio alto-falante funcionando? Sim/Não Médio
14 chargingPortWorking Entrada de carregamento funcionando? Sim/Não Alto
15 camerasWorking Câmeras funcionando / Manchas? Sim/Não Alto
16 flashWorking Flash funcionando? Sim/Não Baixo
17 hasCharger Possui carregador? Sim/Não Baixo
18 toolsAnalysisOk Análise pelo 3uTools OK? Sim/Não Alto
19 batteryHealth Saúde da Bateria 0-100% Alto

Cada campo possui um campo paralelo *Notes (texto) para observações adicionais.

6.2 Checklist do TradeInForm (Frontend - 19 Itens)

O componente TradeInForm.tsx implementa o checklist como array com:

  • ID único por item
  • Descrição da verificação
  • Valor: "sim" | "nao" | "" (não avaliado)
  • Observação: campo de texto livre
DEFAULT_CHECKLIST = [
  "Aparelho liga corretamente"
  "Avarias, travamentos ou toque fantasma"
  "Manchas na tela"
  "Botões funcionando"
  "Marcas de uso"
  "Wi-Fi funcionando"
  "Chip funcionando"
  "4G/5G funcionando"
  "Sensores funcionando / NFC"
  "Face ID / Touch ID funcionando"
  "Microfones funcionando"
  "Áudio auricular funcionando"
  "Áudio alto-falante funcionando"
  "Entrada de carregamento funcionando"
  "Câmeras funcionando / Manchas"
  "Flash funcionando"
  "Possui carregador"
  "Análise pelo 3uTools OK"
  "Saúde da Bateria (%)"
]

6.3 Sistema de Templates Customizáveis

Para além do checklist fixo, existe um sistema de templates:

Tabela Função
trade_in_checklist_templates Templates por categoria (smartphone, tablet, laptop, smartwatch)
trade_in_checklist_items Itens do template com: categoria (visual/funcional/acessorios/documentacao), tipo de avaliação (condition/boolean/percentage/text), opções JSON, % de impacto no valor, ordenação
trade_in_evaluation_results Resultados vinculados à avaliação e item do checklist

Tipos de avaliação:

  • condition: opções pré-definidas (ex: "perfeito", "bom", "regular", "ruim")
  • boolean: sim/não
  • percentage: valor de 0 a 100
  • text: texto livre

6.4 Checklist na O.S. (Diagnóstico)

As Ordens de Serviço possuem campo checklistData (JSONB) que armazena dados de checklist de forma flexível:

  • Preenchido pelo técnico durante diagnóstico
  • Endpoint: PUT /api/retail/service-orders/:id/checklist
  • Timestamp de conclusão: checklistCompletedAt
  • Autor: checklistCompletedBy

7. ORDENS DE SERVIÇO

7.1 Tipos de O.S.

Tipo serviceType Origem Descrição
Reparo (cliente) repair customer_request Cliente traz dispositivo para conserto
Manutenção maintenance customer_request Manutenção preventiva
Diagnóstico diagnostic customer_request Apenas diagnóstico/orçamento
Revisão Interna internal_review device_acquisition Revisão de dispositivo Trade-In
Garantia repair warranty Reparo coberto por garantia

7.2 Fluxo de Status da O.S. (12 Estados)

open → diagnosis → quote → pending_approval → approved → in_repair → waiting_parts → quality_check → ready_pickup → completed
                                     ↓                                                        ↓
                                  rejected                                                 cancelled
Status Descrição
open Recém-criada, aguardando atendimento
diagnosis Em diagnóstico pelo técnico
quote Orçamento elaborado, aguardando aprovação
pending_approval Enviado para aprovação do cliente
approved Cliente aprovou o orçamento
rejected Cliente rejeitou o orçamento
in_repair Em reparo ativo
waiting_parts Aguardando peças/componentes
quality_check Verificação de qualidade pós-reparo
ready_pickup Pronto para retirada pelo cliente
completed Concluída e entregue
cancelled Cancelada

7.3 Campos da O.S.

  • Identificação: Número (auto-gerado), Loja, Prioridade (low/normal/high/urgent)
  • Dispositivo: IMEI, Marca, Modelo, deviceId
  • Cliente: Nome, Telefone, Email, personId (pessoa unificada)
  • Técnico: Nome, personId do técnico
  • Custos: Peças (partsCost), Mão de obra (laborCost), Total (totalCost)
  • Datas: Data esperada, Data real de conclusão
  • Pagamento: Status (pending/paid/partial)
  • O.S. Interna: isInternal, internalType, sourceEvaluationId

7.4 Itens da O.S.

Cada O.S. pode ter múltiplos itens:

  • Peça (part): Componente utilizado no reparo
  • Mão de obra (labor): Serviço técnico
  • Acessório (accessory): Acessório incluído

7.5 Garantias de Serviço

Ao concluir uma O.S., pode-se criar uma garantia vinculada:

  • Vincula à O.S. e ao IMEI
  • Define prazo em dias (ex: 90 dias)
  • Status: active → expired (automático) ou claimed (cliente acionou)
  • Consulta de garantia por IMEI: GET /api/retail/warranties/check/:imei

7.6 Faturamento de O.S. no PDV

Quando uma O.S. está com status ready_pickup:

  1. Aparece na aba "Faturar O.S." do PDV
  2. O operador adiciona ao carrinho como item de serviço
  3. A venda é registrada normalmente
  4. A O.S. é marcada como completed

8. DEVOLUÇÕES E TROCAS

8.1 Fluxo de Devolução

1. Operador clica "Devolução" no PDV
2. Busca venda original por número ou cliente
3. Seleciona itens para devolver
4. Define motivo e método de reembolso
5. Verificação de senha do gerente (MANAGER_PASSWORD)
6. Processamento:
   a. Cria registro em return_exchanges
   b. Cria itens em return_exchange_items
   c. Para dispositivos: reverte status do mobile_device para "returned"
   d. Para produtos: ajusta estoque
   e. Gera crédito para o cliente (customer_credits)
   f. Registra no IMEI history (para dispositivos)
   g. Registra no activity feed

8.2 Tipos

Tipo Descrição
return Devolução pura (reembolso)
exchange Troca por outro produto

8.3 Métodos de Reembolso

  • Crédito na loja (gera customer_credits)
  • Dinheiro
  • Estorno no cartão
  • PIX

8.4 Busca de Vendas para Devolução

Endpoint: GET /api/retail/sales-for-return?search=...

Busca por:

  • Número da venda (saleNumber)
  • Nome do cliente
  • CPF do cliente

Retorna vendas com status "completed" + itens detalhados.

8.5 Segurança

A devolução exige senha do gerente (MANAGER_PASSWORD) para ser processada. Endpoint de verificação: POST /api/retail/verify-manager-password.

9. ESTOQUE E DEPÓSITOS

9.1 Tipos de Depósito

Tipo Descrição
store Depósito vinculado a uma loja
central Depósito central (distribuição)
transit Em trânsito entre depósitos
virtual Depósito virtual (ex: consignação)

9.2 Movimentações de Estoque

Tipo de Movimento Operação Descrição
entry purchase Entrada por compra
entry trade_in Entrada por trade-in
entry manual_entry Entrada manual
entry devolution Entrada por devolução
exit sale Saída por venda
transfer_in - Recebimento de transferência
transfer_out - Envio para transferência
adjustment inventory_adjustment Ajuste de inventário
return - Retorno (devolução)

9.3 Transferências entre Depósitos

Fluxo: pending → in_transit → completed

Cada transferência registra:

  • Depósito de origem e destino
  • Itens com quantidade solicitada, transferida e recebida
  • Números de série/IMEI vinculados
  • Responsáveis (solicitante, aprovador, recebedor)

9.4 Inventário

Tipos: full (completo), partial (parcial), cyclic (cíclico)

Fluxo: open → counting → adjusting → completed

Para cada item do inventário:

  • Sistema mostra quantidade no sistema
  • Operador informa quantidade contada
  • Sistema calcula diferença
  • Ao aplicar ajuste: cria movimentação automática

10. COMISSÕES E METAS

10.1 Dashboard de Comissões

O dashboard exibe para cada vendedor:

  • Total de vendas no período
  • Número de vendas
  • Ticket médio
  • Comissão calculada
  • Meta vs Realizado (progress bar)
  • Comparativo entre vendedores

10.2 Planos de Comissão

Tipo Descrição
fixed Valor fixo por venda
percent Percentual sobre o valor da venda
tiered Faixas progressivas (rules JSONB)
per_product Comissão específica por produto/categoria

10.3 Metas

  • Por Vendedor: goalAmount, goalType (sales/units/margin), achievedAmount, achievedPercent, bonus
  • Por Loja: goalAmount, achievedAmount, achievedPercent

10.4 Fechamento de Comissão

O fechamento consolida vendas e devoluções em um período:

POST /api/retail/commission-closures/calculate

Input: sellerId, periodStart, periodEnd, commissionRate
Output: {
  totalSales,
  totalReturns (devoluções deduzidas),
  netSales (vendas líquidas),
  salesCount,
  returnsCount,
  commissionAmount,
  items: [ { saleId, amount, commission } ]
}

Status do fechamento: open → closed → paid

11. RELATÓRIOS

11.1 Relatórios Disponíveis (6 + 1)

# Relatório Endpoint Descrição
1 OS por Status GET /reports/os-by-status Quantidade e valor total por status
2 OS por Técnico GET /reports/os-by-technician Total de O.S., concluídas, em andamento, receita por técnico
3 Vendas por Vendedor GET /reports/sales-by-seller Total vendas, receita, ticket médio, dias ativos
4 Margem por IMEI GET /reports/margin-by-imei Custo, venda, margem absoluta e %, status
5 Caixa Diário GET /reports/daily-cash Fechamento completo do dia
6 Giro de Estoque GET /reports/stock-turnover Estoque atual, vendas 30d, turnover ratio
7 Detalhamento de Vendas GET /sales?detailed=true Lista completa com filtros

11.2 Caixa Diário (Detalhamento)

O relatório de caixa diário é o mais completo, executando 4 queries:

Query 1 - Resumo:

  • Total de vendas (R$)
  • Quantidade de vendas
  • Total em dinheiro
  • Total em cartão (débito + crédito)
  • Total em PIX
  • Total combinado

Query 2 - Movimentações:

  • Total de sangrias
  • Total de reforços

Query 3 - Listagem de Vendas:

  • Cada venda com: número, hora, cliente, vendedor, subtotal, desconto, total, forma de pagamento

Query 4 - Vendas por Vendedor: Para cada vendedor, breakdown completo:

Coluna Descrição
Vendedor Nome
Vendas Quantidade
Dinheiro Total em cash
Débito Total em débito
Crédito Total em crédito
PIX Total em PIX
Combinado Total combinado
Descontos Total de descontos concedidos
Total Receita líquida

Linha de rodapé com totalizadores gerais.

Cálculo do Saldo do Caixa:

Saldo = Dinheiro + Reforços - Sangrias

12. CADASTROS

12.1 Formas de Pagamento

CRUD completo com campos:

  • Nome, Tipo (cash/debit/credit/pix/boleto/financing)
  • Bandeira (visa/mastercard/elo/amex/hipercard)
  • Taxa (%), Taxa fixa (R$)
  • Máximo de parcelas
  • Taxas por parcela (JSONB: [{installments, feePercent}])
  • Dias para recebimento

12.2 Vendedores

CRUD com vínculo a:

  • Pessoa unificada (personId)
  • Loja (storeId)
  • Plano de comissão (commissionPlanId)
  • Data de contratação

12.3 Planos de Comissão

Tipos: fixed, percent, tiered, per_product Regras customizáveis via JSONB

12.4 Tabelas de Preço

  • Tipos de cliente: retail, wholesale, vip, employee
  • Desconto ou markup percentual
  • Validade (de/até)
  • Itens específicos com preço customizado

12.5 Promoções

  • Tipos: percent_off, fixed_off, buy_x_get_y, bundle
  • Aplicação: all, category, product, brand
  • Quantidade mínima/máxima
  • Período de validade

12.6 Tipos de Produto

Com atributos fiscais completos:

  • Categoria: device, accessory, part, service
  • Controle: requiresImei, requiresSerial
  • Fiscal: NCM, CEST, Origem, CST ICMS, CSOSN, CFOPs (4 tipos), Alíquotas (ICMS, PIS, COFINS, IPI)
  • Reforma Tributária: IBS e CBS (preparado)
  • Unidade de medida

13. COMPRAS E AQUISIÇÕES

13.1 Pedidos de Compra

Fluxo: draft → submitted → approved → partially_received → received → cancelled

Campos: fornecedor, depósito destino, itens (produto, quantidade, preço), condições de pagamento, frete, desconto, totais.

13.2 Recebimento de Mercadoria

Endpoint: POST /api/retail/purchase-orders/:id/receive

Ao receber:

  1. Atualiza quantidades recebidas por item
  2. Cria movimentações de estoque (entry/purchase)
  3. Atualiza saldos no depósito destino
  4. Registra números de série quando aplicável
  5. Atualiza status do pedido

14. CRÉDITOS DE CLIENTE

14.1 Origens de Crédito

Origem Quando é gerado
trade_in Aprovação de avaliação de Trade-In
return Devolução com reembolso em crédito
manual Criação manual pelo operador
promotion Promoção que gera crédito

14.2 Ciclo de Vida

active → used (parcial ou total) → expired → cancelled

14.3 Uso no PDV

Quando o cliente é selecionado:

  1. Sistema busca customer_credits com status active e remainingAmount > 0
  2. Soma total de créditos disponíveis
  3. Exibe banner: "Crédito disponível: R$ X.XXX,XX"
  4. Operador pode ativar abatimento
  5. Na finalização, deduz do crédito mais antigo primeiro (FIFO)
  6. Registra uso parcial (atualiza remainingAmount) ou total (status → used)

14.4 Recibo de Crédito

Endpoint: GET /api/retail/customer-credits/:creditId/receipt

Gera dados para impressão do comprovante de crédito.

15. INTEGRAÇÃO COM PLUS (LARAVEL)

15.1 Componentes da Integração

Arquivo Função
server/plus/proxy.ts Proxy reverso /plus/* → Laravel :8080
server/plus/sso.ts SSO via token HMAC-SHA256
server/plus/launcher.ts Auto-start do Laravel (php artisan serve)
server/plus/client.ts Cliente REST para API do Plus
server/retail/plus-sync.ts Sincronização Retail → Plus

15.2 Sincronização Retail → Plus

Entidade Suite Entidade Plus Endpoint
Persons (clientes) Clientes POST /api/retail/plus/sync/customers
POS Sales + Items Vendas + Itens + Faturamento POST /api/retail/plus/sync/sales
POS Sales NF-e/NFC-e POST /api/retail/plus/sync/nfe

15.3 Campos de Sync na pos_sales

Campo Descrição
plusVendaId ID da venda criada no Plus
plusNfeChave Chave de acesso da NF-e emitida
plusSyncStatus pending → synced → error → not_applicable
plusSyncError Mensagem de erro (se houver)
plusSyncedAt Timestamp da sincronização
empresaId ID da empresa (tenant_empresas) vinculada

16. API - ENDPOINTS COMPLETOS

16.1 Listagem por Domínio

Todos os endpoints estão sob /api/retail/* e requerem autenticação.

Activity Feed (2)

GET  /activity-feed
POST /activity-feed/mark-read

Formas de Pagamento (4)

GET    /payment-methods
POST   /payment-methods
PUT    /payment-methods/:id
DELETE /payment-methods/:id

Vendedores (4)

GET    /sellers
POST   /sellers
PUT    /sellers/:id
DELETE /sellers/:id

Planos de Comissão (4)

GET    /commission-plans
POST   /commission-plans
PUT    /commission-plans/:id
DELETE /commission-plans/:id

Tabelas de Preço (4)

GET    /price-tables
POST   /price-tables
PUT    /price-tables/:id
DELETE /price-tables/:id

Promoções (4)

GET    /promotions
POST   /promotions
PUT    /promotions/:id
DELETE /promotions/:id

Tipos de Produto (5)

GET    /product-types
GET    /product-types/:id
POST   /product-types
PUT    /product-types/:id
DELETE /product-types/:id

Lojas (3)

GET  /stores
POST /stores
PUT  /stores/:id

Depósitos (4)

GET    /warehouses
POST   /warehouses
PUT    /warehouses/:id
DELETE /warehouses/:id

Saldos de Estoque (2)

GET /warehouse-stock
GET /warehouse-stock/:warehouseId/summary

Movimentações de Estoque (2)

GET  /stock-movements
POST /stock-movements

Números de Série (3)

GET  /product-serials
POST /product-serials
PUT  /product-serials/:id

Transferências (4)

GET  /stock-transfers
GET  /stock-transfers/:id
POST /stock-transfers
PUT  /stock-transfers/:id/status

Inventários (5)

GET  /inventories
POST /inventories
GET  /inventories/:id
PUT  /inventories/:id/count
PUT  /inventories/:id/apply

Dispositivos (5)

GET  /devices
GET  /devices/:id
GET  /devices/imei/:imei
POST /devices
PUT  /devices/:id

Avaliações / Trade-In (10)

GET  /evaluations
GET  /evaluations/:id
POST /evaluations
PUT  /evaluations/:id
PUT  /evaluations/:id/approve
PUT  /evaluations/:id/reject
PUT  /evaluations/:id/start-analysis
POST /evaluations/:id/approve-and-process
GET  /evaluations/:id/full-flow
GET  /evaluations/:id/service-order

Ordens de Serviço (8)

GET    /service-orders
GET    /service-orders/:id
POST   /service-orders
PUT    /service-orders/:id
PUT    /service-orders/:id/complete-preparation
POST   /service-orders/:id/items
GET    /service-orders/:id/items
DELETE /service-orders/:id/items/:itemId
PUT    /service-orders/:id/checklist
POST   /service-orders/:id/finalize-internal

Sessões de Caixa (3)

GET  /pos-sessions
POST /pos-sessions/open
PUT  /pos-sessions/:id/close

Movimentações de Caixa (2)

GET  /cash-movements
POST /cash-movements

Garantias (4)

GET  /warranties
POST /warranties
GET  /warranties/check/:imei
PUT  /warranties/:id/claim

Alertas de Estoque (1)

GET /stock-alerts

Relatórios (7)

GET /reports/os-by-status
GET /reports/os-by-technician
GET /reports/sales-by-seller
GET /reports/margin-by-imei
GET /reports/daily-cash
GET /reports/stock-turnover
GET /dashboard-stats

Vendas (1)

GET /sales

Pessoas (7)

GET    /persons
GET    /persons/:id
POST   /persons
PUT    /persons/:id
POST   /persons/:id/roles
PUT    /persons/:id/roles/:roleId
DELETE /persons/:id/roles/:roleType

Histórico por Pessoa (4)

GET /persons/:id/sales
GET /persons/:id/services
GET /persons/:id/trade-ins
GET /persons/:id/credits

Histórico por IMEI (3)

GET /devices/:imei/history
GET /devices/by-origin/:originType
GET /inventory/by-origin

Trade-In Workflow (2)

GET /customer-trade-ins/:personId

Segurança (1)

POST /verify-manager-password

Devoluções (5)

GET  /sales-for-return
GET  /returns
POST /returns
GET  /customer-credits/:personId
GET  /customer-credits/:creditId/receipt
POST /customer-credits/:creditId/use

Metas de Vendedor (4)

GET    /seller-goals
POST   /seller-goals
PUT    /seller-goals/:id
DELETE /seller-goals/:id

Metas da Loja (3)

GET  /store-goals
POST /store-goals
PUT  /store-goals/:id

Fechamento de Comissão (4)

GET  /commission-closures
POST /commission-closures
PUT  /commission-closures/:id
POST /commission-closures/calculate
GET  /commission-dashboard

Compras (5)

GET    /purchase-orders
GET    /purchase-orders/:id
POST   /purchase-orders
PATCH  /purchase-orders/:id/status
POST   /purchase-orders/:id/receive
DELETE /purchase-orders/:id

Plus Sync (8)

GET  /plus/status
POST /plus/sync/customers
POST /plus/sync/sales
POST /plus/sync/nfe
POST /plus/import/customers
POST /plus/import/products
GET  /plus/empresas
POST /plus/empresas
POST /plus/empresas/:id/bind

ERPNext Sync (8)

GET  /sync/status
POST /sync/persons/:id
POST /sync/persons
POST /sync/devices/:id
POST /sync/service-orders/:id
POST /sync/import/customers
POST /sync/import/suppliers
POST /sync/full
POST /sync/stock-entry
POST /sync/sales-invoice

Total: ~130 endpoints

17. SEGURANÇA E MULTI-TENANT

17.1 Autenticação

  • Todas as rotas exigem requireAuth (Passport.js session)
  • Verificação: req.isAuthenticated()

17.2 Tenant Scoping

  • Todos os relatórios e consultas filtram por tenantId
  • Se tenantId estiver ausente, retorna 403
  • Dados de um tenant nunca vazam para outro

17.3 Module Gating

  • Middleware requireModule(key) verifica se módulo está ativo no tenant
  • Verifica campo JSONB tenants.features[key]
  • Retorna 403 com ação sugerida se módulo inativo

17.4 Operações Sensíveis

  • Devoluções exigem senha do gerente (MANAGER_PASSWORD)
  • Verificação via endpoint dedicado
  • Sangrias de caixa registram responsável e autorizador

17.5 Auditoria

  • Todas as operações relevantes registram no retail_activity_feed
  • IMEI history rastreia toda movimentação de dispositivos
  • Device history registra eventos por IMEI

CONCLUSÃO

O módulo Retail da Arcádia Suite é uma solução completa e verticalmente integrada para lojas de celulares e assistência técnica, com ~16.800 linhas de código, 40+ tabelas, e ~130 endpoints REST. Ele cobre todo o ciclo operacional desde a aquisição de dispositivos (compra ou trade-in), passando pela gestão de estoque por IMEI, ordens de serviço com checklist detalhado, PDV com múltiplas formas de pagamento, até o fechamento de caixa com breakdown por vendedor e tipo de pagamento. A integração com o Plus (Laravel) permite emissão de NF-e/NFC-e e sincronização completa de dados fiscais.