22 KiB

Raw Blame History

Plano de Implementação - Módulo Retail (Loja de Celular e Assistência Técnica)

Versão: 1.1
Data: Janeiro 2026
Status: Em Desenvolvimento

0. Requisitos Especiais Identificados

0.1 Fluxo Trade-In → O.S. Interna → Estoque

Quando um aparelho Trade-In é aprovado para aquisição, deve:

Criar automaticamente uma Ordem de Serviço Interna para revisão/manutenção
Ao finalizar a O.S., o aparelho entra no estoque como produto normal
O estoque deve diferenciar a origem: Trade-In vs Fornecedor

┌─────────────────┐     ┌───────────────────┐     ┌─────────────────┐
│   TRADE-IN      │     │   O.S. INTERNA    │     │    ESTOQUE      │
│   (Avaliação)   │ ──→ │   (Revisão)       │ ──→ │   (Disponível)  │
└─────────────────┘     └───────────────────┘     └─────────────────┘
     │                        │                        │
     ▼                        ▼                        ▼
 • Checklist OK           • Limpeza                • Origem: Trade-In
 • Valor acordado         • Teste funcional        • Custo: valor + OS
 • Assinatura             • Troca peças?           • Preço venda
 • Documento legal        • Laudo técnico          • IMEI rastreado

0.2 Cadastro Unificado de Pessoas

Uma única tabela de Pessoas com múltiplos papéis:

Cliente
Fornecedor
Colaborador/Funcionário
Técnico
Representante

┌─────────────────────────────────────────────────────────────────┐
│                      PESSOA (person)                            │
│  • id, nome, cpf_cnpj, email, telefone, endereço               │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ CLIENTE  │   │FORNECEDOR│   │COLABORADOR│
        │ (role)   │   │ (role)   │   │ (role)    │
        └──────────┘   └──────────┘   └──────────┘

1. Análise do Estado Atual

1.1 O Que Já Temos Implementado

Módulo	Funcionalidade	Status	Observações
Estrutura Base	Schema de tabelas (mobile_devices, device_evaluations, service_orders, pos_sales, stock_transfers)	✅ Completo	Alinhado com requisitos
Lojas/Filiais	CRUD de lojas (retail_stores) e armazéns (retail_warehouses)	✅ Completo	Suporte multi-loja
Dispositivos/IMEI	Cadastro, busca por IMEI, listagem	✅ Básico	Falta histórico (Kardex)
Trade-In	Avaliação com checklist customizável, termo de transferência, assinatura digital	✅ Completo	Documento imprimível
Ordens de Serviço	CRUD básico, itens da OS	✅ Parcial	Falta fluxo completo de status
PDV	Sessões, vendas básicas, itens	✅ Parcial	Falta carrinho funcional no frontend
Transferências	Estrutura para transferência entre lojas	✅ Parcial	Falta workflow completo
Dashboard	Estatísticas básicas	✅ Básico	Pode ser expandido

1.2 O Que Está Faltando (Gap Analysis)

Requisito (Documento)	Status	Prioridade	Esforço
Histórico completo de IMEI (Kardex)	❌ Não implementado	Alta	Médio
Geração de etiquetas com código de barras	❌ Não implementado	Alta	Baixo
Fluxo completo de status da O.S.	⚠️ Parcial	Alta	Médio
Orçamentação automática	❌ Não implementado	Alta	Médio
Notificação ao cliente (WhatsApp/SMS)	⚠️ Integração existe	Média	Baixo
Portal público de consulta O.S.	❌ Não implementado	Média	Baixo
PDV com carrinho funcional	⚠️ Parcial	Alta	Alto
Validação IMEI na venda	❌ Não implementado	Alta	Baixo
Baixa automática de peças	❌ Não implementado	Alta	Médio
Separação estoque venda/reparo	⚠️ Via warehouses	Média	Baixo
Impressão de recibos/comprovantes	❌ Não implementado	Média	Médio
Relatórios específicos	⚠️ Parcial (BI existe)	Média	Médio

2. Arquitetura de Integração

2.1 Reutilização de Módulos Existentes

┌─────────────────────────────────────────────────────────────────┐
│                    ARCÁDIA SUITE (Base)                         │
├─────────────────────────────────────────────────────────────────┤
│  ✅ Clientes (customers) → Usar cadastro existente             │
│  ✅ Produtos (products) → Usar cadastro existente               │
│  ✅ Fornecedores (suppliers) → Usar cadastro existente          │
│  ✅ Usuários/Funcionários (users) → Usar sistema de auth        │
│  ✅ WhatsApp (Baileys) → Integrar notificações                  │
│  ✅ ERPNext → Sincronizar dados quando conectado                │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MÓDULO RETAIL (Novo)                         │
├─────────────────────────────────────────────────────────────────┤
│  📱 Dispositivos (mobile_devices) → Controle por IMEI          │
│  🔧 Ordens de Serviço (service_orders) → Assistência Técnica   │
│  💰 PDV (pos_sales) → Ponto de Venda                            │
│  📦 Estoque Retail (via warehouses) → Peças e Aparelhos        │
│  🔄 Trade-In (device_evaluations) → Avaliação de usados        │
│  🏪 Multi-Loja (retail_stores) → Franquias                     │
└─────────────────────────────────────────────────────────────────┘

2.2 Fluxo de Status da O.S. (Implementar)

┌──────────┐    ┌────────────┐    ┌───────────┐    ┌────────────────────┐
│  ABERTA  │ → │ DIAGNÓSTICO│ → │ ORÇAMENTO │ → │ AGUARDANDO_APROVAÇÃO│
└──────────┘    └────────────┘    └───────────┘    └────────────────────┘
                                                            │
                    ┌───────────────────────────────────────┴────┐
                    ▼                                            ▼
            ┌────────────┐                              ┌────────────┐
            │  RECUSADA  │                              │  APROVADA  │
            └────────────┘                              └────────────┘
                                                              │
                    ┌─────────────────────────────────────────┘
                    ▼
            ┌─────────────────┐    ┌───────────┐    ┌──────────┐
            │ AGUARDANDO_PECA │ ← │ EM_REPARO │ → │ QUALIDADE │
            └─────────────────┘    └───────────┘    └──────────┘
                                                          │
                                                          ▼
                                        ┌─────────────────────────┐
                                        │ AGUARDANDO_RETIRADA     │
                                        └─────────────────────────┘
                                                          │
                                                          ▼
                                                  ┌─────────────┐
                                                  │ FINALIZADA  │
                                                  └─────────────┘

3. Plano de Implementação por Fases

Fase 0: Estrutura Base - Pessoas e Trade-In Flow (Semana 0-1) ⭐ PRIORIDADE

0.1 Cadastro Unificado de Pessoas

Criar tabela persons com campos base (nome, cpf_cnpj, email, telefone, endereço)
Criar tabela person_roles (person_id, role_type, dados específicos do papel)
Tipos de papel: customer, supplier, employee, technician, partner
API CRUD /persons com filtro por papel
Migrar referências de customers/suppliers para usar persons
UI unificada de cadastro de pessoas com seleção de papéis

0.2 Fluxo Trade-In → O.S. Interna → Estoque

Adicionar campo origin_type em mobile_devices (trade_in, supplier, internal)
Adicionar campo is_internal em service_orders para diferenciar OS cliente vs interna
Criar trigger automático: ao aprovar Trade-In → criar O.S. Interna
O.S. Interna com tipo: revisão, limpeza, manutenção preventiva
Ao finalizar O.S. Interna → criar dispositivo no estoque
Calcular custo total: valor_trade_in + custo_os
Sugerir preço de venda baseado em margem configurável
UI de acompanhamento do fluxo Trade-In completo

0.3 Diferenciação de Estoque por Origem

Campo acquisition_type em mobile_devices: trade_in, purchase, consignment
Campo acquisition_cost (custo de aquisição)
Campo related_evaluation_id (link com avaliação Trade-In)
Campo related_service_order_id (link com O.S. de revisão)
Filtros no estoque por origem
Relatório de margem por origem

Fase 1: Completar o Núcleo (Semana 2-3)

1.1 Histórico de IMEI (Kardex)

Criar tabela imei_history no schema
API para registrar movimentações automáticas
Endpoint GET /devices/:imei/history
UI de visualização do histórico do dispositivo

1.2 Fluxo Completo de O.S.

Atualizar enum de status conforme fluxograma
API PATCH /service-orders/:id/status com validação de transições
Registrar automaticamente em imei_history
UI com workflow visual de status
Diferenciar O.S. Cliente vs O.S. Interna na listagem

1.3 Orçamentação

API POST /service-orders/:id/generate-quote
Cálculo automático baseado em itens adicionados
UI para adicionar peças/serviços e visualizar orçamento
Impressão de orçamento

1.4 Geração de Etiquetas

API GET /devices/:imei/label retornando PDF
Incluir código de barras (IMEI + número OS)
Botão de impressão na tela de dispositivo/OS

Fase 2: PDV Funcional (Semana 3-4)

2.1 Carrinho de Vendas

Componente de carrinho no frontend
Busca de produtos por código/nome
Leitura de IMEI para aparelhos
Validação de IMEI disponível para venda

2.2 Integração Venda + O.S.

Adicionar O.S. finalizada como item da venda
Baixa automática de peças no fechamento da OS

2.3 Formas de Pagamento

UI para múltiplas formas de pagamento
Cálculo de troco
Integração Trade-In como forma de pagamento

2.4 Recibos e Comprovantes

Geração de recibo de venda (impressão)
Comprovante de entrega de OS

Fase 3: Automação e Comunicação (Semana 5-6)

3.1 Notificações ao Cliente

Integrar com WhatsApp existente (Baileys)
Templates de mensagem: orçamento pronto, OS pronta, lembrete
API POST /service-orders/:id/notify-customer
Histórico de notificações enviadas

3.2 Portal do Cliente (Público)

Rota pública GET /public/os/:orderNumber
Página simples de consulta de status
QR Code na etiqueta/recibo

3.3 Relatórios Específicos

OS por período/técnico/status
Vendas por vendedor/produto/período
Tempo médio de reparo
Peças mais utilizadas

Fase 4: Estoque Avançado (Semana 7-8)

4.1 Separação Estoque Venda/Reparo

Categorização de warehouses (tipo: venda/reparo)
Regras de transferência entre tipos
Alertas de estoque mínimo por categoria

4.2 Baixa Automática de Peças

Trigger ao finalizar reparo
Reserva de peças ao aprovar OS
Liberação se OS cancelada

4.3 Inventário por IMEI

Listagem de aparelhos em estoque por IMEI
Localização física (prateleira/loja)
Tempo em estoque

4. APIs a Implementar

4.0 Módulo Pessoas (Prioridade Máxima) ⭐

Método	Endpoint	Descrição	Status
GET	`/persons`	Listar pessoas (filtro por papel)	❌ Fazer
POST	`/persons`	Criar pessoa	❌ Fazer
GET	`/persons/:id`	Detalhes da pessoa	❌ Fazer
PUT	`/persons/:id`	Atualizar pessoa	❌ Fazer
POST	`/persons/:id/roles`	Adicionar papel à pessoa	❌ Fazer
DELETE	`/persons/:id/roles/:role`	Remover papel	❌ Fazer
GET	`/persons/search?q=`	Buscar por nome/CPF	❌ Fazer

4.1 Módulo Trade-In Flow (Prioridade Máxima) ⭐

Método	Endpoint	Descrição	Status
POST	`/evaluations/:id/approve-and-process`	Aprovar e criar O.S. Interna	❌ Fazer
GET	`/evaluations/:id/full-flow`	Status completo do fluxo	❌ Fazer
POST	`/service-orders/:id/finalize-internal`	Finalizar OS e criar no estoque	❌ Fazer

4.2 Módulo IMEI (Prioridade Alta)

Método	Endpoint	Descrição	Status
GET	`/devices/:imei/history`	Histórico completo (Kardex)	❌ Fazer
GET	`/devices/:imei/label`	Gerar etiqueta PDF	❌ Fazer
PATCH	`/devices/:id/status`	Atualizar status c/ registro	❌ Fazer
GET	`/devices?origin=trade_in`	Filtrar por origem	❌ Fazer

4.3 Módulo O.S. (Prioridade Alta)

Método	Endpoint	Descrição	Status
POST	`/service-orders/:id/generate-quote`	Gerar orçamento	❌ Fazer
PATCH	`/service-orders/:id/status`	Workflow de status	⚠️ Melhorar
POST	`/service-orders/:id/notify-customer`	Enviar notificação	❌ Fazer
GET	`/public/os/:orderNumber`	Consulta pública	❌ Fazer
GET	`/service-orders?is_internal=true`	Filtrar OS internas	❌ Fazer

4.4 Módulo Vendas (Prioridade Alta)

Método	Endpoint	Descrição	Status
POST	`/sales/validate-imei`	Validar IMEI para venda	❌ Fazer
GET	`/sales/:id/receipt`	Gerar recibo PDF	❌ Fazer

4.5 Módulo Estoque (Prioridade Média)

Método	Endpoint	Descrição	Status
POST	`/inventory/:id/decrease`	Baixar do estoque	❌ Fazer
GET	`/inventory/low-stock`	Itens abaixo do mínimo	❌ Fazer
GET	`/inventory/by-origin`	Relatório por origem	❌ Fazer

5. Componentes de UI a Criar/Melhorar

5.0 Componentes Novos - Fase 0 ⭐

Componente	Descrição	Prioridade
`PersonForm`	Cadastro unificado de pessoas com seleção de papéis	Máxima
`PersonSearch`	Busca de pessoas por nome/CPF com indicador de papéis	Máxima
`TradeInFlowTracker`	Acompanhamento visual: Avaliação → O.S. → Estoque	Máxima
`InternalServiceOrder`	Formulário de O.S. interna (revisão/manutenção)	Máxima
`DeviceOriginBadge`	Badge indicando origem (Trade-In / Fornecedor)	Alta

5.1 Novos Componentes - Outras Fases

Componente	Descrição	Prioridade
`IMEIHistory`	Timeline de movimentações do IMEI	Alta
`ServiceOrderWorkflow`	Painel visual de status da OS	Alta
`QuoteGenerator`	Formulário de orçamentação	Alta
`POSCart`	Carrinho do PDV funcional	Alta
`PaymentMethods`	Seletor de formas de pagamento	Alta
`ReceiptPreview`	Visualização/impressão de recibos	Média
`LabelPrint`	Impressão de etiquetas	Média
`CustomerPortal`	Página pública de consulta	Média
`NotificationHistory`	Histórico de mensagens enviadas	Baixa

5.2 Melhorias em Componentes Existentes

Componente	Melhoria	Prioridade
`ArcadiaRetail.tsx`	Adicionar carrinho no PDV	Alta
Aba Estoque	Filtrar por origem (Trade-In/Fornecedor)	Alta
Aba Estoque	Separar por tipo (venda/reparo)	Média
Aba Serviços	Workflow visual de status	Alta
Aba Serviços	Diferenciar O.S. Cliente vs O.S. Interna	Alta
Aba Trade-In	Botão "Aprovar e Processar" com fluxo completo	Alta
Dashboard	KPIs específicos do negócio	Média

6. Estimativa de Esforço

Fase	Duração	Complexidade	Dependências
Fase 0 - Pessoas + Trade-In Flow	1-2 semanas	Alta	Nenhuma
Fase 1 - Núcleo (IMEI, OS, Orçamento)	2 semanas	Média	Fase 0
Fase 2 - PDV	2 semanas	Alta	Fase 1
Fase 3 - Automação	2 semanas	Média	Fase 1, WhatsApp
Fase 4 - Estoque Avançado	2 semanas	Média	Fases 1-2

Total Estimado: 8-10 semanas para MVP completo

7. Schema de Dados - Novas Tabelas

7.1 Tabela `persons` (Pessoas Unificadas)

CREATE TABLE persons (
  id SERIAL PRIMARY KEY,
  tenant_id INTEGER REFERENCES tenants(id),
  full_name VARCHAR(255) NOT NULL,
  cpf_cnpj VARCHAR(20) UNIQUE,
  email VARCHAR(255),
  phone VARCHAR(20),
  phone2 VARCHAR(20),
  address TEXT,
  city VARCHAR(100),
  state VARCHAR(2),
  zip_code VARCHAR(10),
  birth_date DATE,
  notes TEXT,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

7.2 Tabela `person_roles` (Papéis da Pessoa)

CREATE TABLE person_roles (
  id SERIAL PRIMARY KEY,
  person_id INTEGER REFERENCES persons(id) NOT NULL,
  role_type VARCHAR(20) NOT NULL, -- customer, supplier, employee, technician, partner
  -- Campos específicos por papel
  credit_limit NUMERIC(12,2), -- para customer
  payment_terms VARCHAR(50), -- para supplier
  employee_code VARCHAR(20), -- para employee
  commission_rate NUMERIC(5,2), -- para employee/technician
  hire_date DATE, -- para employee
  specialization VARCHAR(100), -- para technician
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

7.3 Campos Adicionais em `mobile_devices`

ALTER TABLE mobile_devices ADD COLUMN acquisition_type VARCHAR(20) DEFAULT 'purchase';
-- Valores: trade_in, purchase, consignment, internal_transfer
ALTER TABLE mobile_devices ADD COLUMN acquisition_cost NUMERIC(12,2);
ALTER TABLE mobile_devices ADD COLUMN related_evaluation_id INTEGER REFERENCES device_evaluations(id);
ALTER TABLE mobile_devices ADD COLUMN related_service_order_id INTEGER REFERENCES service_orders(id);
ALTER TABLE mobile_devices ADD COLUMN person_id INTEGER REFERENCES persons(id); -- substituir supplier_id

7.4 Campos Adicionais em `service_orders`

ALTER TABLE service_orders ADD COLUMN is_internal BOOLEAN DEFAULT false;
ALTER TABLE service_orders ADD COLUMN internal_type VARCHAR(30); -- revision, cleaning, maintenance
ALTER TABLE service_orders ADD COLUMN source_evaluation_id INTEGER REFERENCES device_evaluations(id);

7.5 Tabela `imei_history` (Kardex do IMEI)

CREATE TABLE imei_history (
  id SERIAL PRIMARY KEY,
  device_id INTEGER REFERENCES mobile_devices(id) NOT NULL,
  action VARCHAR(50) NOT NULL,
  -- entrada, venda, devolucao, transferencia, reparo_iniciado, reparo_finalizado, trade_in_aprovado
  previous_status VARCHAR(50),
  new_status VARCHAR(50),
  related_order_id INTEGER, -- pode ser OS, venda, transferência
  related_order_type VARCHAR(20), -- service_order, sale, transfer, evaluation
  notes TEXT,
  created_by INTEGER REFERENCES users(id),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

7. Próximos Passos Imediatos

Criar tabela imei_history para rastreamento completo
Implementar API de histórico GET /devices/:imei/history
Melhorar fluxo de status da O.S. com validações
Criar componente de carrinho funcional no PDV
Implementar geração de orçamento automático

8. Integrações Existentes a Utilizar

Sistema	Uso	Status
ERPNext	Sincronizar clientes, produtos, fornecedores	✅ Conectado
WhatsApp (Baileys)	Notificações ao cliente	✅ Disponível
OpenAI	Sugestões inteligentes	✅ Disponível
PostgreSQL	Banco de dados	✅ Em uso

Este documento deve ser atualizado conforme o progresso da implementação.

22 KiB Raw Blame History