@horizon-framework/api-nextjs-docs 2.3.0

package/docs/SSOT_SPECIFICATION_V2.md

@@ -0,0 +1,333 @@
+# SSOT (Single Source of Truth) - Especificação v2.0
+
+## Visão Geral
+
+O novo formato SSOT v2.0 organiza metadados de campos em **contextos específicos**, permitindo separação clara de responsabilidades e melhor organização dos dados.
+
+### Filosofia do Formato
+- **Contextos Separados**: Cada tipo de metadado tem seu lugar específico
+- **Estrutura Hierárquica**: Agrupamento lógico das propriedades
+- **Flexibilidade**: Campos podem ser vazios e preenchidos conforme necessário
+- **Evolução Gradual**: Estrutura permite crescimento sem quebrar compatibilidade
+
+---
+
+## Estrutura dos Contextos
+
+### 1. **RAIZ** - Identificação Básica
+```typescript
+{
+  "key": "campo_exemplo",           // Identificador único (snake_case)
+  "type": "String",                 // Tipo de dado (String, Number, Boolean, String[], Json)
+  "enum": {"key": "Label"},         // Valores possíveis (quando aplicável)
+  "format": "currency",             // Formatação de exibição
+  "unit": "BRL",                    // Unidade de medida
+  "categories": ["valores"]         // Tags/categorias para filtros
+}
+```
+
+### 2. **RULES** - Regras e Relações
+```typescript
+"rules": {
+  "parent": "tipo",                 // Campo pai hierárquico
+  "conditions": ["operacao:venda"]  // Condições de visibilidade
+}
+```
+
+### 3. **VALIDATION** - Validação Backend/Zod
+```typescript
+"validation": {
+  "required": true,                 // Campo obrigatório
+  "min": 0,                        // Valor mínimo (números)
+  "max": 999999.99,                // Valor máximo (números)
+  "minLength": 3,                  // Tamanho mínimo (strings)
+  "maxLength": 200,                // Tamanho máximo (strings)
+  "precision": 2                   // Casas decimais
+}
+```
+
+### 4. **DB** - Configurações de Banco
+```typescript
+"db": {
+  // VAZIO por enquanto - será preenchido conforme necessário
+  // Futuro: index, unique, default, etc.
+}
+```
+
+### 5. **UI** - Interface e Experiência
+```typescript
+"ui": {
+  "label": "Campo Exemplo",        // Rótulo para exibição
+  "description": "Texto de ajuda", // Helper text para formulários
+  "placeholder": "Digite...",      // Placeholder para inputs
+  "icon": "home",                  // Ícone semântico
+  "displayTemplate": "{{value}} m²", // Template de exibição
+  "mask": "cpf",                   // Máscara de input (cpf, cnpj, cep, phone, email)
+  "searchable": true,              // Pesquisável por texto
+  "filterable": true,              // Aparece nos filtros
+  "sortable": true                 // Permite ordenação
+}
+```
+
+### 6. **AUDIT** - Auditoria e Rastreamento
+```typescript
+"audit": {
+  "origin": "horizon-base/imovel", // Origem do campo
+  "modifiedBy": ["system"]         // Histórico de modificações
+}
+```
+
+---
+
+## Tipos de Dados Suportados
+
+| Tipo | Descrição | Exemplo |
+|------|-----------|---------|
+| `String` | Texto simples | "Casa no Centro" |
+| `Number` | Números inteiros e decimais | 150000.50 |
+| `Boolean` | Verdadeiro/Falso | true, false |
+| `String[]` | Array de strings | ["piscina", "churrasqueira"] |
+| `Json` | Objeto JSON | {"lat": -27.5, "lng": -48.5} |
+| `Json[]` | Array de objetos | [{"url": "...", "caption": "..."}] |
+
+---
+
+## Formatos de Exibição
+
+| Format | Unit | Exemplo Entrada | Exemplo Saída |
+|--------|------|----------------|---------------|
+| `currency` | `BRL` | 150000 | R$ 150.000,00 |
+| `currency` | `USD` | 150000 | $ 150,000.00 |
+| `area` | `m2` | 150 | 150 m² |
+| `distance` | `km` | 1.5 | 1,5 km |
+| `percent` | - | 0.15 | 15% |
+| `count` | - | 3 | 3 itens |
+| `date` | - | "2024-01-01" | 01/01/2024 |
+| `datetime` | - | "2024-01-01T10:30:00Z" | 01/01/2024 10:30 |
+
+---
+
+## Categorias Recomendadas
+
+| Categoria | Descrição | Campos Típicos |
+|-----------|-----------|----------------|
+| `valores` | Campos monetários | valor_venda, valor_locacao |
+| `localizacao` | Endereço e geolocalização | endereco_cidade, latitude, longitude |
+| `estrutura` | Características físicas | quartos, banheiros, area_total |
+| `identificacao` | Títulos e referências | title, reference |
+| `comercial` | Informações comerciais | operacao, status |
+| `caracteristicas` | Amenidades e comodidades | piscina, churrasqueira |
+| `sistema` | Campos internos | id, created_at, updated_at |
+
+---
+
+## Máscaras Disponíveis
+
+### Automáticas (inferidas do format + unit)
+- `currency-brl` → R$ 1.000,00 (format: currency + unit: BRL)
+- `currency-usd` → $ 1,000.00 (format: currency + unit: USD)
+- `area` → 100 m² (format: area + unit: m2)
+- `distance` → 1,5 km (format: distance + unit: km)
+- `percent` → 15% (format: percent)
+- `date` → DD/MM/AAAA (format: date)
+
+### Explícitas (para casos específicos)
+- `cpf` → 000.000.000-00
+- `cnpj` → 00.000.000/0000-00
+- `cep` → 00000-000
+- `phone` → (00) 00000-0000
+- `email` → Validação de email
+
+---
+
+## Condições de Visibilidade
+
+### Operadores Disponíveis
+
+| Operador | Descrição | Exemplo |
+|----------|-----------|---------|
+| `:` (padrão) | Contém | `"operacao:venda"` |
+| `.equals` | Igual a | `"tipo.equals:apartamento"` |
+| `.not` | Diferente de | `"status.not:vendido"` |
+| `.in` | Está na lista | `"tipo.in:casa,apartamento"` |
+| `.gt` | Maior que | `"valor.gt:100000"` |
+| `.gte` | Maior ou igual | `"valor.gte:100000"` |
+| `.lt` | Menor que | `"quartos.lt:5"` |
+| `.lte` | Menor ou igual | `"area.lte:200"` |
+| `.exists` | Campo preenchido | `"condominio.exists:true"` |
+
+### Exemplos de Uso
+```typescript
+"rules": {
+  "conditions": [
+    "operacao:venda",              // operacao contém "venda"
+    "tipo.equals:apartamento",     // tipo é exatamente "apartamento"
+    "valor.gte:100000",            // valor >= 100000
+    "quartos.in:2,3,4"             // quartos é 2, 3 ou 4
+  ]
+}
+```
+
+---
+
+## Exemplos Práticos
+
+### Campo Simples
+```json
+{
+  "key": "title",
+  "type": "String",
+  "categories": ["identificacao"],
+  "validation": {
+    "required": true,
+    "minLength": 3,
+    "maxLength": 200
+  },
+  "ui": {
+    "label": "Título",
+    "description": "Título do imóvel",
+    "placeholder": "Ex: Casa no Centro",
+    "searchable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo com Enum
+```json
+{
+  "key": "tipo",
+  "type": "String",
+  "enum": {
+    "casa": "Casa",
+    "apartamento": "Apartamento",
+    "terreno": "Terreno"
+  },
+  "categories": ["estrutura"],
+  "validation": {
+    "required": true
+  },
+  "ui": {
+    "label": "Tipo",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo Monetário
+```json
+{
+  "key": "valor_venda",
+  "type": "Number",
+  "format": "currency",
+  "unit": "BRL",
+  "categories": ["valores"],
+  "validation": {
+    "min": 0,
+    "max": 999999999.99,
+    "precision": 2
+  },
+  "ui": {
+    "label": "Valor de Venda",
+    "displayTemplate": "{{value}}",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo com Condição
+```json
+{
+  "key": "valor_locacao",
+  "type": "Number",
+  "format": "currency",
+  "unit": "BRL",
+  "categories": ["valores"],
+  "rules": {
+    "conditions": ["operacao:locacao"]
+  },
+  "validation": {
+    "min": 0,
+    "precision": 2
+  },
+  "ui": {
+    "label": "Valor de Locação",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+---
+
+## Geração Automática
+
+### Zod Schema
+A partir do SSOT, é gerado automaticamente:
+- Schema Zod para validação
+- Tipos TypeScript inferidos
+- Funções de validação (parse, safeParse, partial)
+
+### Exemplo de Geração
+```typescript
+// Gerado automaticamente a partir do SSOT
+export const ImovelZod = z.object({
+  id: z.number().optional(),
+  reference: z.string().min(1).max(50),
+  title: z.string().min(3).max(200),
+  tipo: z.enum(["casa", "apartamento", "terreno"]),
+  valor_venda: z.number().min(0).multipleOf(0.01).optional()
+})
+
+export type ImovelType = z.infer<typeof ImovelZod>
+```
+
+---
+
+## Vantagens do Novo Formato
+
+1. **Organização Clara**: Cada contexto tem seu espaço definido
+2. **Flexibilidade**: Campos podem ser vazios e evoluir gradualmente  
+3. **Separação de Responsabilidades**: UI, validação, DB em contextos isolados
+4. **Manutenibilidade**: Fácil identificar onde cada metadado pertence
+5. **Evolução**: Adicionar novos contextos sem quebrar existentes
+6. **Reuso**: Mesmo campo pode ter comportamentos diferentes por contexto
+
+---
+
+## Checklist de Criação
+
+### Campo Mínimo Obrigatório
+- [ ] `key` - Identificador único
+- [ ] `type` - Tipo de dado  
+- [ ] `ui.label` - Rótulo para exibição
+- [ ] `audit.origin` - Origem do campo
+
+### Campo Típico (recomendado)
+- [ ] Validação básica (`required`, limites)
+- [ ] Categoria para organização
+- [ ] Formatação quando aplicável
+- [ ] Configurações de UI (searchable, filterable)
+
+### Campo Complexo
+- [ ] Enum quando valores limitados
+- [ ] Condições de visibilidade
+- [ ] Display template customizado
+- [ ] Relacionamentos hierárquicos
+
+---
+
+Esta especificação serve como **base definitiva** para criação de schemas SSOT v2.0 no sistema, garantindo consistência, flexibilidade e evolução controlada dos metadados.

package/docs/SYNC_API_PATTERN.md

@@ -0,0 +1,268 @@
+# Sync API — Padrao de Sincronizacao de Modulos
+
+> Endpoint /sync que TODO modulo backend Horizon implementa.
+> Ponto de entrada de dados externos (CRM, integradores) para o banco.
+
+---
+
+## Visao Geral
+
+Cada modulo tem 3 operacoes no /sync:
+
+| Metodo | Rota | Autenticacao | Funcao |
+|---|---|---|---|
+| GET | /api/{entity}/sync | Publico (CORS *) | Listing — retorna IDs + refs + updated_at para diff |
+| PUT | /api/{entity}/sync | API Key (x-api-key) | Upsert batch — recebe array, valida, transforma, persiste |
+| DELETE | /api/{entity}/sync | API Key (x-api-key) | Delete por refs/keys — remove items do banco |
+
+---
+
+## Arquitetura de Arquivos
+
+```
+apps/api/src/
+├── app/api/{entity}/sync/
+│   └── route.ts                    # "Ponte seca" — exporta controller
+├── core/
+│   ├── prisma.ts                   # Singleton Prisma Client
+│   └── route-helpers.ts            # withApiKeyProtection() + withPublicCors()
+└── modules/{entity}/
+    ├── schemas/
+    │   └── source-schema.zod.ts    # Importa Zod do pacote CRM
+    ├── controllers/
+    │   └── sync.controller.ts      # GET/PUT/DELETE — valida body, chama service
+    ├── services/
+    │   └── sync.service.ts         # Logica: prepare → transaction → return
+    └── mappers/
+        ├── dataModifier/
+        │   ├── index.ts            # ObjectTransformer com regras do cliente
+        │   └── rules.ts            # Regras especificas CRM/cliente (pode estar vazio)
+        └── computedFields/
+            ├── index.ts            # Orquestra todos os computed
+            ├── seo-slug-gen.ts     # Gera slug SEO
+            ├── thumbnails.ts       # Gera thumbnails das imagens
+            ├── endereco-completo.ts# Monta endereco formatado
+            ├── tipo-subtipo-gen.ts # Mapeia tipo → tipo_gen + subtipo_gen
+            └── valor-m2.ts         # Calcula valor por m2
+```
+
+---
+
+## Fluxo PUT (Upsert)
+
+```
+1. REQUEST → PUT /api/{entity}/sync (x-api-key header)
+   Body: { "{entity}s": [ {...item1}, {...item2} ] }
+
+2. ROUTE → withApiKeyProtection() verifica x-api-key
+   Se invalido: 401 Unauthorized
+
+3. CONTROLLER
+   → Parse body JSON
+   → Validacao Zod RIGOROSA do array
+     Property: usa Zod do pacote CRM (ex: HorizonPropertySchemaBySi9Zod)
+     Broker: schema inline com .passthrough()
+   Se falha: 400 com detalhes Zod
+
+4. SERVICE
+   → validateUpsertInput() — array nao vazio, cada item tem key/reference
+   → Loop de preparacao (cada item):
+     - dataModifier(item)       → Regras de negocio do cliente
+     - computeFields(item)      → Campos calculados (slug, thumb, endereco, flags)
+     - stripUnknownFields(item) → Remove campos que nao existem no model Prisma
+     - Salva sync_raw_data      → JSONB com snapshot completo
+   → Prisma.$transaction():
+     - BACKUP first_synced_at dos existentes
+     - deleteMany({ where: { reference: { in: refs } } })
+     - createMany({ data: prepared, skipDuplicates: true })
+     - Restaura first_synced_at
+
+5. RESPONSE
+   { success: true, inserted: N, updated: N, total: N, references: [...] }
+```
+
+**Por que delete + insert (e nao upsert nativo)?**
+Prisma upsert opera 1 registro por vez. Para batches de 50+ itens, deleteMany + createMany numa transaction e mais performatico. Garante que campos removidos do CRM sao limpos.
+
+---
+
+## Fluxo GET (Listing)
+
+```
+GET /api/{entity}/sync?source_key=si9-api-imoveis
+
+→ findMany com select minimo: { id, reference, source_updated_at }
+→ Filtro opcional por source_key
+→ Ordenado por source_updated_at DESC
+→ Mapeia source_updated_at → updated_at na saida
+
+Response: { properties: [{ id, reference, updated_at }, ...] }
+```
+
+**Proposito:** Integrador faz GET listing → compara updated_at com dados do CRM → envia PUT apenas com os que mudaram. Evita re-sincronizar tudo.
+
+---
+
+## Fluxo DELETE
+
+```
+DELETE /api/{entity}/sync (x-api-key header)
+Body: { "refs": ["ABC-123", "DEF-456"] }
+     (property usa "refs", broker usa "keys")
+
+→ Validacao: array nao vazio
+→ prisma.{entity}.deleteMany({ where: { reference: { in: refs } } })
+
+Response: { success: true, deleted: N, references: [...] }
+```
+
+---
+
+## Pipeline de Transformacao
+
+```
+Dados do CRM (formato CRM)
+  ↓
+Pacote CRM (@horizon-integrations/{crm}-crm)  ← FORA da API, no automations
+  Converte formato CRM → formato Horizon
+  ↓
+PUT /api/{entity}/sync                          ← ENTRADA NA API
+  ↓
+source-schema.zod.ts                            ← Validacao Zod rigorosa
+  ↓
+dataModifier (mappers/dataModifier/)            ← Regras de negocio do CLIENTE
+  ObjectTransformer com rules.ts
+  Pode estar VAZIO (passthrough)
+  ↓
+computedFields (mappers/computedFields/)        ← Campos CALCULADOS
+  seo_slug_gen, thumbnails, endereco_completo,
+  tipo_gen, subtipo_gen, has_video, has_tour,
+  financiavel, first_synced_at
+  ↓
+stripUnknownFields()                            ← Protecao do Prisma
+  Filtra via Prisma.{Entity}ScalarFieldEnum
+  ↓
+sync_raw_data (JSONB)                           ← Snapshot completo
+  ↓
+Prisma $transaction (delete + insert)           ← Persistencia
+```
+
+---
+
+## Protecao de Rotas
+
+```typescript
+// route.ts — padrao para todo modulo
+export const { OPTIONS, GET, PUT, DELETE } = withApiKeyProtection({
+  GET: ControllerGET,     // Publico (CORS *)
+  PUT: ControllerPUT,     // Protegido (x-api-key)
+  DELETE: ControllerDELETE // Protegido (x-api-key)
+});
+```
+
+---
+
+## Diferencas Property vs Broker
+
+| Aspecto | Property | Broker |
+|---|---|---|
+| Chave unica | reference | key |
+| Validacao Zod | Rigorosa (schema CRM) | Flexivel (.passthrough()) |
+| dataModifier | ObjectTransformer com rules | Funcao simples |
+| computedFields | 7+ campos | Poucos (slug, timestamps) |
+| stripUnknownFields | Sim | Nao |
+| sync_raw_data | Sim (JSONB) | Nao |
+| first_synced_at | Sim (preservado) | Nao |
+| GET source_key | Sim | Nao (ainda) |
+
+---
+
+## Multi-Source Sync — Padrao source_key
+
+### O Problema
+
+Uma integracao pode ter MULTIPLAS fontes de dados para a mesma entidade:
+
+| source_key | Fonte | Descricao |
+|---|---|---|
+| si9-api-imoveis | SI9 CRM | Imoveis proprios da imobiliaria |
+| nifb-vrsync-imoveis | VRSync/NIFB | Imoveis do Nucleo de Imoveis |
+
+Sem source_key, ao sincronizar imoveis do SI9, o deleteMany poderia deletar imoveis do NIFB.
+
+### Regra Obrigatoria
+
+**Toda integracao que enviar dados via PUT /sync DEVE incluir source_key em cada item.**
+
+```json
+{
+  "properties": [
+    {
+      "source_key": "si9-api-imoveis",
+      "reference": "ABC-123",
+      "title": "Casa 3 quartos"
+    }
+  ]
+}
+```
+
+### Onde o source_key atua
+
+**PUT (Upsert):** Cada item chega com source_key preenchido, salvo no banco.
+
+**GET (Listing):** Integrador filtra apenas seus registros:
+```
+GET /api/property/sync?source_key=si9-api-imoveis  → So imoveis do SI9
+GET /api/property/sync?source_key=nifb-vrsync-imoveis → So imoveis do NIFB
+GET /api/property/sync → Sem filtro: retorna TODOS
+```
+
+**DELETE — Scoping por fonte (EVOLUCAO NECESSARIA):**
+Estado atual: DELETE opera por references SEM filtrar por source_key.
+Evolucao: DELETE deveria aceitar source_key como filtro adicional:
+
+```typescript
+// Evolucao: DELETE com scoping por source
+await tx.property.deleteMany({
+  where: {
+    reference: { in: refs },
+    source_key: sourceKey  // ← Protecao: so deleta da mesma fonte
+  }
+});
+```
+
+**Upsert Transaction — Scoping (EVOLUCAO NECESSARIA):**
+Estado atual: deleteMany na transaction deleta por reference sem filtrar source_key.
+Evolucao: Adicionar source_key no where:
+
+```typescript
+const sourceKey = preparedImoveis[0]?.source_key;
+await tx.property.deleteMany({
+  where: {
+    reference: { in: references },
+    ...(sourceKey && { source_key: sourceKey })
+  }
+});
+```
+
+### Nomenclatura padrao de source_key
+
+Formato: `{crm}-{api|sync|vrsync}-{entidade-plural}`
+
+Exemplos:
+- `si9-api-imoveis`
+- `jetimob-api-imoveis`
+- `nifb-vrsync-imoveis`
+- `si9-api-corretores`
+- `manual-import-imoveis` (importacoes manuais)
+
+### Ao criar modulo com multi-source
+
+1. Banco: adicionar coluna `source_key TEXT`
+2. Prisma: campo `source_key String?`
+3. entity-schema.ts: campo com `filterable: true` e enum das fontes
+4. Controller GET: aceitar `?source_key=` como query param
+5. Service listing: filtrar `where: { source_key }` quando presente
+6. Service upsert: garantir que source_key vem no payload e e persistido
+7. Service delete: usar source_key como filtro adicional no deleteMany
+8. Automations: cada integracao DEVE enviar source_key

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@horizon-framework/api-nextjs-docs",
+  "version": "2.3.0",
+  "description": "Documentacao do backend generico Horizon — sync, search engine, SSOT, batch totals",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}