filipe/ofrangao-ops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7ffea14891d526ceedb94dbc751e1b6a42c96661
ofrangao-ops/docs/arquitectura-dados.md
T

10 KiB
Raw Blame History

Arquitectura de Dados — O Frangão

Estado: em construção — 2026-07-10 Responsável: Filipe + Hermes Agent

1. Visão Geral

Dois sistemas a funcionar em paralelo durante a transição:

  • Sistema antigo: SyncThing → N8N → Supabase → Google Sheets → Exportação → Meu Dinheiro
  • Sistema novo (futuro): PDV Web → Supabase → (opcional) Google Sheets

Regra: manter ambos alimentados para não haver perda de dados.

2. Stack Tecnológica

Componente Tecnologia Notas
Base de dados Supabase (self-hosted) VPS Hostinger
Automação N8N self-hosted
Ficheiros PDV SyncThing PC loja → VPS
Sheet de entrada Google Sheets (VENDAS) ~25k linhas desde 2021
Gestão financeira Meu Dinheiro (app) Importação via CSV/Excel
Versionamento Gitea (git.ofrangao.com.br) Repos: fechamento-caixa, vault

3. Base de Dados — Supabase

Tabela fechamentos_web

Tabela principal de fechamentos de caixa.

Coluna Tipo Descrição
id uuid PK
id_fechamento varchar(100) ID único (ex: alianca_2026-07-08_sophia)
data date Data do fechamento
loja varchar(20) alianca ou uniao
turno varchar(20) manha / tarde / integral
operador varchar(100) Nome de quem fechou
saldo_troco numeric(12,2) Valor em troco
saldo_credito numeric(12,2) Cartão crédito
saldo_debito numeric(12,2) Cartão débito
saldo_alimentacao numeric(12,2) Ticket alimentação
saldo_vales numeric(12,2) Vales
saldo_areceber numeric(12,2) A receber
saldo_pixcnpj numeric(12,2) PIX
fechamento_dinheiro numeric(12,2) Dinheiro contado
fechamento_cartoes numeric(12,2) Cartões contados
fechamento_areceber numeric(12,2) A receber contado
total_sangrias numeric(12,2) Sangrias
total_despesas numeric(12,2) Despesas
total_cancelamentos numeric(12,2) Cancelamentos
total_vales numeric(12,2) Vales
total_pixcnpj numeric(12,2) PIX
total_areceber numeric(12,2) A receber
total_cartao_credito numeric(12,2) Crédito
total_cartao_debito numeric(12,2) Débito
total_cartao_alimentacao numeric(12,2) Alimentação
total_cartao_pix numeric(12,2) PIX cartão
saldo_esperado numeric(12,2) Total esperado
diferenca numeric(12,2) Diferença vs contado
status_diferenca varchar(20) ok ou divergente
dados jsonb Detalhe por transação
clientes integer Nº clientes
frango integer Nº frangos
vendas numeric Total vendas (do PDV)
criado_em timestamptz Data criação
enviado_por varchar(100) Origem do registo
ip_origem inet IP de origem
user_agent text Browser/cliente
observacoes text Notas
atualizado_em timestamptz Data última alteração

Constraints:

  • UNIQUE (loja, data, turno, operador)
  • loja IN ('alianca', 'uniao')
  • turno IN ('manha', 'tarde', 'integral')

Tabela fechamento_web_log

Log de alterações — audit trail.

Coluna Tipo
id bigint
fechamento_id uuid → fechamentos_web.id
acao varchar(20)
dados jsonb
criado_em timestamptz

Tabela pdv_fechamento

Dados exportados do sistema PDV (legado).

Coluna Tipo Descrição
id bigint PK
data date Data
operador varchar(5) Operador
turno numeric Turno
pdv varchar(4) Número PDV
especie numeric(10,2) Dinheiro
cartao numeric(10,2) Cartão
aprazo numeric(10,2) A prazo
vale numeric(10,2) Vale
empresa varchar(10) Empresa
loja varchar(10) alianca ou uniao
fechado boolean Se está fechado

Nota: fechamentos_web.pdv_fechamento_id referencia pdv_fechamento.id

4. Google Sheets

Sheet "VENDAS"

URL: https://docs.google.com/spreadsheets/d/1OJZzDRTaU9Zh49QsgzAqNMxkn_7X7p7u_BiBBfStW3k/

Abas:

  • VENDAS — principal entrada de dados
  • VALES
  • Exportação — tratamento para importar no Meu Dinheiro
  • Resumo — resumo para balanço
  • Din_Vendas
  • Caixas Dias Trab
  • RESUMO DESPESAS
  • Desp
  • Tab Aux
  • Dias de Trablho Caixa
  • Despesas
  • Resultado

Colunas da aba VENDAS (26 colunas):

# Header Mapeamento Supabase Notas
A DATA data Formato DD/MM/AAAA
B EMPRESA loja Aliança/Central/Minas/União
C SANGRIAS total_sangrias
D DESPESAS total_despesas
E VALES total_vales
F DINHEIRO fechamento_dinheiro
G PIX TAV total_pixcnpj PIX taxado (cobrado ao cliente)
H PIX LOJA saldo_pixcnpj PIX do cliente na loja
I PRAZO total_areceber
J PZREC saldo_areceber Valor a receber contado
K CRÉDITO total_cartao_credito
L DÉBITO total_cartao_debito
M VOUCHER total_cartao_alimentacao Ticket alimentação
N CARTÃO fechamento_cartoes
O T. VENDA vendas =SOMA(K7705:M7705) — total de vendas
P TX CARTÃO calculado =SOMA(SEERRO(VENDAS!K*1,95%;0);SEERRO(VENDAS!L*1,2%;0);SEERRO(VENDAS!M*6%;0))
Q CLIENTES clientes
R Cancelamentos total_cancelamentos
S Sistema pdv_fechamento Valor do PDV — referência
T Diferença diferenca
U Caixa operador Operador de caixa
V PG — Descartar
W Ano — Descartar
X Mês — Descartar
Y DiaSem — Descartar
Z CredPix — Descartar

Dados históricos:

  • 25.000+ linhas (01/01/2021 — 31/12/2025)
  • Lojas activas: Aliança, União
  • Lojas fechadas: Central, Minas

5. Fluxos de Dados

Fluxo Actual (funciona)

PC PDV (ficheiros DBF)
    ↓ SyncThing
VPS (ficheiros)
    ↓ N8N ("PDV Sync - Syncthing para Supabase")
Supabase (tabela pdv_fechamento)
    ↓ N8N ("PDV → Google Sheets Sync")
Google Sheets (VENDAS)
    ↓
Sheet (Exportação) → CSV/Excel → Meu Dinheiro (app)

Fluxo App Fechamento Caixa → Sheet VENDAS (2026-07-10)

App Fechamento Caixa (Tauri)
    ↓ POST / rest/v1/fechamentos_web
Supabase (tabela fechamentos_web)
    ↓ N8N Workflow "Supabase → Sheet VENDAS" (20h BRT)
Google Sheets (VENDAS) ← última linha: 7729 (01/07/2026)
    ↓
Sheet (Exportação) → Meu Dinheiro

Nota: Os dois fluxos são independentes. O N8N do PDV não escreve na mesma Sheet que o App Fechamento Caixa — o App escreve em linha nova a partir da 7730.

6. Tarefas em Aberto

Alta Prioridade

  • Importar histórico Sheet → Supabase (~25k linhas, 2021-2025)

    • Criar tabela vendas_diarias para dados agregados
    • Mapear colunas Sheet → Supabase
    • Limpar dados de lojas fechadas (Central, Minas)
    • Executar importação via script Python

  • Criar fluxo N8N: Supabase → Sheet VENDAS ✅ (2026-07-10)

    • Workflow ID: 34cfbba7-b58a-4ba9-ac98-9c7755260722
    • Trigger: schedule 0 20 * * * (20h BRT)
    • Nodes: Read Last Sync → Fetch Supabase → Filter+Map → Append VENDAS → Update Last Sync
    • Credenciais: SUPABASE_SHEETS_READER_KEY env var + Google Sheets OAuth
    • Sheet "Sincronizacao" A1: guarda UTC timestamp do último sync
    • ⚠️ Primeiro run: cells vazias na Sheet VENDAS (fórmulas T.VENDA, TX_CAIXA, SISTEMA ficam a 0)
    • ⚠️ Necessário criar aba Sincronizacao no spreadsheet com A1 vazio antes de activar

Média Prioridade

  • Adicionar coluna tx_cartao calculada ao Supabase

    • Fórmula: total_cartao_credito * 1.95% + total_cartao_debito * 1.2% + total_cartao_pix * 6%

  • Validar Sistema (PDV) vs vendas — confirmar que girls estão a usar valor correcto

  • Migrar fechamento_web_log para não bloquear DELETE

Baixa Prioridade

  • Avaliar alternativa ao Meu Dinheiro (Falcon Finanças, etc.)
  • Criar dashboard no Supabase para visualização directa

7. Notas Técnicas

Supabase (self-hosted)

  • Container IPs: podem mudar após docker update da Hostinger

    • ⚠️ IPs listados abaixo podem estar desactualizados — o cron Kong DNS fix mantém o kong.yml actualizado
    • PostgREST (supabase-rest): ver cron Kong DNS fix
    • Kong: supabase-kong (mesmo host, porta 8000)
    • DB: 172.16.6.4
    • Auth: ver cron
    • Meta: 172.16.6.9
    • Pooler: 172.16.6.10

  • Problema conhecido: IPs hardcoded no kong.yml — corrigido automaticamente

    • Cron Kong DNS fix (job ID: 9a64e7b49ac6) corre a cada 15 min
    • Usa DNS names (http://supabase-rest:3000/) em vez de IPs hardcoded
    • Compara IP actual do supabase-rest com o em kong.yml
    • Se diferente: substitui e reinicia supabase-kong

Google Sheets API

  • Service account: n8n-integracao@n8n-automacao-filipetavares.iam.gserviceaccount.com
  • Credenciais: /var/lib/docker/volumes/hermes-workspace-k9hd_hermes-agent-data/_data/google_service_account.json
  • Rate limit: 60 reads/minuto — evitar loops de polling

Gitea

  • URL: https://git.ofrangao.com.br
  • Token: (guardado em credentials-n8n-real.env)
  • Repos: filipe/fechamento-caixa, filipe/vault, filipe/ofrangao-ops
  • Atenção: token de git push NÃO funciona na API — usar token dedicado

8. Glossary

Termo Significado
PDV Ponto de Venda — sistema de caixa
Sangria Retirada de dinheiro do caixa
Troco Diferença entregue ao cliente
Prazo / A prazo Venda a pagar depois
Espécie Dinheiro físico
TX Cartão Taxa de cartão (1.95% crédito, 1.2% débito, 6% voucher)
PIX CNPJ PIX feito pela loja
PDV Web Nova versão do sistema PDV (em desenvolvimento)
SyncThing Software de sincronização de ficheiros P2P

Última actualização: 2026-07-10

9. N8N Workflows

Workflow ID Trigger Notas
PDV → Sheets Relatorios VFIiOZK2ZV3a0956 0 */6 * * * Fetch PDV, clear+append Resumo_Diario, Top_Produtos, Resumo_Fechamento
Supabase → Sheet VENDAS 34cfbba7-b58a-4ba9-ac98-9c7755260722 0 20 * * * Incremental por atualizado_em UTC. ⚠️ Requer aba Sincronizacao no spreadsheet

10. Cron Jobs (Hermes Agent)

Job ID Schedule Notas
Kong DNS fix 9a64e7b49ac6 */15 * * * * Auto-fix PostgREST IP no kong.yml
Reference in New Issue View Git Blame Copy Permalink