Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a documentação para desenvolvedores.

Criando Entidades

As entidades Base44 são definidas localmente no seu projeto e depois enviadas ao backend Base44.

Crítico: Nomenclatura de arquivo

Arquivos de entidade DEVEM usar nomenclatura kebab-case: {kebab-case-name}.jsonc

Nome da entidade	Nome do arquivo
`Task`	`task.jsonc`
`TeamMember`	`team-member.jsonc`
`ActivityLog`	`activity-log.jsonc`

ERRADO: TeamMember.jsonc, teamMember.jsonc CERTO: team-member.jsonc

Índice

Criando Entidades

Diretório de entidades

Todas as definições de entidade devem ser colocadas na pasta base44/entities/ na raiz do seu projeto. Cada entidade é definida em seu próprio arquivo .jsonc. Estrutura de exemplo:

my-app/
  base44/
    entities/
      user.jsonc
      product.jsonc
      order.jsonc

Como criar uma entidade

Crie um novo arquivo .jsonc no diretório base44/entities/
Defina seu schema de entidade seguindo a estrutura abaixo
Envie as alterações para a Base44 usando a CLI

Estrutura do schema da entidade

Cada arquivo de entidade segue uma estrutura semelhante ao JSON Schema:

{
  "name": "EntityName",       // PascalCase entity name
  "type": "object",           // Always "object"
  "properties": {
    // Define your fields here
  },
  "required": ["field1"]      // Array of required field names
}

Erro comum: Propriedade schema aninhada

ERRADO - NÃO envolva propriedades em um objeto schema:

{
  "name": "Task",
  "description": "A task entity",
  "schema": {                    // ❌ WRONG - don't use nested "schema"
    "type": "object",
    "properties": { ... }
  }
}

CORRETO - Coloque type e properties no nível superior:

{
  "name": "Task",
  "description": "A task entity",
  "type": "object",              // ✅ CORRECT - top level
  "properties": { ... }          // ✅ CORRECT - top level
}

Este é um erro comum que causará “Invalid schema: Schema must have a ‘type’ field” ao enviar entidades.

Tipos de campo suportados

String

Campo de texto básico:

{
  "title": {
    "type": "string",
    "description": "Task title"
  }
}

Com formato:

{
  "due_date": {
    "type": "string",
    "format": "date",
    "description": "Due date"
  }
}

Formatos disponíveis: date, date-time, time, email, uri, hostname, ipv4, ipv6, uuid, file, regex, richtext

String com Enum

Restrito a valores específicos:

{
  "status": {
    "type": "string",
    "enum": ["todo", "in_progress", "done"],
    "default": "todo",
    "description": "Current status"
  }
}

Number

{
  "position": {
    "type": "number",
    "description": "Position for ordering"
  }
}

Integer

Apenas para números inteiros:

{
  "quantity": {
    "type": "integer",
    "description": "Item quantity",
    "minimum": 0,
    "maximum": 1000
  }
}

Binary

Para dados de arquivo/blob:

{
  "attachment": {
    "type": "binary",
    "description": "File attachment"
  }
}

Boolean

{
  "notify_on_change": {
    "type": "boolean",
    "default": true,
    "description": "Enable notifications"
  }
}

Array de Strings

{
  "labels": {
    "type": "array",
    "items": { "type": "string" },
    "description": "Task labels/tags"
  }
}

Array de Objetos

{
  "attachments": {
    "type": "array",
    "description": "File attachments",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "url": { "type": "string" },
        "type": { "type": "string" }
      }
    }
  }
}

Propriedades de campo

Propriedade	Descrição
`type`	Tipo de dado: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`
`description`	Descrição legível do campo
`enum`	Array de valores permitidos (para strings)
`enumNames`	Rótulos legíveis para valores de enum (mesma ordem que `enum`)
`default`	Valor padrão quando não fornecido
`format`	Dica de formato: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext`
`items`	Schema para itens de array
`properties`	Propriedades aninhadas para tipos de objeto
`$ref`	Referência a outra definição de schema
`minLength`	Comprimento mínimo de string
`maxLength`	Comprimento máximo de string
`pattern`	Padrão regex para validação de string
`minimum`	Valor mínimo para números
`maximum`	Valor máximo para números
`rls`	Regras de segurança em nível de campo (veja a seção Field Level Security)

Exemplo completo

Aqui está uma definição completa de entidade para uma Task:

{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "description": {
      "type": "string",
      "description": "Task description"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo",
      "description": "Current status of the task"
    },
    "board_id": {
      "type": "string",
      "description": "Board this task belongs to"
    },
    "assignee_email": {
      "type": "string",
      "description": "Email of assigned user"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium",
      "description": "Task priority"
    },
    "due_date": {
      "type": "string",
      "format": "date",
      "description": "Due date"
    },
    "labels": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Task labels/tags"
    }
  },
  "required": ["title"]
}

Convenções de nomenclatura

Nome da entidade: Use PascalCase apenas com caracteres alfanuméricos (por exemplo, Task, TeamMember, ActivityLog)
- Deve corresponder ao padrão: /^[a-zA-Z0-9]+$/
- Válido: Task, TeamMember, Order123
- Inválido: Team_Member, Team-Member, Team Member
Nome do arquivo: Use kebab-case correspondente à entidade (por exemplo, task.jsonc, team-member.jsonc, activity-log.jsonc)
Nomes de campo: Use snake_case (por exemplo, board_id, user_email, due_date)

Relacionamentos entre entidades

Para criar relacionamentos entre entidades, use campos de referência de ID:

{
  "board_id": {
    "type": "string",
    "description": "Board this task belongs to"
  },
  "team_id": {
    "type": "string",
    "description": "Associated team ID"
  }
}

Row Level Security (RLS)

O Row Level Security (RLS) controla quais registros os usuários podem acessar com base na sua identidade e atributos. Regras RLS são definidas por entidade dentro do campo rls do schema. Importante: Se nenhum RLS for definido, todos os registros são acessíveis a todos os usuários.

Operações RLS

O RLS suporta cinco operações:

Operação	Descrição
`create`	Controla quem pode adicionar novos registros
`read`	Controla quem pode visualizar registros
`update`	Controla quem pode modificar registros
`delete`	Controla quem pode remover registros
`write`	Abreviação para `create`, `update` e `delete` combinados

Valores de permissão

Cada operação aceita um dos seguintes valores:

true - Permitir todos os usuários (incluindo anônimos/não autenticados)
false - Bloquear todos os usuários
Objeto de condição - Permitir usuários que correspondem à condição

Variáveis de template

Use variáveis de template para referenciar os atributos do usuário atual:

Template	Descrição
`{{user.id}}`	O ID do usuário
`{{user.email}}`	O e-mail do usuário
`{{user.role}}`	A função do usuário
`{{user.data.field_name}}`	Campo personalizado do objeto `data` do usuário

Atributos de entidade integrados

Cada registro de entidade tem esses atributos integrados disponíveis para regras RLS:

Atributo	Descrição
`id`	Identificador único do registro
`created_date`	Timestamp de quando o registro foi criado
`updated_date`	Timestamp de quando o registro foi atualizado pela última vez
`created_by`	E-mail do usuário que criou o registro

Tipos de regra

Existem dois tipos de condição que você pode usar: 1. Comparação entidade-usuário - Compare campos de registro aos valores do usuário atual:

{
  "created_by": "{{user.email}}"
}

2. Verificação de condição de usuário - Verifique propriedades do usuário diretamente usando user_condition:

{
  "user_condition": { "role": "admin" }
}

Notas importantes:

user_condition suporta apenas igualdade simples (por exemplo, { "role": "admin" })
A filtragem de campo de entidade requer prefixo data.: Use { "data.fieldname": value } para filtrar por valores de campo de entidade
Para comparações de campos data.*, você pode usar operadores: $in, $nin, $ne, $all
Operadores lógicos $or, $and, $nor estão disponíveis para combinar condições

⚠️ Para padrões RLS avançados e exemplos, veja rls-examples.md

Exemplos RLS

Acesso apenas do proprietário:

{
  "created_by": "{{user.email}}"
}

Acesso baseado em departamento:

{
  "data.department": "{{user.data.department}}"
}

Acesso apenas de administrador:

{
  "user_condition": { "role": "admin" }
}

Configuração RLS completa:

{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo"
    }
  },
  "required": ["title"],
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}

Padrões RLS comuns

Criação pública, gerenciamento apenas de administrador (por exemplo, formulários de contato, listas de espera):

{
  "rls": {
    "create": true,
    "read": { "user_condition": { "role": "admin" } },
    "update": { "user_condition": { "role": "admin" } },
    "delete": { "user_condition": { "role": "admin" } }
  }
}

Acesso apenas do proprietário:

{
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}

Apenas usuários logados:

{
  "rls": {
    "create": { "user_condition": { "id": "{{user.id}}" } },
    "read": true,
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}

Limitações

user_condition é apenas igualdade: user_condition só suporta correspondência exata (por exemplo, { "role": "admin" }) - sem operadores
Sem operadores de comparação em user_condition: $gt, $lt, $regex, $expr, $where NÃO são suportados para condições de usuário
Sem templates profundamente aninhados: Templates como {{user.data.profile.department}} podem não funcionar

Operadores suportados:

Operadores lógicos: $or, $and, $nor para combinar várias condições
Operadores de campo (para campos data.* apenas): $in, $nin, $ne, $all
Filtragem de campo de entidade: Use o prefixo data. para filtrar por valores de campo de entidade (por exemplo, { "data.status": "published" } ou { "data.completed": true })

⚠️ Veja rls-examples.md para padrões RLS abrangentes e exemplos

Padrões de acesso complexos

Para padrões de acesso complexos que requerem várias condições (por exemplo, “proprietário OU administrador”), você tem duas opções:

Use a interface do painel Base44 - O painel permite adicionar várias regras por operação com lógica OR
Use entidades separadas - Divida os dados em várias entidades com diferentes regras de acesso
Use funções de backend - Implemente lógica de acesso personalizada em funções de backend

Field Level Security (FLS)

O Field Level Security permite controlar o acesso a campos individuais dentro de uma entidade. Regras FLS são definidas dentro do schema de cada campo usando a propriedade rls.

Operações FLS

O FLS suporta as mesmas operações que o RLS no nível de entidade:

Operação	Descrição
`create`	Controla quem pode definir este campo ao criar registros
`read`	Controla quem pode visualizar este campo
`update`	Controla quem pode modificar este campo
`delete`	Controla quem pode limpar este campo
`write`	Abreviação para `create`, `update` e `delete` combinados

Exemplo FLS

{
  "name": "Employee",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Employee name"
    },
    "salary": {
      "type": "number",
      "description": "Employee salary",
      "rls": {
        "read": { "user_condition": { "role": "hr" } },
        "update": { "user_condition": { "role": "hr" } }
      }
    },
    "department": {
      "type": "string",
      "description": "Department name"
    }
  },
  "required": ["name"]
}

Neste exemplo, apenas usuários com a função hr podem ler ou atualizar o campo salary. Todos os usuários com acesso à entidade podem ler/atualizar outros campos.

Notas FLS

Se nenhum RLS em nível de campo for definido, o campo herda as regras RLS em nível de entidade
Regras FLS seguem o mesmo formato de condição que o RLS em nível de entidade
Use FLS para campos sensíveis como salário, CPF ou notas internas

Enviando entidades

O comando entities push envia todas as entidades que existem na pasta base44/entities.

npx base44 entities push

Para mais detalhes sobre o comando push, veja entities-push.md.

Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a versão em inglês.

​Criando Entidades

​Crítico: Nomenclatura de arquivo

​Índice

​Diretório de entidades

​Como criar uma entidade

​Estrutura do schema da entidade

​Erro comum: Propriedade schema aninhada

​Tipos de campo suportados

​String

​String com Enum

​Number

​Integer

​Binary

​Boolean

​Array de Strings

​Array de Objetos

​Propriedades de campo

​Exemplo completo

​Convenções de nomenclatura

​Relacionamentos entre entidades

​Row Level Security (RLS)

​Operações RLS

​Valores de permissão

​Variáveis de template

​Atributos de entidade integrados

​Tipos de regra

​Exemplos RLS

​Padrões RLS comuns

​Limitações

​Padrões de acesso complexos

​Field Level Security (FLS)

​Operações FLS

​Exemplo FLS

​Notas FLS

​Enviando entidades

Criando Entidades

Crítico: Nomenclatura de arquivo

Índice

Diretório de entidades

Como criar uma entidade

Estrutura do schema da entidade

Erro comum: Propriedade schema aninhada

Tipos de campo suportados

String

String com Enum

Number

Integer

Binary

Boolean

Array de Strings

Array de Objetos

Propriedades de campo

Exemplo completo

Convenções de nomenclatura

Relacionamentos entre entidades

Row Level Security (RLS)

Operações RLS

Valores de permissão

Variáveis de template

Atributos de entidade integrados

Tipos de regra

Exemplos RLS

Padrões RLS comuns

Limitações

Padrões de acesso complexos

Field Level Security (FLS)

Operações FLS

Exemplo FLS

Notas FLS

Enviando entidades