_comuns/README.md

# `p-comuns` — Pacote Compartilhado e-licencie

Pacote de tipos, utilitários e configurações compartilhadas entre todos os subprojetos da plataforma **e-licencie** (back-end Node.js, front-end Vue 3 / TSX).

---

## ✅ Configuração do BiomeJS nos Subprojetos

Este guia mostra como usar a configuração base do Biome disponível neste pacote (`Documentos/biome.json`). Todos os subprojetos herdam essas regras via `extends`.

### 1. Adicionar o `p-comuns` como dependência

```bash
pnpm add --save-dev p-comuns
# ou atualizar se já existir:
pnpm up p-comuns
```

---

### 2. Instalar o Biome

```bash
pnpm add --save-dev --save-exact @biomejs/biome@2.4.0
```

> 🎯 Use `--save-exact` para garantir consistência de versões entre ambientes.

---

### 3. Criar `biome.json` na raiz do subprojeto

```json
{
  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["node_modules/p-comuns/Documentos/biome.json"],
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": ["**/*.{ts,tsx,vue}"]
  }
}
```

> `vcs.useIgnoreFile: true` faz o Biome respeitar o `.gitignore` automaticamente — arquivos como `dist/`, `node_modules/` etc. são ignorados sem configuração adicional.

---

### 4. Adicionar scripts no `package.json`

```json
{
  "scripts": {
    "biome": "pnpm exec biome check --write",
    "check": "pnpm run biome && npx tsc --noEmit"
  }
}
```

---

### 5. Configurar o VS Code (`.vscode/settings.json`)

```json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "always",
    "source.fixAll.biome": "always"
  },
  "[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[javascriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[vue]": { "editor.defaultFormatter": "biomejs.biome" },
  "[css]": { "editor.defaultFormatter": "biomejs.biome" },
  "[json]": { "editor.defaultFormatter": "biomejs.biome" },
  "[jsonc]": { "editor.defaultFormatter": "biomejs.biome" },
  "editor.rulers": [100],
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}
```

> 💡 **Biome formata Vue `.vue` nativamente desde a v2.3** — não precisa do Prettier ou Vetur para formatação!

---

## 🔑 Regras da configuração base (Documentos/biome.json)

### O que está ativado:

| Categoria | Regras notáveis |
|-----------|----------------|
| **Correctness** | `noUnusedVariables`, `noUnusedImports`, `noVueSetupPropsReactivityLoss` |
| **Vue 3 específico** | `noVueVIfWithVFor`, `useVueVForKey`, `noVueDuplicateKeys`, `noVueReservedKeys` |
| **Style** | `useAsConstAssertion`, `useSelfClosingElements`, `useConsistentArrayType` (shorthand `T[]`) |
| **Nursery Vue** | `noVueArrowFuncInWatch`, `useVueDefineMacrosOrder`, `useVueConsistentVBindStyle` |
| **Security** | `noDangerouslySetInnerHtml` (warn) |

### Globals do Vue (sem necessidade de importar):

`defineProps`, `defineEmits`, `defineExpose`, `withDefaults`, `defineModel`, `defineOptions`, `defineSlots`

### Formatação:

- Indentação: **2 espaços**
- Linha máxima: **100 caracteres**
- Aspas: **duplas**
- Ponto-e-vírgula: **apenas quando necessário**
- Trailing comma: **sempre**
- Line ending: **LF (`\n`)**

---

## ✅ Sistema de Filtros (tipoFiltro26)

O sistema `tipoFiltro26` foi projetado para gerar automaticamente a tipagem de filtros compatíveis com operadores padrão do PostgreSQL, a partir de um tipo base `T`.

**Principais características:**
- Tipagem forte e segura (TypeScript)
- Suporte a aninhamento de objetos
- Operadores lógicos `E` (AND) e `OU` (OR)
- Validação de operadores permitidos por tipo de dado (string, number, boolean)

### Estrutura do Filtro

#### 1. Campos Simples
```typescript
{ idade: { ">=": 18 } }
```

#### 2. Campos Aninhados
```typescript
{ carro: { ano: { "=": 2020 } } }
```

#### 3. Operadores Lógicos

**Operador E (AND):** Todos devem ser verdadeiros.
```typescript
{
  E: [
    { idade: { ">=": 18 } },
    { nome: { like: "%pa%" } }
  ]
}
```

**Operador OU (OR):** Pelo menos um deve ser verdadeiro.
```typescript
{
  OU: [
    { idade: { "<": 18 } },
    { idade: { ">=": 60 } }
  ]
}
```

#### 4. Exemplo Complexo Completo
```typescript
{
  idade: { ">=": 18 },
  OU: [
    { nome: { like: "%pa%" } },
    {
      E: [
        { carro: { ano: { "=": 2020 } } },
        { carro: { modelo: { in: ["Civic"] } } }
      ]
    }
  ]
}
```

### Operadores Suportados (`operadores26`)

- **Number**: `=`, `!=`, `>`, `>=`, `<`, `<=`, `in`
- **String**: `=`, `!=`, `like`, `in`
- **Boolean**: `=`, `!=`, `in`

### Validação em Tempo de Execução (Zod)

```typescript
import { zFiltro26 } from "p-comuns"

// Valida a estrutura (não checa existência de colunas no DB)
zFiltro26.parse(objetoFiltro)
```

---

## 📚 Veja também

- [`AGENTS.md`](./AGENTS.md) — Guia para assistentes de IA (padrões, convenções, arquitetura)
- [Biome 2.x Docs](https://biomejs.dev)
- [Vue 3 Composition API](https://vuejs.org/guide/composition-api)