commit 9d2277ba8c7fe5b4e444782c21ccf681537c51b9 Author: Hermes Agent Date: Fri Jul 10 13:12:10 2026 +0000 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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..3aae492 --- /dev/null +++ b/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) diff --git a/docs/arquitectura-dados.md b/docs/arquitectura-dados.md new file mode 100644 index 0000000..80d43ef --- /dev/null +++ b/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*