# 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)
- [x] **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()`
- [x] **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
- [x] **INF-04** Criar estrutura de pastas do novo módulo dentro de `sistema-nuvem/` — models, controllers e routes criados
- [x] **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
- [x] **INF-06** Definir autenticação: JWT separado ou reutilizar `signTeamToken` — reutiliza `verifyUserToken` (cliente) e `verifyToken` (admin)

---

### FASE 2 — Cadastro de Clientes (PF e PJ)

- [x] **CAD-01** Criar tabela `clientes` com campos: tipo (PF/PJ), nome/razão social, CPF/CNPJ, e-mail, status
- [x] **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
- [x] **CAD-03** Criar tabela `telefones` com campos: tipo (comercial/celular/WhatsApp/financeiro/compras), número, ramal, aceita_whatsapp, principal
- [x] **CAD-04** Criar tabela `responsaveis` com campos: nome, cargo, setor, telefone_id, e-mail, permissão (compras/financeiro/recebimento)
- [x] **CAD-05** Implementar regras: PJ permite múltiplos responsáveis; PF normalmente 1
- [x] **CAD-06** Implementar endereço padrão automático no checkout
- [x] **CAD-07** Implementar histórico de alterações de cadastro
- [x] **CAD-08** Criar API REST: CRUD de clientes, endereços, telefones e responsáveis
- [x] **CAD-09** Criar tela frontend: formulário de cadastro com abas (Dados Gerais / Endereços / Telefones / Responsáveis)
- [x] **CAD-10** Validação de CPF e CNPJ no frontend e backend
- [x] **CAD-11** Consulta automática de CEP via ViaCEP para preenchimento de endereço

---

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

- [x] **PRD-01** Criar tabela `produtos` com campos: SKU, nome, descrição, unidade, preço, estoque, categoria, ativo
- [x] **PRD-02** Implementar importação via arquivo CSV/XLS
- [x] **PRD-03** Implementar sincronização com sistema local do Alemão (via API ou arquivo exportado)
- [x] **PRD-04** Criar endpoint para atualização de estoque
- [x] **PRD-05** Criar endpoint para atualização de preços
- [x] **PRD-06** Criar tela: Tela 2 — Importação de Produtos (CSV/XLS, sincronizar, atualizar estoque, atualizar preços)
- [x] **PRD-07** Busca de produtos por nome, SKU e categoria no frontend
- [x] **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.

- [x] **PROMO-01** Adicionar coluna `produto_id` (FK para `produtos`) na tabela `promotions` para vincular promoção a produto do catálogo
- [x] **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`)
- [x] **PROMO-03** Ao adicionar produto ao carrinho, aplicar automaticamente `preco_promocional` se houver promoção ativa — exibir preço original riscado
- [x] **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)
- [x] **PROMO-05** Implementar desconto por volume para PJ no carrinho (lógica similar a `RaffleDiscount.getBestForQty` — ex: comprou 10 caixas → 5% off)
- [x] **PROMO-06** Na tela de cotação e resumo do pedido, exibir breakdown de descontos: promoção aplicada + desconto por volume + total final
- [x] **PROMO-07** Criar endpoint `GET /api/promotions/active-summary` para o Cérebro do WhatsApp consultar promoções do dia ao responder clientes
- [x] **PROMO-08** No admin (`Promotions.tsx`), adicionar campo de busca/vínculo por SKU ou `produto_id` ao criar/editar promoção
- [x] **PROMO-09** No Dashboard Geral, adicionar card "Promoções Ativas" com contagem e link para gerenciamento
- [x] **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)

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

---

### FASE 5 — Painel Interno / Dashboard

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

---

### FASE 6 — Fluxo Operacional Interno

#### 6.1 Fila de Separação

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

#### 6.2 Embalagem / Coleta Interna

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

#### 6.3 Auditoria Final

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

#### 6.4 Fiscal

- [x] **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)
- [x] **FIS-03** Preencher dados fiscais automaticamente a partir do cadastro do cliente

#### 6.5 Expedição

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

---

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

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

---

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

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

- [x] **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
- [x] **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
- [x] **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
- [x] **FUT-04** Ranking de produtividade das equipes (separação, embalagem, auditoria)
- [x] **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
