ttheo.
Voltar

Sistemas modulares

Modelo de dados (shared tables)

Modelo de dados (shared tables)

Em sistemas modulares, o app pai declara entidades que viram tabelas reais no banco. Sub-apps usam essas tabelas sem precisar criar duplicatas.

Onde acessar

No app pai → menu → "Modelo de dados" (ícone Layers).

O que é uma entidade

Cada entidade declarada vira uma tabela:

CREATE TABLE app_<parent-slug>_shared_<name> (
  id SERIAL PRIMARY KEY,
  nome TEXT NOT NULL,
  email TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

Você define nome, descrição e colunas pela UI. A plataforma cuida do DDL automaticamente.

Colunas suportadas

TipoUso comum
SERIALID auto-incremento (sempre primary)
TEXTTexto livre
INTEGERNúmeros inteiros
BIGINTIDs externos grandes
NUMERICValores monetários (com decimais)
BOOLEANSim/Não
DATEData sem hora
TIMESTAMPData + hora
TIMESTAMPTZData + hora com timezone
JSONBEstruturas aninhadas

Cada coluna tem flags:

  • PK (primary key): identifica a row. Geralmente id SERIAL PRIMARY KEY.
  • Obrigatório (NOT NULL): bloqueia INSERT sem valor.
  • Default: valor automático (ex: NOW() pra timestamps, 0 pra contadores).

Editar schema

Quando você adiciona/remove/edita entidades + clica "Aplicar mudanças no banco", a plataforma roda DDL automático:

  • Entidade nova → CREATE TABLE IF NOT EXISTS
  • Entidade removida → DROP TABLE (perde dados!)
  • Coluna nova → ALTER TABLE ... ADD COLUMN (com default se NOT NULL)
  • Coluna removida → ALTER TABLE ... DROP COLUMN
  • Tipo de coluna mudou → não suportado (delete + cria novamente)

Tudo em transação — se qualquer comando falha, rollback total.

Como sub-apps usam

Quando você cria um sub-app via ?parentId=X, o backend injeta o schema completo no contexto da IA. Ela vê algo como:

SUB-APP de "CRM" (crm)

Entidades compartilhadas (disponíveis read+write):

clientes (table: app_crm_shared_clientes)
CREATE TABLE app_crm_shared_clientes (
  id SERIAL PRIMARY KEY,
  nome TEXT NOT NULL,
  email TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

Regras:
- Use os nomes EXATOS acima
- Você pode SELECT/INSERT/UPDATE/DELETE em todas
- NÃO use CREATE TABLE pra entidades compartilhadas — já existem

Resultado: a IA gera código usando app_crm_shared_clientes, não inventa app_clientes_x7k2.

Quando não usar shared tables

Pra dados específicos do sub-app (config local, cache, drafts), cria com prefix próprio:

CREATE TABLE app_<este-sub-app-slug>_<entity>_<hash> (...)

Esses ficam isolados — outros sub-apps não veem.

Preflight check

A regra MISSING_OWNER_FILTER pula tabelas shared — elas são multi-tenant by design, não precisam de WHERE owner_id =. Pra tabelas privadas, a regra continua ativa.

Limites

  • Até 20 entidades por sistema
  • Até 40 colunas por entidade
  • Nome de entidade e coluna em snake_case minúsculo

Próximos passos