# Atualização em massa de campo — Clarizen

App terminal em Node.js para escolher um tipo de entidade e um campo via metadata do Adaptive Work, e atualizar esse campo em massa nos objetos do tipo selecionado (com filtros opcionais).

## Pré-requisitos

- Node.js 18+
- API key do Adaptive Work (`CLARIZEN_API_KEY`)
- Biblioteca `@arco/clarizen-lib` compilada no diretório irmão (`../clarizen-lib`)

## Instalação

```bash
cd ../clarizen-lib && npm install && npm run build
cd ../update_field_API
cp .env.example .env
# Edite .env com CLARIZEN_BASE_URL e CLARIZEN_API_KEY
npm install
```

## Uso

```bash
npm start
```

Fluxo interativo:

1. Autenticação com API key
2. Escolha do tipo de entidade (nível) — lista completa ou filtro por texto
3. **Filtro de objetos** — todos, por State (se o tipo tiver lifecycle), ou cláusula WHERE em CZQL
4. Escolha do campo — cada opção mostra **label**, **nome** e **tipo**
5. Exibição de exemplo de preenchimento conforme o tipo
6. Informe o novo valor (ou limpe o campo, se nullable)
7. Busca dos objetos conforme o filtro
8. Confirmação com resumo (tipo, filtro, campo, valor, quantidade)
9. Atualização em massa com barra de progresso, porcentagem e ETA

## Filtros de objetos

Após escolher o tipo de entidade, você pode limitar quais registros serão atualizados:

| Opção | Descrição |
|-------|-----------|
| Todos os objetos | Sem filtro (comportamento original) |
| Filtrar por State | Disponível quando a metadata expõe `validStates` (ex.: Active, Completed) |
| CZQL WHERE | Informe só a cláusula `WHERE`; o app valida contra a API antes de continuar |

### Exemplos de cláusula WHERE (CZQL)

```
State = 'Active'
Name LIKE 'Projeto%'
State = 'Active' AND Name LIKE 'Test%'
```

A cláusula é aplicada via `entityQuery` com filtro CZQL. Comandos de modificação (`DELETE`, `UPDATE`, etc.) são rejeitados.

## Exemplos de valor por tipo de campo

| Tipo | Como preencher no terminal |
|------|---------------------------|
| Boolean | `true`, `false`, `sim`, `não` |
| String | texto livre, ex: `Meu valor` |
| Integer / Long | `42` |
| Double | `3.14` |
| DateTime | `2026-06-09` ou `2026-06-09T14:30:00Z` |
| Date | `2026-06-09` |
| Entity | `/User/abc-123` ou `{"id":"/User/abc-123"}` |
| Duration | `{"value":5,"unit":"Days"}` |
| Money | `{"value":100,"currency":"BRL"}` |

Campos **nullable** permitem limpar o valor escolhendo "Limpar campo (null)" ou digitando `null`.

## Variáveis de ambiente

| Variável | Descrição |
|----------|-----------|
| `CLARIZEN_BASE_URL` | URL base da API (padrão: `https://api.clarizen.com`) |
| `CLARIZEN_API_KEY` | API key (alternativa: `API_KEY_AW`) |

O app também tenta carregar `../clarizen-lib/.env` se não houver `.env` local.

## Erros

Objetos que falharem na atualização são listados ao final. Um arquivo `errors-<timestamp>.json` é gerado na pasta do projeto com os detalhes.

## Observações

- Apenas campos **atualizáveis** são listados (exclui calculados, create-only e internos).
- A atualização usa `bulk.execute` em lotes de 20, com fallback individual em caso de falha no lote.
- Rate limit da API: ~25 requisições/segundo por organização.