@horizon-framework/website-dev-docs 2.3.0 → 2.3.1

package/index.md

@@ -19,6 +19,7 @@
 - [API_PROPERTY.md](./knowledge/API_PROPERTY.md) — Stack, arquitetura, endpoints da API
 - [SEARCH_ENGINE_API.md](./knowledge/SEARCH_ENGINE_API.md) — Motor de busca, facets, pagination, cursor vs offset
 - [BATCH_TOTALS_API.md](./knowledge/BATCH_TOTALS_API.md) — API batch totals, contagens dinamicas
+- [SYNC_API_PATTERN.md](./knowledge/SYNC_API_PATTERN.md) — Padrao /sync (GET/PUT/DELETE), pipeline de transformacao, multi-source (source_key)
 - [SSOT_SPECIFICATION_V2.md](./knowledge/SSOT_SPECIFICATION_V2.md) — Spec SSOT v2.0, metadados hierarquicos
 - [MODULE_CREATION_PATTERN.md](./knowledge/MODULE_CREATION_PATTERN.md) — Padrao de criacao de modulos backend + frontend
 

package/knowledge/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

@@ -1,6 +1,6 @@
 {
   "name": "@horizon-framework/website-dev-docs",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Documentacao inteligente da plataforma Horizon para agentes de IA. Instale para tornar seu agente mais inteligente.",
   "license": "UNLICENSED",
   "private": false,