> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criando Entidades

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

<Warning>
  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](/developers).
</Warning>

# 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](#criando-entidades)
  * [Diretório de Entidades](#entity-directory)
  * [Como criar uma entidade](#how-to-create-an-entity)
  * [Estrutura do schema da entidade](#entity-schema-structure)
  * [Tipos de campo suportados](#supported-field-types)
  * [Propriedades de campo](#field-properties)
  * [Exemplo completo](#complete-example)
  * [Convenções de nomenclatura](#naming-conventions)
  * [Relacionamentos entre entidades](#relationships-between-entities)
  * [Row Level Security (RLS)](#row-level-security-rls)
  * [Field Level Security (FLS)](#field-level-security-fls)
  * [Enviando entidades](#pushing-entities)

## 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

1. Crie um novo arquivo `.jsonc` no diretório `base44/entities/`
2. Defina seu schema de entidade seguindo a estrutura abaixo
3. 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:

```jsonc theme={null}
{
  "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`:

```jsonc theme={null}
{
  "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:

```jsonc theme={null}
{
  "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:

```jsonc theme={null}
{
  "title": {
    "type": "string",
    "description": "Task title"
  }
}
```

Com formato:

```jsonc theme={null}
{
  "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:

```jsonc theme={null}
{
  "status": {
    "type": "string",
    "enum": ["todo", "in_progress", "done"],
    "default": "todo",
    "description": "Current status"
  }
}
```

### Number

```jsonc theme={null}
{
  "position": {
    "type": "number",
    "description": "Position for ordering"
  }
}
```

### Integer

Apenas para números inteiros:

```jsonc theme={null}
{
  "quantity": {
    "type": "integer",
    "description": "Item quantity",
    "minimum": 0,
    "maximum": 1000
  }
}
```

### Binary

Para dados de arquivo/blob:

```jsonc theme={null}
{
  "attachment": {
    "type": "binary",
    "description": "File attachment"
  }
}
```

### Boolean

```jsonc theme={null}
{
  "notify_on_change": {
    "type": "boolean",
    "default": true,
    "description": "Enable notifications"
  }
}
```

### Array de Strings

```jsonc theme={null}
{
  "labels": {
    "type": "array",
    "items": { "type": "string" },
    "description": "Task labels/tags"
  }
}
```

### Array de Objetos

```jsonc theme={null}
{
  "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:

```jsonc theme={null}
{
  "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:

```jsonc theme={null}
{
  "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:

1. **`true`** - Permitir todos os usuários (incluindo anônimos/não autenticados)
2. **`false`** - Bloquear todos os usuários
3. **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:

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

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

```jsonc theme={null}
{
  "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](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md)**

### Exemplos RLS

**Acesso apenas do proprietário:**

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

**Acesso baseado em departamento:**

```jsonc theme={null}
{
  "data.department": "{{user.data.department}}"
}
```

**Acesso apenas de administrador:**

```jsonc theme={null}
{
  "user_condition": { "role": "admin" }
}
```

**Configuração RLS completa:**

```jsonc theme={null}
{
  "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):**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "user_condition": { "role": "admin" } },
    "update": { "user_condition": { "role": "admin" } },
    "delete": { "user_condition": { "role": "admin" } }
  }
}
```

**Acesso apenas do proprietário:**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

**Apenas usuários logados:**

```jsonc theme={null}
{
  "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](https://docs.base44.com/developers/skills/base44-cli/references/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:

1. **Use a interface do painel Base44** - O painel permite adicionar várias regras por operação com lógica OR
2. **Use entidades separadas** - Divida os dados em várias entidades com diferentes regras de acesso
3. **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

```jsonc theme={null}
{
  "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`.

```bash theme={null}
npx base44 entities push
```

Para mais detalhes sobre o comando push, veja [entities-push.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-push.md).

<Note>Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a [versão em inglês](/). </Note>