# Campos (fields)

> As factories de campo do oon-core-back e os tipos equivalentes do manifesto de domínio, com metadata para o frontend.

`fields` produz descritores compatíveis com Mongoose e com a metadata do Core. Cada helper retorna `{ ...mongoose, __meta }`; o bloco `__meta` alimenta `/core/models` sem vazar para o schema final.

```javascript
const { fields } = require("@oondemand/oon-core-back");
```

## Referência

| Factory | Tipo Mongoose | Metadata | Observações |
|---|---|---|---|
| `fields.string(opts)` | `String` (com `trim`) | `string` | `searchable` é **true por padrão**; use `searchable: false` para excluir da busca |
| `fields.number(opts)` | `Number` | `number` | — |
| `fields.boolean(opts)` | `Boolean` | `boolean` | `default` padrão `false` |
| `fields.date(opts)` | `Date` | `date` | — |
| `fields.ref(model, opts)` | `ObjectId` com `ref` | `ref` | Renderizado como seletor pesquisável no frontend |
| `fields.enum(values, opts)` | `String` com `enum` | `enum` (`options`) | — |
| `fields.currency(opts)` | `Number`, `min: 0` | `currency` | `default` padrão `0` |
| `fields.currencyCode(opts)` | `String` ISO 4217 maiúsculo | `currencyCode` | Padrão `"BRL"` |
| `fields.currencyConverted(opts)` | `Number`, `min: 0` | `currencyConverted` | `base` (padrão `"BRL"`) |

Opções comuns: `required`, `default` e `label`.

```javascript
schema: {
  nome: fields.string({ required: true, label: "Nome" }),
  observacao: fields.string({ label: "Observação", searchable: false }),
  quantidade: fields.number({ required: true, label: "Quantidade" }),
  ativo: fields.boolean({ default: true, label: "Ativo" }),
  vencimento: fields.date({ label: "Vencimento" }),
  cliente: fields.ref("Cliente", { required: true, label: "Cliente" }),
  etapa: fields.enum(["Aberto", "Concluído"], { default: "Aberto", label: "Etapa" }),
  valor: fields.currency({ label: "Valor" }),
  moeda: fields.currencyCode({ label: "Moeda" }),
  valorBrl: fields.currencyConverted({ base: "BRL", label: "Valor em BRL" }),
}
```

Você também pode usar uma definição Mongoose crua; ela aparece na metadata com `kind: "raw"` e não ganha renderização especializada.

## Tipos no manifesto de domínio

No `central.domain.json`, use `kind`:

| `kind` | Opções específicas |
|---|---|
| `string` | `minLength`, `maxLength` |
| `number` | `min`, `max`, `computed` |
| `boolean` | — |
| `date` | — |
| `ref` | `ref` (nome da model relacionada) |
| `enum` | `values` (textos únicos e não vazios) |
| `currency` | `min`, `max`, `computed` |
| `currencyCode` | — |
| `currencyConverted` | `base` (ISO de três letras), `computed` |

Opções comuns: `label`, `description`, `required`, `default`, `readonly`, `searchable`, `unique`, `index`.

```json
{
  "fields": {
    "titulo": { "kind": "string", "required": true, "maxLength": 120, "label": "Título" },
    "cliente": { "kind": "ref", "ref": "Cliente", "required": true },
    "etapa": { "kind": "enum", "values": ["Aberto", "Fechado"], "default": "Aberto" },
    "valor": { "kind": "currency", "min": 0 },
    "statusIntegracao": { "kind": "string", "readonly": true }
  }
}
```

## Como o frontend usa a metadata

| `kind` | Controle no formulário | Coluna |
|---|---|---|
| `string` | texto | texto |
| `number` | numérico | número |
| `boolean` | switch/checkbox | sim/não |
| `date` | data | data |
| `ref` | seletor pesquisável com busca no backend | rótulo do registro |
| `enum` | select | badge |
| `currency` | moeda | moeda |

Campos `readonly` e `computed` aparecem como somente leitura e **não são enviados** pelo formulário. Overrides pontuais de campo (checkbox com valores de domínio, grupos, opções remotas) estão em [Formulários e overrides](/docs/frontend/formularios).

Fonte: https://sdk.oonapps.com/docs/backend/campos