ADR-DB-001-platform — Database Platform Standard para iaw-platform

Contexto

O iaw-platform e o hub central de billing da In All Web. Gere subscricoes, pagamentos Stripe, facturas Moloni e provisioning de tenants para os SaaS (booking + stores). Tem SLA legal por Stripe Connect e SAF-T Moloni.

O STD-DB-001 (aprovado 2026-04-15) define 5 camadas obrigatorias para todos os produtos. Este ADR documenta como o iaw-platform implementa cada camada.

Decisao

O iaw-platform adopta o STD-DB-001 integralmente, sem excepcoes.

RPO/RTO (validado pelo Dany)

Metrica	Valor	Justificacao
RPO	5 min	SLA legal Stripe + Moloni SAF-T — perder >5min de transaccoes = inconsistencia fiscal
RTO	1 hora	Clientes nao podem ficar sem checkout/billing >1h

Camadas — Estado Actual e Plano

C0 — Data Model Hygiene (pre-go-live)

Requisito	Estado	Notas
tenant_id UUID NOT NULL em tabelas multi-tenant	Parcial	clients, subscriptions, invoices tem. Verificar tickets, domains
PK UUID v7	Nao	Usa Integer auto-increment. Migracao gradual (novas tabelas UUID)
TIMESTAMPTZ created_at/updated_at	Sim	Todas as tabelas
deleted_at soft delete	Parcial	clients tem. Adicionar a subscriptions, invoices
FKs ON DELETE explicito	Verificar	Auditar todas as FKs
CHECK enums	Parcial	Status fields usam String — migrar para CHECK
UNIQUE com tenant_id	Verificar	Auditar constraints

Accao: CI job db:hygiene para validar automaticamente.

C1 — Pagination (pre-go-live)

Requisito	Estado	Notas
Contrato items + pagination	Parcial	Admin endpoints usam. Portal parcial
page_size max 200	Nao enforced	Adicionar validacao Pydantic
Cursor pagination >100K rows	Nao	Implementar quando tabelas crescerem
Proibir SELECT * e COUNT >1M	Nao	Adicionar linting SQL

C2 — Indexes (<10K rows)

Requisito	Estado	Notas
Compostos comecam tenant_id	Verificar	Auditar indices existentes
pg_trgm para ILIKE	Nao	Adicionar para busca de clientes
Alembic CONCURRENTLY	Nao	Aplicar em proximas migracoes

C3 — Scaling (quando necessario)

Requisito	Threshold	Estado
C3a PgBouncer	>50 conns	Nao necessario agora (2 clientes)
C3b Read replicas	read:write >5:1	Nao necessario agora
C3c Partitioning	stripe_events >5M rows	Futuro
C3d Redis cache	Nao cachear billing/stock	Ja cumprido (Redis so para Celery)
C3e Materialized views	Query >1s	Nao necessario agora

C4 — Resiliencia (dia 1)

Requisito	Estado	Notas
C4a Backups PITR	Parcial	Cron diario existe. WAL archive por configurar
C4b DR runbook	Nao	Criar runbook
C4c pg_stat_statements	Nao	Activar imediatamente
C4c Slow query 500ms	Nao	Configurar log_min_duration_statement
C4c Alertas Zabbix	Parcial	Pool/lag/disk por configurar
C4d RLS	Nao	Middleware UnifiedTenantMiddleware faz filtering. RLS DB-level por implementar
C4d sslmode=require	Verificar	Confirmar connection string
C4d Rotacao 90d Vault	Nao	Configurar
C4d pgaudit billing	Nao	Instalar e configurar
C4e RGPD anonimizacao	Sim	anonymize_db.py existe
C4e Portability JSON	Nao	Adicionar export endpoint
C4e Audit 2 anos	Nao	Configurar retencao

Tabelas Criticas (SLA Legal)

Tabela	Tipo	RPO	Justificacao
invoices	Billing	5min	SAF-T Moloni — obrigacao fiscal
payment_intents	Stripe	5min	Reconciliacao Stripe Connect
subscriptions	Billing	5min	Estado de cobranca
stripe_events	Webhooks	5min	Auditoria Stripe
tax_records	Fiscal	5min	Conformidade SAF-T
tenants	Core	15min	Provisioning
clients	Core	15min	Dados pessoais RGPD

Accoes Imediatas (3 dias)

1. pg_stat_statements — activar em todos os ambientes
2. Slow query logging — log_min_duration_statement = 500
3. Verificar sslmode — connection strings em .env e Vault

Accoes 1 Semana

4. Backup encryption — chaves no Vault
5. WAL archive — configurar para RPO 5min
6. CI job db:hygiene — validar C0 automaticamente

Accoes 2 Semanas

7. Simulacro DR — testar restore do backup
8. RLS policies — adicionar a tabelas criticas
9. pgaudit — activar para tabelas billing

Excepcoes

Nenhuma. O iaw-platform adopta o STD-DB-001 integralmente.

---

Referencia canonica: STD-DB-001 v1.0.0 (2026-04-15) Aprovado por: Dany Coutinho