Decisoes Tecnicas

Este documento registra decisoes tecnicas importantes do Romeo, com contexto e justificativa. Serve como referencia para entender por que certas escolhas foram feitas.

Formato

Cada decisao segue: Problema → Opcoes consideradas → Decisao → Consequencias.

Problema

Como representar periodos de temporada (alta, baixa, feriados) no banco de dados, permitindo consultas eficientes de disponibilidade e tarifacao?

Opcoes consideradas

Decisao

Usar DATERANGE nativo do Postgres com constraint EXCLUDE USING GISTpara garantir nao-overlap no nivel do banco.

CREATE TABLE temporadas (
  id UUID PRIMARY KEY,
  imovel_id UUID REFERENCES imoveis(id),
  periodo DATERANGE NOT NULL,
  tipo TEXT NOT NULL, -- 'alta', 'baixa', 'feriado'
  tarifa_diaria DECIMAL(10,2),
  EXCLUDE USING GIST (imovel_id WITH =, periodo WITH &&)
);

Consequencias

Operador && (overlap) e @> (contains) funcionam nativamente. Queries de disponibilidade ficam simples e performaticas com indice GiST.

Problema

Como gerar Pix com valor, vencimento e identificacao unicos para cada cobranca de aluguel?

Decisao

Integrar com gateway que suporta Pix Cobranca (QR code dinamico) via API. Nao armazenar chaves Pix no nosso banco — usar tokenizacao do parceiro.

Pix estatico (chave fixa) nao serve para aluguel — nao tem como saber qual inquilino pagou.

Problema

Como garantir recuperacao de dados em caso de desastre, sem custo excessivo?

Decisao

Testes

Restore automatizado testado semanalmente em ambiente de staging. Alerta se falhar.

Problema

Como isolar dados entre organizacoes (imobiliarias) de forma segura e escalavel?

Opcoes consideradas

Decisao

RLS (Row Level Security) com organizacao_id em todas as tabelas. Menos overhead operacional, escala melhor, e o Supabase tem suporte nativo.

Trade-off

Isolamento logico, nao fisico. Bugs em RLS podem vazar dados. Mitigacao: testes automatizados de politicas + audit log.

Para detalhes completos de stack, veja /docs/stack.