Perguntas BDApp — Bloco 2 (49 respostas)

Lacunas técnicas restantes para implementação do BDApp. Bloco 2 complementa as 58 perguntas do Bloco 1 em /respostas.

49 perguntas · 8 blocos Atualizado: 20/05/2026
Bloco 1Bloco 2Bloco 3Bloco 4Bloco 5Bloco 6Bloco 7Bloco 8
1

BLOCO 1 — Aba Clientes

8 perguntas
P1

Colunas exatas da aba Clientes, na ordem real:

Data | Cliente | Email | Telefone | CPF | Endereço | Total gasto | Qtd pedidos
P2

Cabeçalhos literais:

Data | Cliente | Email | Telefone | CPF | Endereço | Total gasto | Qtd pedidos
P3

Campos WooCommerce/banco que alimentam cada coluna:

  • Data = date_created do pedido mais recente daquele cliente
  • Cliente = shipping.first_name + shipping.last_name (fallback: billing)
  • Email = billing.email
  • Telefone = billing.phone
  • CPF = meta_key _billing_cpf (ou _billing_cnpj se não houver CPF)
  • Endereço = billing.address_1 + billing.number + billing.address_2 + billing.city + billing.state + billing.postcode
  • Total gasto = soma de meta totals dos pedidos via Sheets (recalculado por soma de coluna total da aba Pedidos filtrada por email)
  • Qtd pedidos = contagem de pedidos via Sheets (recalculado por contagem de linhas na aba Pedidos filtrada por email)
P4

Recalculo de total_gasto:

Soma da coluna Total (aba Pedidos) filtrada por email do cliente. IGNORA pedidos cancelled e refunded — apenas status que geraram escrita válida.
P5

Recalculo de qtd_pedidos:

Contagem de linhas na aba Pedidos filtrada por email do cliente. IGNORA pedidos cancelled e refunded.
P6

Valor para CNPJ quando existe CNPJ em vez de CPF:

Grava o CNPJ na coluna CPF (sem distinção de tipo). Máscara aplicada: 00.000.000/0000-00.
P7

Cliente já existe — campos atualizados:

  • Sempre atualizados: Email, Telefone, Endereço (sempre que vier preenchido)
  • Sempre recalculados: Total gasto, Qtd pedidos
  • Nunca atualizados: Data (mantém primeiro pedido), Cliente (nome não muda)
P8

Pedidos cancelled/refunded afetam total_gasto e qtd_pedidos:

NÃO. Apenas pedidos que passaram pelo fluxo de escrita válido (processing, completed) são contados.
2

BLOCO 2 — Aba Inventário

7 perguntas
P9

Colunas exatas da aba Inventário, na ordem real:

SKU | Produto | Qtd | Preço original | Preço venda | Status | Pedido | Data da venda | Valor da venda
P10

Cabeçalhos literais:

SKU | Produto | Qtd | Preço original | Preço venda | Status | Pedido | Data da venda | Valor da venda
P11

Preço venda — campo exato do WooCommerce:

line_items[].price (preço unitário da linha, NÃO o line_total)
P12

Quando qtd > 1, o Preço venda gravado é:

Valor unitário (line_items[].price). O sistema grava o preço de uma unidade, não o total da linha.
P13

Formato de Data da venda:

dd/mm/yyyy HH:mm (ex: 20/05/2026 14:32)
P14

Busca de SKU: comparacao exata ou normalizada?

Comparação EXATA por string (SKU WooCommerce = SKU planilha). Sem normalização de espaços, hifens ou case.
P15

SKU duplicado na aba Inventário:

O sistema atualiza a PRIMEIRA linha encontrada (ordem de aparência na planilha). Comportamento não-determinístico para duplicados.
3

BLOCO 3 — Aba Separar

8 perguntas
P16

Coluna Qtd recebe sempre 1 ou a quantidade real?

SEMPRE 1 por linha. Cada linha representa uma unidade a ser separada, independente da quantity do line_item.
P17

Quando quantity > 1, sistema cria:

VÁRIAS linhas separadas, uma por unidade. Cada linha recebe Qtd = 1. (Ex: quantity=3 → 3 linhas na Separar)
P18

Endereço da aba Separar vem de shipping ou billing?

shipping.address_1 + shipping.number (não usa billing para o endereço principal)
P19

Cidade, UF e CEP da Separar — shipping ou billing?

shipping.city, shipping.state, shipping.postcode
P20

Se shipping vier vazio, usa fallback para billing?

SIM. Se shipping.first_name vazio, usa billing como fallback para todo o bloco de endereço/nome.
P21

Colunas adicionais na Separar além das 10 informadas?

Não há colunas adicionais conhecidas além das 10 listadas.
P22

Protecao contra duplicidade na Separar:

SIM. O webhook identifica o pedido por order_id. Ao processar, verifica se o order_id já existe na Separar — se existir, pula sem append.
P23

Chave usada na protecao contra duplicidade na Separar:

order_id (único por pedido). A verificação é: "pedido #1234 já tem linha na Separar?" — se sim, pula.
4

BLOCO 4 — Aba Pedidos

5 perguntas
P24

De onde vem o number quando billing.number não é nativo do WooCommerce?

De billing.address_2 (texto que segue address_1 e contém o número). O sistema concatena address_1 + " " + address_2.
P25

Fallback se billing.number não existir:

Usa billing.address_2 completo como número/endereço. Se ambos vazios, deixa em branco.
P26

Mapa de status para PT-BR:

  • processing → Processando
  • on-hold → Em Espera
  • completed → Concluído
  • cancelled → Cancelado
  • refunded → Reembolsado
  • (qualquer outro status → em branco ou copiado como vier)
P27

Campo Total — componentes exatos:

SOMA de:
  • subtotal dos itens (line_items)
  • custo de frete (shipping_total)
  • desconto aplicado (discount_total)
  • taxas de cartão (fee_total)
NÃO inclui: order_tax, shipping_tax, refunded_total
P28

Quando frete é zero:

Grava R$ 0,00. Não usa — — regra fixa, sempre monetary format.
5

BLOCO 5 — Webhook e Segurança

5 perguntas
P29

Webhook exige token E HMAC juntos, ou apenas um?

Ambiente atual: ambos juntos (?token=... E X-Wc-Webhook-Signature). O token sozinho não basta para produção.
P30

Quando HMAC é tratado como opcional:

Em ambiente de desenvolvimento/teste, quando o header X-Wc-Webhook-Signature está ausente E o IP é localhost/127.0.0.1.
P31

Resposta HTTP de sucesso esperada pelo WooCommerce:

HTTP 200 com corpo ok ou JSON { received: true }. Qualquer outro código ou timeout = WooCommerce reenvia.
P32

O sistema responde ao WooCommerce antes ou depois de DB + Sheets?

DEPOIS. Responde apenas após completar todas as operações (DB write + Google Sheets upsert). Resposta HTTP só enviada quando tudo está commitado.
P33

Existe fila/assincronia no processamento?

NÃO. Tudo acontece na mesma requisição HTTP síncrona. Se o processamento demorar, o WooCommerce entra em timeout e reenvia.
6

BLOCO 6 — Reprocessamento e Logs

5 perguntas
P34

Endpoint específico para reprocessar order_id único:

SIM. GET /api/analytics/backfill?order_id=XXX — o mesmo endpoint aceita order_id único ou range.
P35

Rota exata e parâmetros:

GET /api/analytics/backfill
  • order_id=N (único)
  • from=YYYY-MM-DD&to=YYYY-MM-DD (range de datas)
  • Nenhum parâmetro = backfill completo
P36

Como o sistema impede duplicação na Separar durante reprocessamento:

Antes de appendar na Separar, o sistema DELETA todas as linhas existentes com aquele order_id, depois reinsere. Funciona como upsert de fato.
P37

Pedido com falha de sync — marcação técnica no banco?

SIM. Tabela order_analytics tem coluna last_sync_status (varchar) que grava success, failed_sheets, failed_db ou similar após cada tentativa.
P38

Logs guardam payload bruto ou apenas metadados?

Logs de execução guardam metadados: timestamp, order_id, etapas atingidas, tempo de cada etapa. Payload bruto do webhook NÃO é armazenado em produção (evita PII em logs).
7

BLOCO 7 — Infra e Configuração

4 perguntas
P39

Aba Config existe?

NÃO. A integração atual NÃO tem aba Config. Toda configuração é via variáveis de ambiente do servidor.
P40

Configs guardadas (não em aba, mas em env):

  • GOOGLE_SERVICE_ACCOUNT_JSON (credencial completa JSON)
  • WOOCOMMERCE_CONSUMER_KEY / WOOCOMMERCE_CONSUMER_SECRET
  • SPREADSHEET_ID
  • WEBHOOK_SECRET_TOKEN
  • WooCommerce store URL
P41

Nome exato do spreadsheet importa no código?

NÃO. O código usa apenas spreadsheetId. O nome visual da planilha é irrelevante para a automação.
P42

Apenas uma planilha usada?

SIM. Uma única planilha Google Sheets com 4 abas: Pedidos, Clientes, Inventário, Separar. Não há planilha secundária.
8

BLOCO 8 — Integrações Residuais

7 perguntas
P43

Email de notificação dispara em quais status:

Status: processing (pedido pago) E completed (enviado). Dois emails distintos:
  • processing = "🛒 Novo pedido #X - R$Y" (aviso de pagamento)
  • completed = "📦 Pedido #X enviado" (rastreio)
P44

Email: remetente e destinatário:

  • Remetente: bancadasantigas@gmail.com (via Gmail API)
  • Destinatário: bancadasantigas@gmail.com (mesmo endereço — notificação interna)
P45

Feed Pinterest consome dados de onde:

Tabela pinterest_catalog no banco PostgreSQL. NÃO lê direto do WooCommerce nem da planilha Sheets.
P46

Processo que popula pinterest_catalog:

Pipeline de classificação: SKU do WooCommerce → pinterest_catalog. Classificação baseada em tags (adult, nude, explicit vs vintage, collector, hq, capa). Popula automaticamente a cada novo produto ou ajuste de tag.
P47

Classificação safe/explicit:

AUTOMÁTICA. Baseada em tags do produto no WooCommerce. Híbrida: tags pré-definidas disparam classificação automática; review manual para borderline cases.
P48

Feed Pinterest é crítico para o core ou apenas marketing?

APENAS marketing/canal. Não impacta operação operacional diária. Pode ser implementado depois do BDApp core sem risco.
P49

Automação de alt text — depende de alguma tabela/config não documentada:

SIM. A automação de alt text (batch API via WooCommerce REST v3) usa a tabela products como fonte de verdade. Não depende de tabela Config — usa endpoint direto da API REST do WooCommerce. Dependência: produtos precisam ter image.src populado. Não há tabela BancaOS específica além da products.

BancaOS — Bloco 2 BDApp · 49 respostas documentadas

Gerado automaticamente em 20/05/2026