ruicesar/mercado.clube67.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mercado.clube67.com/docs/cotacao-online.md
T

12 KiB
Raw Permalink Blame History

Sistema de Cotação Online — Plano de Execução

Projeto: alemaoconveniencias.local
Data: 2026-04-22
Status: ✅ Concluído (FIS-02 pendente de ManualNFSeWebService.md · INF-01 decisão externa)

Objetivo

Criar uma plataforma online para solicitar, comparar e gerenciar cotações, integrando clientes PF e PJ ao fluxo operacional interno (separação, embalagem, auditoria, fiscal, expedição) com suporte à IA no WhatsApp.

Fases e Tarefas

FASE 1 — Fundação e Infraestrutura

  • INF-01 Definir domínio/subdomínio do sistema de cotação (ex: cotacao.alemaoconveniencias.com.br)
  • INF-02 Criar banco de dados separado ou novo schema no PostgreSQL existente para o módulo de cotação — migrations em database.js:initialize()
  • INF-03 Mapear tenant_id do alemão no sistema atual para isolamento correto — todas as tabelas novas têm tenant_id com fallback 1
  • INF-04 Criar estrutura de pastas do novo módulo dentro de sistema-nuvem/ — models, controllers e routes criados
  • INF-05 Configurar variáveis de ambiente (.env) para o módulo de cotação — sem novas vars necessárias; reutiliza JWT_SECRET/USER_SECRET
  • INF-06 Definir autenticação: JWT separado ou reutilizar signTeamToken — reutiliza verifyUserToken (cliente) e verifyToken (admin)

FASE 2 — Cadastro de Clientes (PF e PJ)

  • CAD-01 Criar tabela clientes com campos: tipo (PF/PJ), nome/razão social, CPF/CNPJ, e-mail, status
  • CAD-02 Criar tabela enderecos com campos: tipo (entrega/cobrança/retirada/matriz/filial), CEP, rua, número, complemento, bairro, cidade, estado, referência, principal
  • CAD-03 Criar tabela telefones com campos: tipo (comercial/celular/WhatsApp/financeiro/compras), número, ramal, aceita_whatsapp, principal
  • CAD-04 Criar tabela responsaveis com campos: nome, cargo, setor, telefone_id, e-mail, permissão (compras/financeiro/recebimento)
  • CAD-05 Implementar regras: PJ permite múltiplos responsáveis; PF normalmente 1
  • CAD-06 Implementar endereço padrão automático no checkout
  • CAD-07 Implementar histórico de alterações de cadastro
  • CAD-08 Criar API REST: CRUD de clientes, endereços, telefones e responsáveis
  • CAD-09 Criar tela frontend: formulário de cadastro com abas (Dados Gerais / Endereços / Telefones / Responsáveis)
  • CAD-10 Validação de CPF e CNPJ no frontend e backend
  • CAD-11 Consulta automática de CEP via ViaCEP para preenchimento de endereço

FASE 3 — Catálogo de Produtos e Importação

  • PRD-01 Criar tabela produtos com campos: SKU, nome, descrição, unidade, preço, estoque, categoria, ativo
  • PRD-02 Implementar importação via arquivo CSV/XLS
  • PRD-03 Implementar sincronização com sistema local do Alemão (via API ou arquivo exportado)
  • PRD-04 Criar endpoint para atualização de estoque
  • PRD-05 Criar endpoint para atualização de preços
  • PRD-06 Criar tela: Tela 2 — Importação de Produtos (CSV/XLS, sincronizar, atualizar estoque, atualizar preços)
  • PRD-07 Busca de produtos por nome, SKU e categoria no frontend
  • PRD-08 Exibir disponibilidade de estoque em tempo real na área do cliente

FASE 3B — Integração com o Sistema de Promoções Existente

O sistema já possui tabela promotions, model Promotion.js, controller promotionsController.js, rotas /api/promotions e frontend em admin-app/src/pages/Promotions.tsx e customer-app/src/pages/LandingPage.tsx. As tarefas abaixo ligam o módulo de cotação a essa infraestrutura sem reescrever nada.

  • PROMO-01 Adicionar coluna produto_id (FK para produtos) na tabela promotions para vincular promoção a produto do catálogo
  • PROMO-02 No catálogo da área do cliente, exibir badge "Em Promoção" e preco_promocional quando produto tiver promoção ativa (GET /api/promotions)
  • PROMO-03 Ao adicionar produto ao carrinho, aplicar automaticamente preco_promocional se houver promoção ativa — exibir preço original riscado
  • PROMO-04 Ativar seção "Ofertas do Dia" na landing page da área do cliente (componente já existe em customer-app/src/pages/LandingPage.tsx — apenas conectar ao endpoint real)
  • PROMO-05 Implementar desconto por volume para PJ no carrinho (lógica similar a RaffleDiscount.getBestForQty — ex: comprou 10 caixas → 5% off)
  • PROMO-06 Na tela de cotação e resumo do pedido, exibir breakdown de descontos: promoção aplicada + desconto por volume + total final
  • PROMO-07 Criar endpoint GET /api/promotions/active-summary para o Cérebro do WhatsApp consultar promoções do dia ao responder clientes
  • PROMO-08 No admin (Promotions.tsx), adicionar campo de busca/vínculo por SKU ou produto_id ao criar/editar promoção
  • PROMO-09 No Dashboard Geral, adicionar card "Promoções Ativas" com contagem e link para gerenciamento
  • PROMO-10 Implementar promoção relâmpago no checkout da cotação com countdown (reutilizar modelo raffle_flash_promos e lógica de RaffleFlashPromo.getActive)

FASE 4 — Área do Cliente (Carrinho e Cotação)

  • CLI-01 Criar fluxo de login/registro do cliente (PF com CPF / PJ com CNPJ)
  • CLI-02 Criar tela de busca de produtos com filtros
  • CLI-03 Implementar carrinho de compras (sessão ou banco de dados)
  • CLI-04 Implementar função "Salvar Cotação" (gera cotação sem finalizar compra)
  • CLI-05 Implementar função "Finalizar Compra" com seleção de forma de pagamento: PIX / Cartão / Faturado PJ
  • CLI-06 Integrar gateway de pagamento para PIX e cartão (Asaas — após correção BUG-06/07 com HMAC)
  • CLI-07 Implementar opção de retirada ou entrega no checkout
  • CLI-08 Exibir cotações salvas e histórico de pedidos do cliente
  • CLI-09 Implementar recompra rápida a partir de pedido anterior (PJ)
  • CLI-10 Criar tela: Tela 3 — Área do Cliente (buscar, carrinho, salvar cotação, finalizar)

FASE 5 — Painel Interno / Dashboard

  • DASH-01 Criar tela: Tela 1 — Dashboard Geral (pedidos hoje, em separação, em auditoria, prontos, mensagens WhatsApp)
  • DASH-02 Criar contadores em tempo real via WebSocket ou polling
  • DASH-03 Filtro por data, setor e equipe no dashboard
  • DASH-04 Criar notificações internas para novos pedidos e cotações

FASE 6 — Fluxo Operacional Interno

6.1 Fila de Separação

  • SEP-01 Criar tabela pedidos com status: cotação → aguardando → separação → embalagem → auditoria → fiscal → expedição → entregue
  • SEP-02 Criar tela: Tela 4 — Fila de Separação por Equipe (itens por equipe A, B, etc.)
  • SEP-03 Permitir atribuição de pedido a equipe específica
  • SEP-04 Marcar itens como separados por produto

6.2 Embalagem / Coleta Interna

  • EMB-01 Criar tela: Tela 5 — Embalagem (checklist: separados / embalado / lacrado / enviado auditoria)
  • EMB-02 Registro de quem realizou a embalagem e timestamp

6.3 Auditoria Final

  • AUD-01 Criar tela: Tela 6 — Auditoria (conferência de código de barras, quantidades, validade)
  • AUD-02 Botões: Aprovar / Reprovar com campo de motivo
  • AUD-03 Ao reprovar, devolver pedido para separação com alerta à equipe

6.4 Fiscal

  • FIS-01 Criar tela: Tela 7 — Fiscal (gerar cupom fiscal / emitir NF-e com CPF/CNPJ do cliente)
  • FIS-02 Integrar com módulo de NFS-e existente (ver ManualNFSeWebService.md)
  • FIS-03 Preencher dados fiscais automaticamente a partir do cadastro do cliente

6.5 Expedição

  • EXP-01 Criar tela: Tela 8 — Expedição (aguardando retirada, enviar motoboy, rota de entrega, pedido entregue)
  • EXP-02 Registrar responsável pela entrega e horário
  • EXP-03 Enviar notificação ao cliente quando pedido sair para entrega

FASE 7 — Comunicação Interna (Inbox por Setor)

  • INB-01 Criar inbox interno por setor (atendimento, cotação, separação, financeiro, suporte)
  • INB-02 Permitir troca de mensagens entre setores vinculadas ao pedido
  • INB-03 Notificações de nova mensagem no inbox do setor responsável

FASE 8 — Cérebro do WhatsApp / Secretária Virtual

  • WPP-01 Conectar núcleo de IA ao CRM WhatsApp (motor NewWhats em http://127.0.0.1:8008)
  • WPP-02 Implementar identificação automática de PF vs PJ pelo contato
  • WPP-03 Implementar reconhecimento de setor correto (vendas, cotação, entrega, financeiro, suporte)
  • WPP-04 Conectar IA à base de produtos, preços e estoque para responder automaticamente
  • WPP-05 Implementar sugestão de carrinho rápido com link de pagamento via WhatsApp
  • WPP-06 Implementar coleta automática de endereço, telefone e responsável via conversa
  • WPP-07 Implementar transferência para atendente humano com resumo de contexto
  • WPP-08 Implementar envio de atualizações de status do pedido ao WhatsApp do responsável correto
  • WPP-09 Implementar reativação de clientes parados com follow-up automático
  • WPP-10 Criar protocolos automáticos por setor (número de protocolo por atendimento)

Fluxo do Cérebro:

Mensagem recebida
-> identificar cliente (PF/PJ, histórico)
-> entender intenção (compra, cotação, entrega, financeiro, suporte)
-> consultar base interna (produtos, estoque, pedidos)
-> responder automaticamente
-> abrir protocolo/tarefa
-> transferir setor humano se necessário

FASE 9 — Módulos Estratégicos Futuros

  • FUT-01 App separador com leitor de código de barras (mobile PWA) — SeparadorPage.tsx em /cotacao/separador, BarcodeDetector nativo + fallback manual, scan por SKU, feedback sonoro/háptico
  • FUT-02 Recompra automática PJ (pedido recorrente agendado) — tabela pedidos_recorrentes, PedidoRecorrente.js, job diário, rotas /api/recorrentes, UI na aba "Pedidos" do DashboardPage
  • FUT-03 Clube de benefícios integrado ao módulo existente — badge "Benefício de Sócio" na aba Pedidos para membros ativos, prioridade de atendimento registrada nas cotações
  • FUT-04 Ranking de produtividade das equipes (separação, embalagem, auditoria)
  • FUT-05 Relatório de performance por setor e período

Dependências Críticas (resolver antes de iniciar)

# Bug Impacto Prioridade
BUG-06/07 Webhooks Asaas sem HMAC Pagamentos vulneráveis a fraude CRÍTICO
BUG-10 signTeamToken com ReferenceError Login de equipe quebrado CRÍTICO
BUG-13 Notificações de compra nunca enviadas Cliente não recebe confirmação ALTO
BUG-30 Endpoint público expõe CPFs Violação LGPD CRÍTICO

Estes bugs estão documentados em TAREFAS.md. Resolver BUG-06/07 e BUG-30 antes de ativar pagamentos e cadastro público.

Arquitetura Técnica

Frontend (admin-v2)          Frontend (customer-app)
        |                            |
        +---------> API Node.js/Express <--------+
                          |
              +-----------+-----------+
              |           |           |
         PostgreSQL     Redis       NewWhats
         (dados)      (BullMQ)    (WhatsApp)
                                      |
                                   IA/LLM
  • Backend: Node.js + Express (padrão do sistema atual)
  • Banco: PostgreSQL com tenant_id do Alemão
  • Filas: BullMQ/Redis para notificações e tarefas assíncronas
  • WhatsApp: Motor NewWhats em http://127.0.0.1:8008
  • Pagamentos: Asaas (após correção de HMAC)
  • NF-e: Integração via ManualNFSeWebService

Ordem Recomendada de Execução

  1. Resolver bugs críticos (BUG-06, BUG-07, BUG-10, BUG-30)
  2. FASE 1 — Infraestrutura
  3. FASE 2 — Cadastro de Clientes
  4. FASE 3 — Catálogo e Importação
  5. FASE 4 — Área do Cliente (Carrinho/Cotação)
  6. FASE 5 — Dashboard
  7. FASE 6 — Fluxo Operacional (Separação → Expedição)
  8. FASE 7 — Inbox Interno
  9. FASE 8 — Cérebro WhatsApp
  10. FASE 9 — Módulos Futuros

Total de tarefas: 84
Tarefas críticas pré-requisito: 4 (bugs existentes)
Integração promoções (FASE 3B): 10 tarefas — reutiliza infra existente, sem reescrita

Reference in New Issue View Git Blame Copy Permalink