@horizon-framework/api-nextjs-docs 2.3.0

package/docs/MODULE_CREATION_PATTERN.md

@@ -0,0 +1,624 @@
+# Padrão de Criação de Módulos - API v2
+
+> Guia completo para criar novos módulos/entidades no sistema (ex: Branch, Lead, City)
+
+## Arquitetura Completa de um Módulo
+
+Um módulo completo possui **4 componentes principais**:
+
+| Componente | Localização | Responsabilidade |
+|------------|-------------|------------------|
+| **NPM Package** | `/horizon-npm-packages/horizon-modules/{entity}/domain-data/` | Schema base (TypeScript + Zod) |
+| **Database** | `/apps/api/database/tables/{entity}/` | SQL puro (CREATE, índices, FTS) |
+| **API Module** | `/apps/api/src/modules/{entity}/` | Controllers, Services, Mappers |
+| **API Routes** | `/apps/api/src/app/api/{entity}/` | Endpoints Next.js |
+
+---
+
+## Estrutura de Pastas Completa
+
+### NPM Package (`@horizon-domains/{entity}-model`)
+
+```
+horizon-npm-packages/horizon-modules/{entity}/domain-data/
+├── package.json                        # @horizon-domains/{entity}-model
+├── tsconfig.json                       # Configuração TypeScript
+├── tsup.config.ts                      # Build config (CJS, ESM, DTS)
+├── vitest.config.ts                    # Testes
+└── src/
+    ├── index.ts                        # Exports principais
+    └── schemas/
+        ├── types.ts                    # Tipos base (EntitySchema, FieldSchema, etc.)
+        ├── horizon-{entity}-schema-base.ts     # Schema TypeScript
+        └── horizon-{entity}-schema-base.zod.ts # Schema Zod para validação
+```
+
+### Database (SQL)
+
+```
+apps/api/database/tables/{entity}/
+├── create.sql                          # CREATE TABLE + índices
+├── generated-columns.sql               # FTS tsvector, campos derivados
+└── drop.sql                            # DROP TABLE (desenvolvimento)
+```
+
+### API Module
+
+```
+apps/api/src/modules/{entity}/
+├── schemas/                            # Config/Schemas (renomeado de config/)
+│   ├── entity-schema.ts                # Schema TypeScript (SSOT local)
+│   ├── entity-schema.zod.ts            # Validação Zod
+│   └── search-schema.ts                # Schema de busca (se aplicável)
+│
+├── controllers/
+│   ├── find.controller.ts              # POST busca única
+│   ├── search.controller.ts            # POST busca avançada
+│   ├── sync.controller.ts              # PUT upsert / DELETE
+│   └── schemas.controller.ts           # GET schemas JSON
+│
+├── services/
+│   ├── find.service.ts                 # Lógica de busca única
+│   ├── search.service.ts               # Lógica de busca múltipla
+│   └── sync.service.ts                 # Lógica de sync/upsert/delete
+│
+├── mappers/
+│   ├── computedFields/                 # Campos computados
+│   │   ├── index.ts                    # Orquestra computações
+│   │   └── buildSlug.ts                # Gera slug (exemplo)
+│   │
+│   └── dataModifier/                   # Regras de negócio
+│       └── index.ts                    # Transformações cliente-específicas
+│
+└── lib/                                # Funções auxiliares (opcional)
+```
+
+### API Routes
+
+```
+apps/api/src/app/api/{entity}/
+├── find/
+│   └── route.ts                        # POST /api/{entity}/find
+├── search/
+│   └── route.ts                        # POST /api/{entity}/search
+├── sync/
+│   └── route.ts                        # PUT/DELETE /api/{entity}/sync
+└── schemas/
+    ├── entity/
+    │   └── route.ts                    # GET /api/{entity}/schemas/entity
+    └── search/
+        └── route.ts                    # GET /api/{entity}/schemas/search
+```
+
+---
+
+## Passo a Passo para Criar Novo Módulo
+
+### Passo 1: Criar NPM Package
+
+**1.1 Criar estrutura de diretórios:**
+```bash
+mkdir -p /horizon-npm-packages/horizon-modules/{entity}/domain-data/src/schemas
+```
+
+**1.2 Criar `package.json`:**
+```json
+{
+  "name": "@horizon-domains/{entity}-model",
+  "version": "1.0.0",
+  "description": "Schema definitions for {Entity}",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}
+```
+
+**1.3 Criar `tsconfig.json`:**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**1.4 Criar `tsup.config.ts`:**
+```typescript
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});
+```
+
+**1.5 Criar `src/schemas/types.ts`:**
+```typescript
+// Reexportar tipos base do property-model ou definir localmente
+export interface FieldSchema {
+  type: "string" | "number" | "boolean" | "date" | "array" | "object" | "json";
+  required?: boolean;
+  description?: string;
+  ui?: UIMetadata;
+}
+
+export interface UIMetadata {
+  label?: string;
+  placeholder?: string;
+  inputType?: string;
+}
+
+export interface EntitySchema {
+  name: string;
+  description?: string;
+  fields: Record<string, FieldSchema>;
+}
+```
+
+**1.6 Criar `src/schemas/horizon-{entity}-schema-base.ts`:**
+```typescript
+import type { EntitySchema } from "./types";
+
+export const horizon{Entity}SchemaBase: EntitySchema = {
+  name: "{Entity}",
+  description: "Schema base para {Entity}",
+  fields: {
+    key: { type: "string", required: true, description: "Identificador único" },
+    name: { type: "string", required: true, description: "Nome" },
+    slug: { type: "string", required: false, description: "URL amigável" },
+    // Adicione campos específicos aqui
+  }
+};
+```
+
+**1.7 Criar `src/schemas/horizon-{entity}-schema-base.zod.ts`:**
+```typescript
+import { z } from "zod";
+
+export const Horizon{Entity}SchemaBaseZod = z.object({
+  key: z.string().min(1),
+  name: z.string().min(1),
+  slug: z.string().optional(),
+  // Adicione validações Zod aqui
+});
+
+// Versão passthrough (aceita campos extras)
+export const Horizon{Entity}SchemaBaseZodPassthrough = Horizon{Entity}SchemaBaseZod.passthrough();
+
+export type Horizon{Entity}SchemaBaseType = z.infer<typeof Horizon{Entity}SchemaBaseZod>;
+```
+
+**1.8 Criar `src/index.ts`:**
+```typescript
+// Schema TypeScript
+export { horizon{Entity}SchemaBase } from "./schemas/horizon-{entity}-schema-base";
+
+// Types
+export type { EntitySchema, FieldSchema, UIMetadata } from "./schemas/types";
+
+// Schema Zod
+export {
+  Horizon{Entity}SchemaBaseZod,
+  Horizon{Entity}SchemaBaseZodPassthrough,
+  type Horizon{Entity}SchemaBaseType,
+} from "./schemas/horizon-{entity}-schema-base.zod";
+```
+
+**1.9 Build do pacote:**
+```bash
+cd /horizon-npm-packages/horizon-modules/{entity}/domain-data
+pnpm install
+pnpm build
+```
+
+---
+
+### Passo 2: Criar Tabela SQL
+
+**2.1 Criar `database/tables/{entity}/create.sql`:**
+```sql
+-- =============================================
+-- TABELA: {entity}
+-- =============================================
+
+CREATE TABLE IF NOT EXISTS {entity} (
+  -- Sistema
+  id SERIAL PRIMARY KEY,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+  -- Identificação (obrigatórios)
+  key VARCHAR(255) UNIQUE NOT NULL,
+  name VARCHAR(500) NOT NULL,
+  slug VARCHAR(600),
+
+  -- Campos específicos
+  -- Adicione campos aqui
+
+  -- Full-text search
+  search_tsvector TSVECTOR
+);
+
+-- Índices
+CREATE INDEX IF NOT EXISTS idx_{entity}_key ON {entity}(key);
+CREATE INDEX IF NOT EXISTS idx_{entity}_slug ON {entity}(slug);
+CREATE INDEX IF NOT EXISTS idx_{entity}_search ON {entity} USING GIN(search_tsvector);
+```
+
+**2.2 Criar `database/tables/{entity}/generated-columns.sql`:**
+```sql
+-- =============================================
+-- GENERATED COLUMNS: {entity}
+-- Full-text search e campos derivados
+-- =============================================
+
+-- Função para atualizar tsvector
+CREATE OR REPLACE FUNCTION update_{entity}_search_tsvector()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.search_tsvector :=
+    setweight(to_tsvector('portuguese', COALESCE(NEW.name, '')), 'A');
+    -- Adicione mais campos conforme necessário
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger para atualização automática
+DROP TRIGGER IF EXISTS trigger_update_{entity}_search ON {entity};
+CREATE TRIGGER trigger_update_{entity}_search
+BEFORE INSERT OR UPDATE ON {entity}
+FOR EACH ROW
+EXECUTE FUNCTION update_{entity}_search_tsvector();
+```
+
+**2.3 Criar `database/tables/{entity}/drop.sql`:**
+```sql
+-- DROP (apenas desenvolvimento)
+DROP TABLE IF EXISTS {entity} CASCADE;
+DROP FUNCTION IF EXISTS update_{entity}_search_tsvector();
+```
+
+**2.4 Executar no banco e sincronizar Prisma:**
+```bash
+# Executar SQL no banco (psql ou DBeaver)
+psql -d your_db -f database/tables/{entity}/create.sql
+psql -d your_db -f database/tables/{entity}/generated-columns.sql
+
+# Sincronizar Prisma (pull do banco)
+pnpm prisma db pull
+pnpm prisma generate
+```
+
+---
+
+### Passo 3: Criar Módulo na API
+
+**3.1 Criar estrutura de pastas:**
+```bash
+mkdir -p src/modules/{entity}/{schemas,controllers,services,mappers/computedFields,mappers/dataModifier}
+```
+
+**3.2 Criar `schemas/entity-schema.ts`:**
+```typescript
+/**
+ * Entity Schema do {Entity} - SSOT Local
+ */
+
+// Importa do NPM Package (ou define localmente)
+// import { horizon{Entity}SchemaBase } from '@horizon-domains/{entity}-model';
+
+export const {entity}EntitySchema = {
+  name: "{Entity}",
+  fields: {
+    key: { type: "string", required: true },
+    name: { type: "string", required: true },
+    slug: { type: "string", required: false },
+    // ...campos
+  },
+  // Override local se necessário
+  displayOverrides: {}
+};
+```
+
+**3.3 Criar `mappers/computedFields/index.ts`:**
+```typescript
+/**
+ * 🔄 Computed Fields do {Entity}
+ */
+import { buildSlug } from "./buildSlug";
+
+export function compute{Entity}Fields(data: any, config?: any): any {
+  const enriched = { ...data };
+
+  // 1. Gerar slug
+  if (!enriched.slug && enriched.name) {
+    enriched.slug = buildSlug(enriched);
+  }
+
+  // 2. Timestamps
+  if (!enriched.created_at) {
+    enriched.created_at = new Date();
+  }
+  enriched.updated_at = new Date();
+
+  return enriched;
+}
+```
+
+**3.4 Criar `mappers/computedFields/buildSlug.ts`:**
+```typescript
+/**
+ * Build Slug
+ */
+export function buildSlug(data: any): string {
+  if (!data.name) return data.key || "{entity}";
+
+  const baseSlug = data.name
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "") // Remove acentos
+    .replace(/[^a-z0-9]+/g, "-")     // Substitui especiais
+    .replace(/^-+|-+$/g, "")         // Remove - bordas
+    .substring(0, 50);
+
+  return data.key ? `${baseSlug}-${data.key}` : baseSlug;
+}
+```
+
+**3.5 Criar `mappers/dataModifier/index.ts`:**
+```typescript
+/**
+ * Data Modifier do {Entity}
+ * Aplica regras de negócio (passthrough por padrão)
+ */
+export function modify{Entity}Data<T extends Record<string, any>>(data: T): T {
+  // Passthrough - adicione regras conforme necessidade
+  return data;
+}
+```
+
+**3.6 Criar `services/sync.service.ts`:**
+```typescript
+import { prisma } from '@/core/prisma';
+import { modify{Entity}Data } from '../mappers/dataModifier';
+import { compute{Entity}Fields } from '../mappers/computedFields';
+
+export interface UpsertResponse {
+  inserted: number;
+  updated: number;
+  keys: string[];
+}
+
+export async function upsert{Entity}sService(
+  items: any[],
+  config?: any
+): Promise<UpsertResponse> {
+  if (!Array.isArray(items) || items.length === 0) {
+    return { inserted: 0, updated: 0, keys: [] };
+  }
+
+  const prepared: any[] = [];
+  const keys: string[] = [];
+
+  for (const item of items) {
+    const modified = modify{Entity}Data(item);
+    const enriched = compute{Entity}Fields(modified, config);
+    prepared.push(enriched);
+    keys.push(item.key);
+  }
+
+  const result = await prisma.$transaction(async (tx) => {
+    const deleteResult = await tx.{entity}.deleteMany({
+      where: { key: { in: keys } }
+    });
+
+    const insertResult = await tx.{entity}.createMany({
+      data: prepared,
+      skipDuplicates: true
+    });
+
+    return { deleted: deleteResult.count, inserted: insertResult.count };
+  });
+
+  return { inserted: result.inserted, updated: result.inserted, keys };
+}
+
+export async function delete{Entity}sService(keys: string[]): Promise<any> {
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return { deleted: 0, keys: [] };
+  }
+
+  const result = await prisma.{entity}.deleteMany({
+    where: { key: { in: keys } }
+  });
+
+  return { deleted: result.count, keys };
+}
+```
+
+**3.7 Criar Controllers e Routes:**
+
+Seguir o mesmo padrão dos módulos existentes (property, broker).
+Exportar handlers nos arquivos route.ts.
+
+---
+
+### Passo 4: Testar Endpoints
+
+```bash
+# 1. Inserir dados (Sync)
+curl -X PUT http://localhost:3000/api/{entity}/sync \
+  -H "Content-Type: application/json" \
+  -d '{ "{entity}s": [{ "key": "test-001", "name": "Test" }] }'
+
+# 2. Buscar por critério (Find)
+curl -X POST http://localhost:3000/api/{entity}/find \
+  -H "Content-Type: application/json" \
+  -d '{ "criteria": { "key": "test-001" } }'
+
+# 3. Busca avançada (Search)
+curl -X POST http://localhost:3000/api/{entity}/search \
+  -H "Content-Type: application/json" \
+  -d '{ "list": { "page": 1, "limit": 10 } }'
+
+# 4. Deletar (Sync DELETE)
+curl -X DELETE http://localhost:3000/api/{entity}/sync \
+  -H "Content-Type: application/json" \
+  -d '{ "keys": ["test-001"] }'
+```
+
+---
+
+## 📌 Checklist de Validação
+
+### NPM Package
+- [ ] `package.json` com nome `@horizon-domains/{entity}-model`
+- [ ] Schema TypeScript criado (`horizon-{entity}-schema-base.ts`)
+- [ ] Schema Zod criado (`horizon-{entity}-schema-base.zod.ts`)
+- [ ] `src/index.ts` exportando tudo
+- [ ] Build funciona (`pnpm build`)
+
+### Database
+- [ ] `create.sql` com tabela e índices
+- [ ] `generated-columns.sql` com FTS tsvector
+- [ ] SQL executado no banco
+- [ ] Prisma sincronizado (`prisma db pull && prisma generate`)
+
+### API Module
+- [ ] Estrutura de pastas criada (`schemas/`, `controllers/`, `services/`, `mappers/`)
+- [ ] `entity-schema.ts` criado
+- [ ] `computedFields/` com `index.ts` e `buildSlug.ts`
+- [ ] `dataModifier/index.ts` criado (passthrough)
+- [ ] Services implementados (`sync`, `find`, `search`)
+- [ ] Controllers implementados com validação Zod
+- [ ] Routes configuradas em `/app/api/{entity}/`
+
+### Testes
+- [ ] PUT sync funciona (inserir)
+- [ ] POST find funciona (buscar)
+- [ ] POST search funciona (listar)
+- [ ] DELETE sync funciona (deletar)
+- [ ] Slug é gerado automaticamente
+
+---
+
+## Arquitetura WEB - Estrutura de Módulos no Frontend
+
+Um módulo no frontend (`/apps/web/src/modules/{entity}/`) segue estrutura padronizada:
+
+### **Estrutura Completa WEB**
+
+```
+apps/web/src/modules/{entity}/
+├── core/                              # Lógica core do módulo
+│   ├── module.config.ts               # Configuração do módulo
+│   ├── item/                          # Tudo relacionado a UM item
+│   │   ├── index.ts                   # Exports
+│   │   ├── {entity}-url-builder.ts    # Builder de URLs
+│   │   ├── enrichMapper.ts            # Mapper para enriquecer dados
+│   │   ├── schemas/                   # Schemas do item
+│   │   │   ├── index.ts               # Exports dos schemas
+│   │   │   ├── schema.ts              # Schema TypeScript (SSOT)
+│   │   │   ├── schema.generated.json  # Schema gerado da API
+│   │   │   ├── base-schema.json       # Schema base (campos)
+│   │   │   ├── display-layer-schema.json  # Overrides de UI
+│   │   │   └── computed-schema.json   # Campos computados
+│   │   └── computed-fields/           # Campos computados runtime
+│   │       ├── index.ts
+│   │       ├── {entity}-url.ts        # Gerador de URL
+│   │       └── assembleComputedData.ts
+│   ├── list/                          # Tudo relacionado a LISTA (se houver)
+│   │   └── ...
+│   ├── libs/                          # Bibliotecas específicas (se houver)
+│   │   └── ...
+│   └── services/                      # Services do módulo
+│       └── {Entity}Service.ts
+│
+└── features/                          # Features/páginas do módulo
+    ├── item-display/                  # Página individual
+    │   └── page-display/
+    │       ├── components/
+    │       └── data/
+    └── search-list/                   # Listagem com busca (se houver)
+        ├── components/
+        ├── config/
+        └── hooks/
+```
+
+### **Arquivos Obrigatórios por Módulo**
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `core/item/index.ts` | Exportações do item |
+| `core/item/schemas/index.ts` | Exportações dos schemas |
+| `core/item/schemas/schema.ts` | Schema TypeScript |
+| `core/item/schemas/schema.generated.json` | Schema da API |
+| `core/item/enrichMapper.ts` | Mapper de enriquecimento |
+| `core/item/{entity}-url-builder.ts` | Construtor de URLs |
+
+### **Comparação Property vs Broker**
+
+| Aspecto | Property (Completo) | Broker (Simplificado) |
+|---------|---------------------|----------------------|
+| `core/item/schemas/` | Completo | Completo |
+| `core/item/computed-fields/` | Sim | Sim |
+| `core/libs/` | 7 módulos | Não precisa |
+| `core/list/` | Sim | Não precisa |
+| `features/search-list/` | 20+ componentes | Fora do escopo |
+
+---
+
+## Referências
+
+| Módulo | Descrição | Complexidade |
+|--------|-----------|--------------|
+| **Property** | Módulo completo de imóveis | Alta (com CRM, rules, computed) |
+| **Broker** | Módulo simplificado de corretores | Baixa (passthrough) |
+
+Use o **Broker** como template para módulos simples.
+Use o **Property** como referência para módulos complexos.
+
+---
+
+## Convenções
+
+| Elemento | Convenção | Exemplo |
+|----------|-----------|---------|
+| Types/Interfaces | PascalCase | `BrokerEntity` |
+| Funções | camelCase | `findBrokerService` |
+| Arquivos | kebab-case | `entity-schema.ts` |
+| Tabelas SQL | snake_case | `broker` |
+| NPM Package | kebab-case | `@horizon-domains/broker-model` |
+| Pastas | kebab-case | `computed-fields/` ou `computedFields/` |