gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/02-modules.md

@@ -0,0 +1,285 @@
+# Sistema de Modulos
+
+Los modulos definen la estructura de datos en Gufi. Son JSON que se convierten automaticamente en tablas PostgreSQL.
+
+## Estructura de un modulo
+
+```json
+{
+  "name": "ventas",
+  "displayName": "Ventas",
+  "icon": "ShoppingCart",
+  "submodules": [
+    {
+      "name": "pedidos",
+      "label": "Pedidos",
+      "entities": [
+        {
+          "id": 16192,
+          "name": "pedidos",
+          "label": "Pedidos",
+          "kind": "table",
+          "fields": [
+            { "name": "cliente", "type": "relation", "label": "Cliente", "required": true, "relation": { "module": "crm", "entity": "clientes" } },
+            { "name": "fecha", "type": "date", "label": "Fecha", "required": true },
+            { "name": "total", "type": "currency", "label": "Total", "currency": "EUR" },
+            { "name": "estado", "type": "select", "label": "Estado", "options": [
+              { "value": "pendiente", "label": "Pendiente", "color": "yellow" },
+              { "value": "enviado", "label": "Enviado", "color": "blue" },
+              { "value": "entregado", "label": "Entregado", "color": "green" }
+            ]}
+          ],
+          "permissions": {
+            "admin": "*",
+            "ventas": ["entity:view", "entity:create", "entity:update"]
+          },
+          "automations": [
+            { "trigger": "insert", "function_name": "notificar_pedido" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Tabla fisica resultante
+
+El modulo anterior crea la tabla `m{moduleId}_t16192`:
+
+```sql
+CREATE TABLE company_116.m360_t16192 (
+  id SERIAL PRIMARY KEY,
+  created_at TIMESTAMP DEFAULT NOW(),
+  cliente INTEGER REFERENCES m308_t4136(id),
+  cliente__display TEXT,  -- Cache del nombre
+  fecha DATE NOT NULL,
+  total NUMERIC,
+  estado TEXT,
+  estado__display TEXT    -- Cache del label
+);
+```
+
+## Campos __display
+
+Para campos `relation` y `select`, Gufi mantiene un campo `__display` con el valor legible:
+
+```
+cliente = 123           --> cliente__display = "Empresa ABC"
+estado = "pendiente"    --> estado__display = "Pendiente"
+```
+
+**Al actualizar, actualiza AMBOS:**
+```javascript
+gufi_data({
+  action: "update",
+  table: "ventas.pedidos",
+  company_id: "116",
+  id: 5,
+  data: {
+    estado: "enviado",
+    estado__display: "Enviado"
+  }
+})
+```
+
+## Tipos de entidades (kind)
+
+| Kind | Descripcion | UI |
+|------|-------------|-----|
+| `table` | Tabla normal con CRUD | GenericTable |
+| `dashboard` | Dashboard de KPIs | DashboardView |
+| `config` | Configuracion (1 registro) | FormView |
+| `marketplace_view` | Vista del marketplace | MarketplaceView |
+| `custom` | Vista custom hardcoded | Plugin especifico |
+
+## Operaciones con MCP
+
+### Ver contexto completo de una empresa
+
+```
+gufi_context({ company_id: "116" })
+```
+
+Devuelve: modulos, entidades, campos, relaciones, automations.
+
+### Agregar un campo
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  operations: [{
+    op: "add_field",
+    entity: "ventas.pedidos",  // modulo.entidad
+    field: {
+      name: "fecha_entrega",
+      type: "date",
+      label: "Fecha de Entrega",
+      required: false
+    }
+  }]
+})
+```
+
+### Modificar un campo
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  operations: [{
+    op: "update_field",
+    entity: "ventas.pedidos",
+    field_name: "fecha_entrega",
+    changes: { required: true, label: "Fecha Entrega (requerida)" }
+  }]
+})
+```
+
+### Crear entidad nueva
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  operations: [{
+    op: "add_entity",
+    module: "inventario",
+    entity: {
+      name: "productos",
+      label: "Productos",
+      kind: "table",
+      fields: [
+        { name: "nombre", type: "text", label: "Nombre", required: true },
+        { name: "sku", type: "barcode", label: "SKU" },
+        { name: "precio", type: "currency", label: "Precio" },
+        { name: "stock", type: "number_int", label: "Stock" }
+      ]
+    }
+  }]
+})
+```
+
+### Crear Custom View (marketplace_view)
+
+Las Custom Views son entidades de tipo `marketplace_view`. Se crean igual que cualquier entidad:
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  operations: [{
+    op: "add_entity",
+    module: "ventas",
+    entity: {
+      name: "dashboard_ventas",
+      label: "Dashboard de Ventas",
+      kind: "marketplace_view"  // <-- Esto crea una Custom View
+    }
+  }]
+})
+```
+
+Despues de crear la vista:
+1. Usa `gufi_view_pull({ view_id: <id> })` para descargar el template
+2. Edita los archivos locales
+3. Usa `gufi_view_push({ view_id: <id> })` para subir cambios
+```
+
+### Preview (dry run)
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  preview: true,  // No ejecuta, solo muestra que haria
+  operations: [...]
+})
+```
+
+### Multiples operaciones
+
+```javascript
+gufi_schema_modify({
+  company_id: "116",
+  operations: [
+    { op: "add_field", entity: "ventas.pedidos", field: { name: "urgente", type: "boolean", label: "Urgente" } },
+    { op: "add_field", entity: "ventas.pedidos", field: { name: "notas", type: "text", label: "Notas" } },
+    { op: "update_field", entity: "ventas.pedidos", field_name: "estado", changes: { required: true } }
+  ]
+})
+```
+
+## Relaciones
+
+### relation (FK)
+
+```json
+{
+  "name": "cliente",
+  "type": "relation",
+  "label": "Cliente",
+  "relation": {
+    "module": "crm",
+    "entity": "clientes",
+    "displayField": "nombre"
+  }
+}
+```
+
+### reversed_relation (virtual)
+
+No crea columna. Muestra registros que apuntan a este:
+
+```json
+{
+  "name": "pedidos",
+  "type": "reversed_relation",
+  "label": "Pedidos",
+  "reversedRelation": {
+    "module": "ventas",
+    "entity": "pedidos",
+    "field": "cliente"
+  }
+}
+```
+
+## Permisos por entidad
+
+```json
+{
+  "permissions": {
+    "admin": "*",
+    "manager": ["entity:view", "entity:create", "entity:update", "entity:delete"],
+    "sales": ["entity:view", "entity:create"],
+    "viewer": ["entity:view"]
+  }
+}
+```
+
+**Permisos disponibles:**
+- `entity:view` - Ver registros
+- `entity:create` - Crear registros
+- `entity:update` - Editar registros
+- `entity:delete` - Eliminar registros
+- `entity:import` - Importar desde Excel
+- `entity:export` - Exportar a Excel/PDF
+
+## Migraciones automaticas
+
+Cuando modificas un modulo, Gufi automaticamente:
+
+1. **Campos nuevos**: `ALTER TABLE ADD COLUMN`
+2. **Campos eliminados**: Marca como deprecated (no elimina datos)
+3. **Tipos cambiados**: Intenta cast, si falla mantiene el anterior
+4. **Relaciones nuevas**: Crea FK + indice
+
+NO se hace automaticamente:
+- Eliminar columnas con datos
+- Cambiar tipos incompatibles
+- Renombrar campos (crea nuevo)
+
+## Iconos disponibles
+
+Los iconos son de Lucide React. Comunes:
+- `ShoppingCart`, `Package`, `Users`, `Building`
+- `FileText`, `Calendar`, `Settings`, `BarChart`
+- `Truck`, `MapPin`, `Phone`, `Mail`
+
+Ver catalogo completo: https://lucide.dev/icons/

package/docs/mcp/03-fields.md

@@ -0,0 +1,357 @@
+# Tipos de Campos y CB Builders
+
+Referencia completa de tipos de campo en Gufi. **Fuente de verdad**: `@gufi/column-types`
+
+## IMPORTANTE: Usar CB.* siempre
+
+En vistas React, **SIEMPRE** usar `gufi.CB.*` para crear/actualizar datos:
+
+```typescript
+await gufi.dataProvider.create({
+  resource: tableId,
+  variables: {
+    nombre: gufi.CB.text('Mi Producto'),
+    precio: gufi.CB.currency(150),
+    telefono: gufi.CB.phone('612345678'),
+  }
+});
+```
+
+## Tipos de Campo
+
+### Texto
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `text` | TEXT | `"string"` | `CB.text('value')` |
+| `email` | TEXT[] | `["user@example.com"]` | `CB.email('user@example.com')` |
+| `url` | TEXT | `"https://..."` | `CB.url('https://...')` |
+| `barcode` | TEXT | `"8414533043847"` | `CB.barcode(8414533043847)` |
+
+**Notas:**
+- `email` es un ARRAY de textos (TEXT[]), soporta múltiples emails
+- `email` se normaliza a minúsculas automáticamente
+- `barcode` acepta números (se convierte a string)
+
+**Email - Formatos válidos:**
+```javascript
+// Un solo email (se convierte a array)
+CB.email('user@example.com')    // → ['user@example.com']
+
+// Múltiples emails (separados por coma)
+CB.email('a@x.com, b@x.com')    // → ['a@x.com', 'b@x.com']
+
+// Array directo
+CB.email(['a@x.com', 'b@x.com']) // → ['a@x.com', 'b@x.com']
+```
+
+### Numeros
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `number` | NUMERIC | `123.45` | `CB.number(123.45)` |
+| `number_int` | INTEGER | `42` | `CB.int(42)` |
+| `number_float` | DOUBLE | `3.14159` | `CB.float(3.14)` |
+| `percentage` | DOUBLE | `0.75` (= 75%) | `CB.percentage(75)` |
+
+**Notas:**
+- `number_int` redondea automaticamente
+- `percentage` se guarda como decimal (0.75), se muestra como 75%
+
+### Fecha/Hora
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `date` | TIMESTAMP | `"2024-01-15T00:00:00.000Z"` | `CB.date()` |
+| `time` | TIME | `"14:30:00"` | `CB.time('14:30')` |
+
+**Solo existe `date` (siempre TIMESTAMP):**
+```javascript
+CB.date()                      // Hoy medianoche: '2024-01-15T00:00:00.000Z'
+CB.date('2024-06-15')          // '2024-06-15T00:00:00.000Z'
+CB.date('2024-06-15T14:30:00') // '2024-06-15T14:30:00.000Z' (preserva hora)
+CB.date(new Date())            // ISO completo del Date object
+```
+
+**Display controlado por `includeTime` en schema:**
+```json
+{ "name": "fecha_nacimiento", "type": "date" }
+{ "name": "fecha_entrega", "type": "date", "includeTime": true }
+```
+
+**`created_at`:** Campo sistema automatico, siempre muestra hora.
+
+### Seleccion
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `select` | TEXT | `"value"` | `CB.select('value')` |
+| `multiselect` | TEXT[] | `["a", "b"]` | `CB.multiselect('a', 'b')` |
+| `boolean` | BOOLEAN | `true/false` | `CB.bool(true)` |
+
+**Opciones en schema:**
+```json
+{
+  "name": "estado",
+  "type": "select",
+  "options": [
+    { "value": "pendiente", "label": "Pendiente", "color": "yellow" },
+    { "value": "activo", "label": "Activo", "color": "green" }
+  ]
+}
+```
+
+### Relaciones
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `relation` | INTEGER | `123` (FK ID) | `CB.relation(123)` |
+| `users` | INTEGER[] | `[16, 23]` | `CB.users(16, 23)` |
+| `reversed_relation` | - | (virtual, read-only) | - |
+
+**Notas:**
+- `relation` es una FK a otra tabla
+- `users` es array de IDs de usuarios (para asignar tareas, etc.)
+- `reversed_relation` no tiene columna, es calculado
+
+### Currency (NUMERICO)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `currency` | NUMERIC | `150.00` | `CB.currency(150)` |
+
+**IMPORTANTE:** Currency es un numero simple. El codigo de moneda va en el schema del campo:
+
+```json
+{
+  "name": "precio",
+  "type": "currency",
+  "currency": "EUR"
+}
+```
+
+**NO es JSONB, es NUMERIC:**
+```javascript
+// CORRECTO
+precio: 150.00
+
+// INCORRECTO (formato legacy)
+precio: { currency: 'EUR', amount: 150.00 }
+```
+
+### Phone (JSONB)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `phone` | JSONB | `{ prefix, number }` | `CB.phone('612345678')` |
+
+**Formato:**
+```javascript
+{
+  prefix: "+34",      // Codigo de pais
+  number: "612345678" // Numero sin prefijo
+}
+```
+
+**CB.phone detecta pais:**
+```javascript
+CB.phone('612345678')         // { prefix: '+34', number: '612345678' }
+CB.phone('+1 555 123 4567')   // { prefix: '+1', number: '5551234567' }
+CB.phone('612345678', '+44')  // { prefix: '+44', number: '612345678' }
+```
+
+### Location (JSONB)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `location` | JSONB | `{ street, city, ... }` | `CB.location({...})` |
+
+**Formato completo:**
+```javascript
+{
+  lat: 40.4168,           // Latitud
+  lng: -3.7038,           // Longitud
+  country: "ES",          // ISO 3166-1 alpha-2
+  city: "Madrid",
+  street: "Calle Mayor",
+  number: "15",
+  postal_code: "28013",
+  floor: "3",
+  letter: "B",
+  notes: "Puerta azul",
+  place_id: "...",        // Google/OSM ID
+  timezone: "Europe/Madrid"
+}
+```
+
+**Minimo requerido:**
+```javascript
+CB.location({ street: 'Mayor', number: '15', city: 'Madrid' })
+```
+
+### File (JSONB Array)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `file` | JSONB | Array de archivos | `CB.file(url, name)` |
+
+**Dos formatos validos:**
+
+```javascript
+// Simple (solo path)
+["company_130/uuid_photo.jpg"]
+
+// Completo (con metadata)
+[{
+  url: "company_130/abc123_dni.pdf",
+  name: "dni_12345.pdf",
+  mime: "application/pdf",
+  size: 245678
+}]
+```
+
+**IMPORTANTE:** Los archivos deben subirse primero a GCS:
+```javascript
+// 1. Subir archivo
+const formData = new FormData();
+formData.append('file', file);
+const { url, name } = await fetch('/api/files/upload', { method: 'POST', body: formData }).then(r => r.json());
+
+// 2. Guardar referencia
+fotos: CB.file(url, name)
+```
+
+**NO guardar base64 en campos file.**
+
+### Signature (TEXT base64)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `signature` | TEXT | `"data:image/png;base64,..."` | `CB.signature(dataUrl)` |
+
+**Unico tipo que acepta base64 directamente** (firmas son pequenas).
+
+### JSON (JSONB)
+
+| Tipo | PostgreSQL | Formato | CB Builder |
+|------|------------|---------|------------|
+| `json` | JSONB | Cualquier objeto | `CB.json({...})` |
+
+Para datos estructurados sin tipo especifico.
+
+## Ejemplo completo de create
+
+```typescript
+// 💜 Nombre lógico - dataProvider lo resuelve automáticamente
+const productosTable = 'ventas.productos';
+
+await gufi.dataProvider.create({
+  resource: productosTable,
+  variables: {
+    // Texto
+    nombre: gufi.CB.text('Mi Producto'),
+    email_contacto: gufi.CB.email('contacto@empresa.com'),
+    codigo_barras: gufi.CB.barcode('8414533043847'),
+
+    // Numeros
+    cantidad: gufi.CB.int(100),
+    peso: gufi.CB.float(2.5),
+    descuento: gufi.CB.percentage(15),  // 0.15
+
+    // Currency
+    precio: gufi.CB.currency(150),      // 150.00
+
+    // Fecha/Hora (siempre TIMESTAMP)
+    fecha_alta: gufi.CB.date(),         // Hoy a medianoche UTC
+    fecha_evento: gufi.CB.date('2024-06-15'),  // Fecha especifica
+
+    // Seleccion
+    estado: gufi.CB.select('activo'),
+    categorias: gufi.CB.multiselect('electronica', 'hogar'),
+    activo: gufi.CB.bool(true),
+
+    // Relaciones
+    proveedor_id: gufi.CB.relation(45),
+    responsables: gufi.CB.users(16, 23),
+
+    // Complejos
+    telefono: gufi.CB.phone('612345678'),
+    direccion: gufi.CB.location({
+      street: 'Gran Via',
+      number: '1',
+      city: 'Madrid'
+    }),
+  }
+});
+```
+
+## Ejemplo completo de update
+
+```typescript
+// 💜 Nombre lógico
+const productosTable = 'ventas.productos';
+
+// IMPORTANTE: Para select/relation, actualizar AMBOS campos
+await gufi.dataProvider.update({
+  resource: productosTable,
+  id: recordId,
+  variables: {
+    estado: gufi.CB.select('enviado'),
+    estado__display: 'Enviado',
+
+    cliente_id: gufi.CB.relation(newClientId),
+    cliente_id__display: 'Nuevo Cliente SA',
+
+    precio: gufi.CB.currency(200),
+  }
+});
+```
+
+## Errores comunes
+
+### 1. Currency como objeto
+```javascript
+// INCORRECTO
+precio: { currency: 'EUR', amount: 150 }
+
+// CORRECTO
+precio: gufi.CB.currency(150)  // Solo el numero
+```
+
+### 2. Phone con formato incorrecto
+```javascript
+// INCORRECTO
+telefono: { country: 'ES', number: '612345678' }
+
+// CORRECTO
+telefono: gufi.CB.phone('612345678')  // { prefix: '+34', number: '612345678' }
+```
+
+### 3. Olvidar __display en updates
+```javascript
+// INCORRECTO (UI no se actualiza)
+estado: 'enviado'
+
+// CORRECTO
+estado: 'enviado',
+estado__display: 'Enviado'
+```
+
+### 4. Base64 en campos file
+```javascript
+// INCORRECTO
+foto: 'data:image/png;base64,...'
+
+// CORRECTO (subir primero)
+const { url, name } = await uploadFile(file);
+foto: gufi.CB.file(url, name)
+```
+
+### 5. Email como string plano
+```javascript
+// FUNCIONA pero no recomendado
+email: 'user@example.com'
+
+// CORRECTO (usa CB para normalización)
+email: gufi.CB.email('user@example.com')  // → ['user@example.com']
+```