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

1262 lines
46 KiB
Markdown
Raw 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](#1-visão-geral)
2. [Banco de Dados - Schema Completo](#2-banco-de-dados)
3. [Dashboard - Painel Principal](#3-dashboard)
4. [PDV - Ponto de Venda](#4-pdv)
5. [Trade-In - Gestão de Troca](#5-trade-in)
6. [Checklist de Avaliação](#6-checklist)
7. [Ordens de Serviço](#7-ordens-de-serviço)
8. [Devoluções e Trocas](#8-devoluções-e-trocas)
9. [Estoque e Depósitos](#9-estoque-e-depósitos)
10. [Comissões e Metas](#10-comissões-e-metas)
11. [Relatórios](#11-relatórios)
12. [Cadastros](#12-cadastros)
13. [Compras e Aquisições](#13-compras-e-aquisições)
14. [Créditos de Cliente](#14-créditos-de-cliente)
15. [Integração com Plus (Laravel)](#15-integração-plus)
16. [API - Endpoints Completos](#16-api-endpoints)
17. [Segurança e Multi-Tenant](#17-segurança)
---
## 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 Três Abas de Catálogo
#### 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:
```json
{
"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.
Reference in New Issue View Git Blame Copy Permalink