ofrangao-ops/docs/arquitectura-dados.md

# 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 |

**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` | |
| H | PIX LOJA | `total_pixcnpj` | |
| I | PRAZO | `total_areceber` | |
| J | PZREC | `saldo_areceber` | |
| K | CRÉDITO | `total_cartao_credito` | |
| L | DÉBITO | `total_cartao_debito` | |
| M | VOUCHER | `total_cartao_pix` | |
| 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)
    ↓ SyncThing
VPS (ficheiros)
    ↓ N8N (conversão)
Supabase → Google Sheets (VENDAS)
                        ↓
                  Sheet (Exportação)
                        ↓
                  CSV/Excel
                        ↓
                  Meu Dinheiro (app)
```

### Fluxo Futuro (objectivo)

```
PDV Web (novo sistema)
    ↓
Supabase
    ↓                    ← N8N (quando disponível)
Google Sheets (opcional) → Exportação → Meu Dinheiro
    ↓
App Fechamento Caixa (Tauri)
```

---

## 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

- [x] **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
  - PostgREST (supabase-rest): `172.16.6.7` — ⚠️ MUDANÇA FREQUENTE
  - Kong: `172.16.6.7` (mesmo host, porta 8000)
  - DB: `172.16.6.4`
  - Auth: `172.16.6.8`
  - 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
  - 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 |