docs: arquitectura inicial O Frangão

- Stack tecnológica
- Tabelas Supabase (fechamentos_web, pdv_fechamento)
- Google Sheets VENDAS — mapeamento de colunas
- Fluxos de dados (actual e futuro)
- Tarefas em aberto
- Notas técnicas

README.md

@@ -0,0 +1,25 @@
+# O Frangão — Documentação de Arquitectura e Operações
+
+> Estado: em construção — 2026-07-10
+
+Repositório de documentação técnica do ecossistema O Frangão / O Novilhão.
+
+## Índice
+
+- [Arquitectura de Dados](./docs/arquitectura-dados.md) — estado actual, fluxos, stack
+- [Tarefas](./docs/tarefas.md) — backlog de desenvolvimento
+
+## Repositórios Relacionados
+
+| Repo | Descrição |
+|---|---|
+| `filipe/fechamento-caixa` | App Tauri de Fechamento de Caixa |
+| `filipe/vault` | Notas e documentação dispersa |
+| `filipe/ofrangao-ops` | Este repositório |
+
+## Stack
+
+- **Base de dados**: Supabase (self-hosted, VPS Hostinger)
+- **Automação**: N8N (self-hosted)
+- **Gestão financeira**: Meu Dinheiro (app)
+- **Versionamento**: Gitea (git.ofrangao.com.br)

docs/arquitectura-dados.md

@@ -0,0 +1,284 @@
+# 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
+
+- [ ] **Criar fluxo N8N: Supabase → Sheet**
+  - Configurar Google Sheets node no N8N
+  - Query: `SELECT * FROM fechamentos_web ORDER BY data DESC`
+  - Agendar: daily às 20h
+  - Destino: aba "VENDAS" (append ou update)
+
+### 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):
+  - Kong: `172.16.6.7`
+  - DB: `172.16.6.4`
+  - Studio: `172.16.6.3`
+  - Auth: `172.16.6.8`
+
+- **Problema conhecido**: IPs hardcoded no `kong.yml` — actualizar com `sed` quando mudam
+
+### 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*