gufi-cli 0.1.1 → 0.1.3

package/CLAUDE.md

@@ -0,0 +1,1491 @@
+# Gufi CLI - Documentación Completa para Claude
+
+## ¿Qué es Gufi?
+
+Gufi es un **ERP multi-tenant** donde cada empresa (company) tiene su propia base de datos aislada. Los consultores pueden crear módulos personalizados sin programar - solo definiendo JSONs que describen la estructura de datos.
+
+**Filosofía**: "Simple · Professional · Elegance" - El Apple de los ERPs
+
+### Arquitectura General
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         GUFI ERP                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Company 116 (Fitvending)     Company 146 (Gufi)              │
+│   ├── Schema: company_116      ├── Schema: company_146         │
+│   ├── Módulo: Nayax (308)      ├── Módulo: Tareas (360)        │
+│   │   └── Tablas: m308_t4136   │   └── Tablas: m360_t16192     │
+│   └── Módulo: Stock (310)      └── Módulo: Incidencias (361)   │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│   core.modules        → Definiciones JSON de módulos            │
+│   core.entities       → Metadatos de cada tabla                 │
+│   core.automation_scripts → Código JavaScript de automations    │
+│   core.automation_meta    → Vincula scripts a triggers          │
+├─────────────────────────────────────────────────────────────────┤
+│   marketplace.packages    → Paquetes publicados                 │
+│   marketplace.views       → Vistas React/TypeScript             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Nomenclatura de Tablas
+
+Las tablas físicas en PostgreSQL siguen el patrón:
+```
+m{moduleId}_t{entityId}
+```
+
+Ejemplo:
+- Módulo "Tareas" tiene ID 360
+- Entidad "asignaciones" tiene ID 16192
+- Tabla física: `m360_t16192` en schema `company_146`
+
+---
+
+## Estructura de un Módulo (JSON)
+
+Un módulo es un JSON que define **toda la estructura de datos** de una funcionalidad. Gufi lee este JSON y automáticamente:
+1. Crea las tablas en PostgreSQL
+2. Genera la UI (formularios, listas, filtros)
+3. Configura permisos
+4. Vincula relaciones entre tablas
+
+### JSON Completo de Ejemplo
+
+```json
+{
+  "name": "ventas",
+  "displayName": "Gestión de Ventas",
+  "icon": "ShoppingCart",
+  "submodules": [
+    {
+      "name": "maestros",
+      "label": "Datos Maestros",
+      "icon": "Database",
+      "entities": [
+        {
+          "kind": "table",
+          "name": "clientes",
+          "label": "Clientes",
+          "fields": [
+            {
+              "name": "nombre",
+              "type": "text",
+              "label": "Nombre",
+              "required": true,
+              "searchable": true
+            },
+            {
+              "name": "email",
+              "type": "email",
+              "label": "Email",
+              "unique": true
+            },
+            {
+              "name": "telefono",
+              "type": "phone",
+              "label": "Teléfono"
+            },
+            {
+              "name": "tipo",
+              "type": "select",
+              "label": "Tipo de Cliente",
+              "options": [
+                { "value": "particular", "label": "Particular" },
+                { "value": "empresa", "label": "Empresa" },
+                { "value": "vip", "label": "VIP" }
+              ],
+              "default": "particular"
+            },
+            {
+              "name": "limite_credito",
+              "type": "currency",
+              "label": "Límite de Crédito",
+              "currency": "EUR"
+            },
+            {
+              "name": "activo",
+              "type": "boolean",
+              "label": "Activo",
+              "default": true
+            },
+            {
+              "name": "notas",
+              "type": "textarea",
+              "label": "Notas"
+            },
+            {
+              "name": "comercial_id",
+              "type": "users",
+              "label": "Comercial Asignado"
+            }
+          ],
+          "permissions": {
+            "Admin": "*",
+            "Comercial": "crud",
+            "User": "read"
+          },
+          "ui": {
+            "defaultSort": { "field": "nombre", "order": "ASC" },
+            "searchFields": ["nombre", "email"],
+            "listFields": ["nombre", "tipo", "comercial_id", "activo"]
+          }
+        },
+        {
+          "kind": "table",
+          "name": "productos",
+          "label": "Productos",
+          "fields": [
+            {
+              "name": "codigo",
+              "type": "text",
+              "label": "Código",
+              "required": true,
+              "unique": true
+            },
+            {
+              "name": "nombre",
+              "type": "text",
+              "label": "Nombre",
+              "required": true
+            },
+            {
+              "name": "precio",
+              "type": "currency",
+              "label": "Precio",
+              "currency": "EUR",
+              "required": true
+            },
+            {
+              "name": "stock",
+              "type": "number",
+              "label": "Stock",
+              "default": 0,
+              "min": 0
+            },
+            {
+              "name": "categoria",
+              "type": "multiselect",
+              "label": "Categorías",
+              "options": [
+                { "value": "electronica", "label": "Electrónica" },
+                { "value": "ropa", "label": "Ropa" },
+                { "value": "hogar", "label": "Hogar" }
+              ]
+            },
+            {
+              "name": "imagen",
+              "type": "image",
+              "label": "Imagen"
+            }
+          ],
+          "permissions": {
+            "Admin": "*",
+            "User": "read"
+          }
+        }
+      ]
+    },
+    {
+      "name": "operaciones",
+      "label": "Operaciones",
+      "icon": "FileText",
+      "entities": [
+        {
+          "kind": "table",
+          "name": "pedidos",
+          "label": "Pedidos",
+          "fields": [
+            {
+              "name": "numero",
+              "type": "text",
+              "label": "Nº Pedido",
+              "required": true,
+              "unique": true,
+              "autoGenerate": "PED-{YYYY}{MM}-{SEQ:5}"
+            },
+            {
+              "name": "cliente_id",
+              "type": "relation",
+              "label": "Cliente",
+              "ref": "clientes",
+              "display": "nombre",
+              "required": true
+            },
+            {
+              "name": "fecha",
+              "type": "date",
+              "label": "Fecha",
+              "default": "today"
+            },
+            {
+              "name": "estado",
+              "type": "select",
+              "label": "Estado",
+              "options": [
+                { "value": "borrador", "label": "Borrador", "color": "gray" },
+                { "value": "confirmado", "label": "Confirmado", "color": "blue" },
+                { "value": "enviado", "label": "Enviado", "color": "yellow" },
+                { "value": "entregado", "label": "Entregado", "color": "green" },
+                { "value": "cancelado", "label": "Cancelado", "color": "red" }
+              ],
+              "default": "borrador"
+            },
+            {
+              "name": "total",
+              "type": "currency",
+              "label": "Total",
+              "currency": "EUR",
+              "computed": true
+            },
+            {
+              "name": "responsable_id",
+              "type": "users",
+              "label": "Responsable"
+            },
+            {
+              "name": "observaciones",
+              "type": "textarea",
+              "label": "Observaciones"
+            }
+          ],
+          "permissions": {
+            "Admin": "*",
+            "Comercial": "crud",
+            "User": "read"
+          },
+          "automations": [
+            {
+              "trigger": "on_insert",
+              "function_name": "notificar_nuevo_pedido"
+            },
+            {
+              "trigger": "on_update",
+              "condition": "estado = 'confirmado'",
+              "function_name": "procesar_pedido"
+            },
+            {
+              "trigger": "click",
+              "function_name": "generar_factura",
+              "label": "Generar Factura",
+              "icon": "FileText",
+              "showWhen": "estado = 'entregado'"
+            }
+          ]
+        },
+        {
+          "kind": "table",
+          "name": "lineas_pedido",
+          "label": "Líneas de Pedido",
+          "fields": [
+            {
+              "name": "pedido_id",
+              "type": "relation",
+              "label": "Pedido",
+              "ref": "pedidos",
+              "required": true,
+              "cascade": true
+            },
+            {
+              "name": "producto_id",
+              "type": "relation",
+              "label": "Producto",
+              "ref": "productos",
+              "display": "nombre",
+              "required": true
+            },
+            {
+              "name": "cantidad",
+              "type": "number",
+              "label": "Cantidad",
+              "required": true,
+              "min": 1,
+              "default": 1
+            },
+            {
+              "name": "precio_unitario",
+              "type": "currency",
+              "label": "Precio Unit.",
+              "currency": "EUR"
+            },
+            {
+              "name": "subtotal",
+              "type": "currency",
+              "label": "Subtotal",
+              "currency": "EUR",
+              "computed": "cantidad * precio_unitario"
+            }
+          ],
+          "permissions": {
+            "Admin": "*",
+            "Comercial": "crud"
+          },
+          "ui": {
+            "inline": true,
+            "parentField": "pedido_id"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Tipos de Campos Disponibles
+
+| Tipo | PostgreSQL | Descripción | Opciones |
+|------|------------|-------------|----------|
+| `text` | VARCHAR(255) | Texto corto | `maxLength`, `minLength`, `pattern` |
+| `textarea` | TEXT | Texto largo | `rows`, `maxLength` |
+| `number` | NUMERIC | Número | `min`, `max`, `decimals`, `step` |
+| `currency` | NUMERIC(15,2) | Dinero | `currency` (EUR, USD, etc.) |
+| `date` | DATE | Fecha | `min`, `max`, `default: "today"` |
+| `datetime` | TIMESTAMP | Fecha y hora | `min`, `max` |
+| `time` | TIME | Solo hora | - |
+| `select` | VARCHAR | Selector único | `options: [{value, label, color}]` |
+| `multiselect` | TEXT[] | Selector múltiple | `options: [{value, label}]` |
+| `relation` | INTEGER (FK) | Relación a otra tabla | `ref`, `display`, `cascade` |
+| `users` | INTEGER/INT[] | Usuario(s) del sistema | `multiple: true` |
+| `boolean` | BOOLEAN | Sí/No | `default` |
+| `email` | VARCHAR | Email validado | - |
+| `phone` | VARCHAR | Teléfono | `format` |
+| `url` | VARCHAR | URL | - |
+| `image` | TEXT | URL de imagen (GCS) | `maxSize`, `allowedTypes` |
+| `file` | TEXT | URL de archivo (GCS) | `maxSize`, `allowedTypes` |
+| `json` | JSONB | Objeto JSON | `schema` |
+| `color` | VARCHAR(7) | Color hex | - |
+| `rating` | SMALLINT | Puntuación 1-5 | `max` |
+| `percentage` | NUMERIC | Porcentaje | `min`, `max` |
+
+### Opciones de Campo
+
+```json
+{
+  "name": "campo",
+  "type": "text",
+  "label": "Etiqueta visible",
+  "required": true,           // Campo obligatorio
+  "unique": true,             // Valor único en la tabla
+  "default": "valor",         // Valor por defecto
+  "searchable": true,         // Incluir en búsqueda global
+  "hidden": false,            // Ocultar en UI
+  "readonly": false,          // Solo lectura
+  "computed": "expr",         // Calculado (no editable)
+  "autoGenerate": "pattern",  // Auto-generar valor
+  "validation": {             // Validaciones custom
+    "pattern": "^[A-Z]{3}",
+    "message": "Debe ser 3 letras mayúsculas"
+  }
+}
+```
+
+### Permisos por Rol
+
+```json
+"permissions": {
+  "Admin": "*",           // Todos los permisos
+  "Manager": "crud",      // Create, Read, Update, Delete
+  "User": "cru",          // Create, Read, Update (no delete)
+  "Viewer": "read",       // Solo lectura
+  "Guest": ""             // Sin acceso
+}
+```
+
+---
+
+## Automations (Código JavaScript)
+
+Las automations son **funciones JavaScript** almacenadas en la base de datos que se ejecutan en respuesta a eventos.
+
+### Dónde se almacenan
+
+```sql
+-- El código está en:
+SELECT function_name, js_code FROM core.automation_scripts WHERE company_id = 116;
+
+-- Los triggers están en:
+SELECT * FROM core.automation_meta WHERE company_id = 116;
+```
+
+### Tipos de Triggers
+
+| Trigger | Cuándo se ejecuta |
+|---------|-------------------|
+| `on_insert` | Al crear un registro |
+| `on_update` | Al modificar un registro |
+| `on_delete` | Al eliminar un registro |
+| `click` | Botón manual en la UI |
+| `scheduled` | Cron job (ej: "0 9 * * *") |
+
+### Estructura de una Automation
+
+```javascript
+/**
+ * Función: procesar_pedido
+ * Trigger: on_update cuando estado = 'confirmado'
+ *
+ * @param {Object} context - Contexto de ejecución
+ * @param {Object} api - API para interactuar con el sistema
+ * @param {Object} logger - Logger para debugging
+ */
+async function procesar_pedido(context, api, logger) {
+  // ═══════════════════════════════════════════════════════════
+  // CONTEXT - Información del evento
+  // ═══════════════════════════════════════════════════════════
+  const {
+    company_id,      // ID de la company (ej: 116)
+    module_id,       // ID del módulo (ej: 308)
+    entity_id,       // ID de la entidad/tabla (ej: 4136)
+    table,           // Nombre físico de tabla (ej: "m308_t4136")
+    row,             // Registro actual (después del cambio)
+    old_row,         // Registro anterior (solo en on_update)
+    input,           // Input del usuario (solo en click)
+    env,             // Variables de entorno de la company
+    user             // Usuario que disparó el evento
+  } = context;
+
+  logger.info('Procesando pedido', { pedido_id: row.id, estado: row.estado });
+
+  // ═══════════════════════════════════════════════════════════
+  // API.QUERY - Consultas SQL
+  // ═══════════════════════════════════════════════════════════
+
+  // Obtener líneas del pedido
+  const { rows: lineas } = await api.query(
+    `SELECT lp.*, p.nombre as producto_nombre, p.stock
+     FROM ${context.schema}.m308_t4137 lp  -- lineas_pedido
+     JOIN ${context.schema}.m308_t4138 p ON p.id = lp.producto_id
+     WHERE lp.pedido_id = $1`,
+    [row.id]
+  );
+
+  // Actualizar stock de productos
+  for (const linea of lineas) {
+    await api.query(
+      `UPDATE ${context.schema}.m308_t4138
+       SET stock = stock - $1
+       WHERE id = $2`,
+      [linea.cantidad, linea.producto_id]
+    );
+
+    logger.debug('Stock actualizado', {
+      producto: linea.producto_nombre,
+      cantidad: linea.cantidad
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // API.EMAIL - Enviar emails
+  // ═══════════════════════════════════════════════════════════
+
+  // Obtener datos del cliente
+  const { rows: [cliente] } = await api.query(
+    `SELECT * FROM ${context.schema}.m308_t4135 WHERE id = $1`,
+    [row.cliente_id]
+  );
+
+  await api.email({
+    to: cliente.email,
+    subject: `Pedido ${row.numero} confirmado`,
+    body: `
+      Hola ${cliente.nombre},
+
+      Tu pedido ${row.numero} ha sido confirmado.
+
+      Total: ${row.total}€
+
+      Gracias por tu compra.
+    `,
+    // O usar HTML:
+    html: `<h1>Pedido Confirmado</h1><p>...</p>`
+  });
+
+  // ═══════════════════════════════════════════════════════════
+  // API.HTTP - Llamadas a APIs externas
+  // ═══════════════════════════════════════════════════════════
+
+  // Webhook a sistema externo
+  if (env.WEBHOOK_URL) {
+    const response = await api.http(env.WEBHOOK_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${env.WEBHOOK_TOKEN}`
+      },
+      body: JSON.stringify({
+        event: 'pedido_confirmado',
+        pedido: row,
+        cliente: cliente
+      })
+    });
+
+    logger.info('Webhook enviado', { status: response.status });
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // RETURN - Resultado de la automation
+  // ═══════════════════════════════════════════════════════════
+
+  return {
+    success: true,
+    message: `Pedido ${row.numero} procesado correctamente`,
+    data: {
+      lineas_procesadas: lineas.length,
+      email_enviado: true
+    }
+  };
+}
+```
+
+### Variables de Entorno (env)
+
+Cada company puede tener variables de entorno configuradas en `core.company_env_variables`:
+
+```javascript
+// Acceso en automations
+const apiKey = env.STRIPE_API_KEY;
+const webhookUrl = env.SLACK_WEBHOOK;
+const emailFrom = env.EMAIL_FROM || 'noreply@gufi.com';
+```
+
+### Automation con Input del Usuario (Click)
+
+```javascript
+// Definición en el JSON del módulo:
+{
+  "trigger": "click",
+  "function_name": "enviar_recordatorio",
+  "label": "Enviar Recordatorio",
+  "icon": "Mail",
+  "input_schema": {
+    "mensaje": {
+      "type": "textarea",
+      "label": "Mensaje personalizado",
+      "required": true
+    },
+    "urgente": {
+      "type": "boolean",
+      "label": "Marcar como urgente",
+      "default": false
+    }
+  }
+}
+
+// La función recibe el input:
+async function enviar_recordatorio(context, api, logger) {
+  const { row, input } = context;
+
+  // input.mensaje contiene el texto del usuario
+  // input.urgente contiene true/false
+
+  await api.email({
+    to: row.cliente_email,
+    subject: input.urgente ? '🚨 URGENTE: ' + row.numero : row.numero,
+    body: input.mensaje
+  });
+
+  return { success: true };
+}
+```
+
+---
+
+## Views (Vistas del Marketplace)
+
+Las Views son **componentes React/TypeScript** que los consultores escriben en el navegador y se almacenan en PostgreSQL. Se ejecutan dinámicamente en el frontend.
+
+### Dónde se almacenan
+
+```sql
+SELECT id, name, code FROM marketplace.views WHERE package_id = 14;
+```
+
+### Estructura de Archivos de una View
+
+Cuando descargas una view con `gufi pull`, obtienes:
+
+```
+~/gufi-dev/mi-vista/
+├── index.tsx              # Entry point - exporta featureConfig y default
+├── types.ts               # Interfaces TypeScript
+│
+├── core/
+│   └── dataProvider.ts    # 💜 dataSources + featureConfig (MUY IMPORTANTE)
+│
+├── metadata/
+│   ├── inputs.ts          # 💜 Inputs configurables por usuario
+│   ├── help.es.ts         # Documentación en español
+│   └── help.en.ts         # Documentación en inglés
+│
+├── components/
+│   └── MiComponente.tsx   # Componentes React
+│
+├── views/
+│   └── page.tsx           # Página principal
+│
+└── automations/           # Opcional: automations de la vista
+    └── mi_automation.js
+```
+
+---
+
+### 💜 dataSources - Declarar qué Tablas Necesita la Vista
+
+El archivo `core/dataProvider.ts` define qué tablas necesita la vista. El Developer Center lee esto y muestra UI para que el usuario asigne sus tablas.
+
+```typescript
+// core/dataProvider.ts
+// 💜 Mi Vista - Data Sources & Feature Configuration
+
+/* ============================================================================
+   💜 Data Sources - Tablas que necesita esta vista
+============================================================================ */
+export const dataSources = [
+  {
+    key: 'tareasTable',             // Identificador único
+    type: 'table',                   // Siempre 'table'
+    label: { es: 'Tabla de Tareas', en: 'Tasks Table' },
+    description: {
+      es: 'Tabla principal de tareas',
+      en: 'Main tasks table'
+    },
+    required: true,                  // true = obligatorio
+  },
+  {
+    key: 'proyectosTable',
+    type: 'table',
+    label: { es: 'Proyectos', en: 'Projects' },
+    description: {
+      es: 'Tabla de proyectos (opcional)',
+      en: 'Projects table (optional)'
+    },
+    required: false,                 // false = opcional
+  },
+  {
+    key: 'comentariosTable',
+    type: 'table',
+    label: { es: 'Comentarios', en: 'Comments' },
+    description: {
+      es: 'Comentarios en tareas',
+      en: 'Task comments'
+    },
+    required: false,
+  },
+] as const;
+
+/* ============================================================================
+   💜 Feature Config - EXPORTAR SIEMPRE
+============================================================================ */
+import { featureInputs } from '../metadata/inputs';
+
+export const featureConfig = {
+  dataSources,
+  inputs: featureInputs,
+};
+
+// También exporta funciones de carga de datos...
+```
+
+**En el index.tsx:**
+```typescript
+// index.tsx
+export { featureConfig } from './core/dataProvider';
+export default function MiVista({ gufi }) { ... }
+```
+
+**Cómo acceder a las tablas configuradas:**
+```typescript
+export default function MiVista({ gufi }) {
+  const viewSpec = gufi?.context?.viewSpec || {};
+
+  // Keys de dataSources → nombres de tabla físicos
+  const tareasTable = viewSpec.tareasTable;      // "m360_t16194"
+  const proyectosTable = viewSpec.proyectosTable; // "m360_t16200" o undefined
+
+  // Usar para queries
+  const res = await gufi.dataProvider.getList({
+    resource: tareasTable,
+    pagination: { current: 1, pageSize: 100 },
+  });
+}
+```
+
+---
+
+### 💜 inputs (featureInputs) - Configuración del Usuario
+
+Permite que el usuario configure opciones de la vista sin tocar código.
+
+```typescript
+// metadata/inputs.ts
+// 💜 Mi Vista - Inputs Configurables
+
+export const featureInputs = [
+  // BOOLEAN - Checkbox
+  {
+    key: 'showCompleted',
+    type: 'boolean',
+    label: { es: 'Mostrar completadas', en: 'Show completed' },
+    description: {
+      es: 'Incluir tareas completadas',
+      en: 'Include completed tasks'
+    },
+    default: false,
+  },
+
+  // SELECT - Dropdown estático
+  {
+    key: 'defaultView',
+    type: 'select',
+    label: { es: 'Vista por defecto', en: 'Default view' },
+    description: {
+      es: 'Panel inicial al abrir',
+      en: 'Initial panel on open'
+    },
+    options: [
+      { value: 'list', label: { es: 'Lista', en: 'List' } },
+      { value: 'kanban', label: { es: 'Kanban', en: 'Kanban' } },
+      { value: 'calendar', label: { es: 'Calendario', en: 'Calendar' } },
+    ],
+    default: 'list',
+  },
+
+  // NUMBER - Input numérico
+  {
+    key: 'lowStockThreshold',
+    type: 'number',
+    label: { es: 'Umbral stock bajo (%)', en: 'Low stock threshold (%)' },
+    description: {
+      es: 'Porcentaje para alertas',
+      en: 'Percentage for alerts'
+    },
+    placeholder: '40',
+    default: 40,
+  },
+
+  // TEXT - Input de texto
+  {
+    key: 'emailCc',
+    type: 'text',
+    label: { es: 'Email CC', en: 'CC Email' },
+    description: {
+      es: 'Email en copia',
+      en: 'CC email'
+    },
+    placeholder: 'admin@empresa.com',
+  },
+
+  // SELECT con opciones de otra tabla (dinámico)
+  {
+    key: 'defaultWarehouse',
+    type: 'select',
+    label: { es: 'Almacén por defecto', en: 'Default warehouse' },
+    description: {
+      es: 'Almacén seleccionado al abrir',
+      en: 'Warehouse on open'
+    },
+    optionsFrom: 'warehousesTable',  // 💜 Carga opciones del dataSource
+    default: 'all',
+  },
+] as const;
+```
+
+**Acceder a inputs en runtime:**
+```typescript
+export default function MiVista({ gufi }) {
+  const viewSpec = gufi?.context?.viewSpec || {};
+
+  // Los inputs están directamente en viewSpec
+  const showCompleted = viewSpec.showCompleted ?? false;
+  const defaultView = viewSpec.defaultView ?? 'list';
+  const threshold = viewSpec.lowStockThreshold ?? 40;
+  const emailCc = viewSpec.emailCc;
+}
+```
+
+---
+
+### 💜 help - Documentación para Usuarios
+
+Crea archivos de ayuda que aparecen en el botón "?" de la vista.
+
+```typescript
+// metadata/help.es.ts
+export const help = {
+  // Para Admin/Consultant
+  consultant: {
+    title: "Mi Vista",
+    description: "Descripción breve de la vista.",
+    sections: [
+      {
+        id: "overview",
+        title: "Descripción General",
+        content: `
+**Funcionalidades:**
+- Lista de tareas con filtros
+- Vista Kanban por proyecto
+- Sistema de comentarios
+
+**Tablas requeridas:**
+| DataSource | Descripción |
+|------------|-------------|
+| tareasTable | Tabla principal de tareas |
+| proyectosTable | Proyectos (opcional) |
+        `.trim(),
+      },
+      {
+        id: "configuration",
+        title: "Configuración",
+        content: `
+**Campos requeridos en tareas:**
+- titulo (text)
+- estado (select: pendiente, en_progreso, completada)
+- asignado_a (users)
+- proyecto_id (relation, opcional)
+        `.trim(),
+      },
+      {
+        id: "permissions",
+        title: "Permisos",
+        content: `
+| Permiso | Efecto |
+|---------|--------|
+| * | Acceso completo |
+| entity:view | Solo lectura |
+| create_tasks | Puede crear tareas |
+        `.trim(),
+      },
+    ],
+  },
+
+  // Para usuarios finales
+  user: {
+    title: "Guía de Uso",
+    sections: [
+      {
+        id: "basics",
+        title: "Uso Básico",
+        content: `
+1. **Mis Tareas**: Tareas asignadas a ti
+2. **Proyectos**: Vista Kanban por proyecto
+3. **Gestión**: Tareas que has asignado
+
+Para crear tarea, pulsa el botón **+**
+        `.trim(),
+      },
+    ],
+  },
+};
+```
+
+---
+
+### 💜 automations en Vistas
+
+Las vistas pueden incluir automations que se ejecutan al hacer click.
+
+**Archivo de automation:**
+```javascript
+// automations/send_notification.js
+/**
+ * 💜 Automation: send_notification
+ * Trigger: ON_CLICK (desde la vista)
+ */
+async function send_notification(context, api, logger) {
+  const { input, env } = context;
+  const { tarea_id, mensaje } = input;
+
+  // Obtener tarea
+  const { rows } = await api.query(
+    'SELECT titulo, asignado_a FROM tareas WHERE id = $1',
+    [tarea_id]
+  );
+
+  // Obtener email del asignado
+  const { rows: users } = await api.query(
+    'SELECT email FROM core.users WHERE id = $1',
+    [rows[0].asignado_a]
+  );
+
+  // Enviar email
+  await api.email({
+    to: users[0].email,
+    subject: `Notificación: ${rows[0].titulo}`,
+    html: `<p>${mensaje}</p>`,
+    cc: env.NOTIFICATION_CC,
+  });
+
+  logger.info('Notificación enviada', { tarea_id });
+  return { success: true };
+}
+```
+
+**Llamar automation desde React:**
+```typescript
+const handleNotify = async (tareaId: number) => {
+  try {
+    const result = await gufi.utils.runClickAutomation({
+      functionName: 'send_notification',
+      input: {
+        tarea_id: tareaId,
+        mensaje: 'Tu tarea ha sido actualizada',
+      },
+    });
+
+    if (result.success) {
+      gufi.utils.toastSuccess('Notificación enviada');
+    }
+  } catch (err) {
+    gufi.utils.toastError(err.message);
+  }
+};
+```
+
+---
+
+### 💜 El Objeto `gufi` - Props Completas
+
+Toda vista recibe `gufi` con todo lo necesario:
+
+```typescript
+interface GufiProps {
+  context: {
+    user: { id, email, name, role };
+    lang: 'es' | 'en';
+    viewSpec: {
+      // dataSources configurados
+      tareasTable: string;
+      proyectosTable?: string;
+      // inputs configurados
+      showCompleted: boolean;
+      defaultView: string;
+      lowStockThreshold: number;
+    };
+    companyId: number;
+    moduleId: number;
+    entityId: number;
+  };
+
+  dataProvider: {
+    getList({ resource, pagination, filters, sorters });
+    getOne({ resource, id });
+    create({ resource, variables });
+    update({ resource, id, variables });
+    deleteOne({ resource, id });
+  };
+
+  utils: {
+    toastSuccess(msg: string);
+    toastError(msg: string);
+    toastInfo(msg: string);
+    runClickAutomation({ functionName, input });
+  };
+}
+```
+
+---
+
+### 💜 seedData - Datos de Ejemplo para Demo/Testing
+
+Las vistas pueden incluir datos de ejemplo que se cargan automáticamente al instalar. Esto es útil para demos, testing, y onboarding de nuevos usuarios.
+
+```typescript
+// metadata/seedData.ts
+export interface SeedDataConfig {
+  description: { es: string; en: string };
+  data: { [dataSourceKey: string]: Array<Record<string, any>> };
+  order: string[];  // Orden de creación (importante para referencias)
+}
+
+export const seedData: SeedDataConfig = {
+  description: {
+    es: 'Crea empresas de ejemplo (Singular, FitVending), proyectos y tareas de prueba',
+    en: 'Creates sample companies, projects and test tasks',
+  },
+
+  // Orden de creación - tablas con referencias van después
+  order: ['empresasTable', 'proyectosTable', 'tareasTable'],
+
+  data: {
+    // Empresas/Clientes
+    empresasTable: [
+      {
+        nombre: 'Singular',
+        contacto: 'Contacto Singular',
+        email: 'contacto@singular.es',
+        estado: 'activo'
+      },
+      {
+        nombre: 'FitVending',
+        contacto: 'Equipo FitVending',
+        email: 'info@fitvending.es',
+        estado: 'activo'
+      },
+    ],
+
+    // Proyectos
+    proyectosTable: [
+      {
+        nombre: 'Gufi ERP',
+        descripcion: 'Desarrollo del ERP Gufi',
+        color: '#8B5CF6',
+        estado: 'activo',
+      },
+    ],
+
+    // Tareas - con referencias a otras tablas
+    tareasTable: [
+      {
+        titulo: 'Revisar bug crítico',
+        descripcion: 'Los usuarios reportan problemas',
+        asignado_a: '@currentUser',      // 💜 Token especial: usuario actual
+        asignado_por: '@currentUser',
+        prioridad: 'urgente',
+        estado: 'pendiente',
+        fecha_limite: '@today',           // 💜 Token especial: fecha de hoy
+        proyecto_id: '@ref:proyectosTable.0',  // 💜 Referencia: ID del primer proyecto
+        empresa_id: '@ref:empresasTable.0',    // 💜 Referencia: ID de primera empresa
+      },
+      {
+        titulo: 'Preparar demo',
+        descripcion: 'Demo del módulo de facturación',
+        asignado_a: '@currentUser',
+        prioridad: 'alta',
+        fecha_limite: '@tomorrow',        // 💜 Token especial: mañana
+        empresa_id: '@ref:empresasTable.1',
+      },
+    ],
+  },
+};
+```
+
+**Tokens Especiales:**
+| Token | Descripción |
+|-------|-------------|
+| `@currentUser` | ID del usuario actual (para campos users) |
+| `@today` | Fecha de hoy (YYYY-MM-DD) |
+| `@tomorrow` | Fecha de mañana |
+| `@nextWeek` | Fecha dentro de 7 días |
+| `@ref:tableKey.index` | ID del registro creado en otra tabla |
+
+**Agregar a featureConfig:**
+```typescript
+// core/dataProvider.ts
+import { seedData } from '../metadata/seedData';
+
+export const featureConfig = {
+  dataSources,
+  inputs: featureInputs,
+  seedData,  // 💜 Agregar aquí
+};
+```
+
+**Cargar desde Developer Center:**
+En la página de edición de vista, el Developer Center muestra un botón "Load Sample Data" que ejecuta el seedData en la company seleccionada.
+
+---
+
+### 💜 Checklist para Nueva Vista
+
+1. [ ] `core/dataProvider.ts` - dataSources + export featureConfig
+2. [ ] `metadata/inputs.ts` - featureInputs configurables
+3. [ ] `metadata/seedData.ts` - Datos de ejemplo (opcional pero recomendado)
+4. [ ] `metadata/help.es.ts` y `help.en.ts` - Documentación
+5. [ ] `index.tsx` - export featureConfig y default component
+6. [ ] Usar `gufi?.context?.viewSpec` para tablas e inputs
+7. [ ] Usar `gufi?.dataProvider` para CRUD
+8. [ ] Usar `gufi?.utils?.toast*` para notificaciones
+9. [ ] Si hay automation: carpeta `automations/` con .js
+
+### View.tsx - Componente Principal
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { useList, useUpdate, useCreate } from '@refinedev/core';
+
+// ═══════════════════════════════════════════════════════════════
+// PROPS que recibe toda View
+// ═══════════════════════════════════════════════════════════════
+interface ViewProps {
+  // Configuración de la vista
+  viewSpec: {
+    id: number;
+    name: string;
+    config: Record<string, any>;  // Config guardada por el usuario
+  };
+
+  // Contexto de la company
+  context: {
+    companyId: number;
+    moduleId: number;
+    entityId: number;
+  };
+
+  // Usuario actual
+  user: {
+    id: number;
+    email: string;
+    name: string;
+    role: string;
+  };
+
+  // Notificaciones
+  toastSuccess: (message: string) => void;
+  toastError: (message: string) => void;
+  toastInfo: (message: string) => void;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// COMPONENTE PRINCIPAL
+// ═══════════════════════════════════════════════════════════════
+export default function MiVista({ viewSpec, context, user, toastSuccess, toastError }: ViewProps) {
+  const [filtro, setFiltro] = useState('todos');
+
+  // ─────────────────────────────────────────────────────────────
+  // useList - Obtener lista de registros
+  // ─────────────────────────────────────────────────────────────
+  const { data, isLoading, refetch } = useList({
+    resource: 'm360_t16192',  // Nombre físico de la tabla
+    pagination: { current: 1, pageSize: 100 },
+    filters: filtro !== 'todos' ? [
+      { field: 'estado', operator: 'eq', value: filtro }
+    ] : [],
+    sorters: [
+      { field: 'created_at', order: 'desc' }
+    ]
+  });
+
+  // ─────────────────────────────────────────────────────────────
+  // useUpdate - Actualizar registros
+  // ─────────────────────────────────────────────────────────────
+  const { mutate: updateRecord } = useUpdate();
+
+  const handleStatusChange = (id: number, newStatus: string) => {
+    updateRecord(
+      {
+        resource: 'm360_t16192',
+        id,
+        values: { estado: newStatus }
+      },
+      {
+        onSuccess: () => {
+          toastSuccess('Estado actualizado');
+          refetch();
+        },
+        onError: (error) => {
+          toastError('Error al actualizar: ' + error.message);
+        }
+      }
+    );
+  };
+
+  // ─────────────────────────────────────────────────────────────
+  // useCreate - Crear registros
+  // ─────────────────────────────────────────────────────────────
+  const { mutate: createRecord } = useCreate();
+
+  const handleCreate = (data: any) => {
+    createRecord(
+      {
+        resource: 'm360_t16192',
+        values: data
+      },
+      {
+        onSuccess: () => {
+          toastSuccess('Registro creado');
+          refetch();
+        }
+      }
+    );
+  };
+
+  // ─────────────────────────────────────────────────────────────
+  // RENDER
+  // ─────────────────────────────────────────────────────────────
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center h-64">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-violet-600" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-6 bg-gradient-to-br from-violet-50/40 via-white to-purple-50/40 min-h-screen">
+      {/* Header */}
+      <div className="flex items-center justify-between mb-6">
+        <h1 className="text-2xl font-bold text-gray-900">
+          {viewSpec.name}
+        </h1>
+        <div className="flex gap-2">
+          <select
+            value={filtro}
+            onChange={(e) => setFiltro(e.target.value)}
+            className="px-3 py-2 border rounded-lg"
+          >
+            <option value="todos">Todos</option>
+            <option value="pendiente">Pendientes</option>
+            <option value="completado">Completados</option>
+          </select>
+        </div>
+      </div>
+
+      {/* Lista */}
+      <div className="grid gap-4">
+        {data?.data.map((item: any) => (
+          <div
+            key={item.id}
+            className="p-4 bg-white rounded-xl shadow-sm border border-gray-100 hover:shadow-md transition-shadow"
+          >
+            <div className="flex items-center justify-between">
+              <div>
+                <h3 className="font-medium text-gray-900">{item.titulo}</h3>
+                <p className="text-sm text-gray-500">{item.descripcion}</p>
+              </div>
+              <button
+                onClick={() => handleStatusChange(item.id, 'completado')}
+                className="px-4 py-2 bg-violet-600 text-white rounded-lg hover:bg-violet-700"
+              >
+                Completar
+              </button>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Empty state */}
+      {data?.data.length === 0 && (
+        <div className="text-center py-12 text-gray-500">
+          No hay registros que mostrar
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### dataProvider.ts - Lógica de Datos Custom
+
+```typescript
+// core/dataProvider.ts
+import { DataProvider } from '@refinedev/core';
+
+// Puedes extender el dataProvider por defecto
+export const customDataProvider = (baseProvider: DataProvider): DataProvider => ({
+  ...baseProvider,
+
+  // Override getList para transformar datos
+  getList: async (params) => {
+    const result = await baseProvider.getList(params);
+
+    // Transformar datos antes de devolverlos
+    return {
+      ...result,
+      data: result.data.map(item => ({
+        ...item,
+        // Agregar campos calculados
+        diasPendiente: calcularDias(item.created_at),
+        prioridadColor: getPrioridadColor(item.prioridad)
+      }))
+    };
+  },
+
+  // Custom method para operaciones especiales
+  custom: async ({ url, method, payload }) => {
+    const response = await fetch(url, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+    return response.json();
+  }
+});
+
+function calcularDias(fecha: string): number {
+  const diff = Date.now() - new Date(fecha).getTime();
+  return Math.floor(diff / (1000 * 60 * 60 * 24));
+}
+
+function getPrioridadColor(prioridad: string): string {
+  const colores: Record<string, string> = {
+    alta: 'red',
+    media: 'yellow',
+    baja: 'green'
+  };
+  return colores[prioridad] || 'gray';
+}
+```
+
+---
+
+## Packages del Marketplace
+
+Un Package agrupa múltiples Views y módulos relacionados para distribuirlos.
+
+### Estructura en Base de Datos
+
+```sql
+-- Package publicado
+SELECT * FROM marketplace.packages WHERE id = 14;
+-- { id: 14, name: "Stock Management", version: "1.2.0", published_at: ... }
+
+-- Vistas del package
+SELECT id, name FROM marketplace.views WHERE package_id = 14;
+-- { id: 5, name: "Stock Overview" }
+-- { id: 6, name: "Inventory Report" }
+
+-- Módulos incluidos (snapshot)
+SELECT * FROM marketplace.package_modules WHERE package_id = 14;
+```
+
+### Flujo de Desarrollo → Publicación
+
+```
+1. DESARROLLO (en tu company)
+   └── Creas módulo "Stock" en company 116
+   └── Creas views en Developer Center
+   └── Testas todo localmente
+
+2. CREAR PACKAGE
+   └── Developer Center → Packages → New Package
+   └── Agregas módulo "Stock"
+   └── Agregas views "Stock Overview", "Inventory Report"
+
+3. PUBLICAR
+   └── Click "Publish to Marketplace"
+   └── Sistema crea snapshot inmutable
+   └── Versión 1.0.0 disponible
+
+4. INSTALACIÓN (otra company)
+   └── Company 200 instala el package
+   └── Sistema crea módulo "Stock" en company_200
+   └── Views disponibles en su menú
+```
+
+---
+
+## Comandos del CLI
+
+### Instalación
+
+```bash
+npm install -g gufi-cli
+gufi login
+```
+
+### Gestión de Companies y Módulos
+
+```bash
+# Ver companies
+gufi companies
+
+# Ver módulos de una company
+gufi modules 146
+
+# Ver JSON de un módulo
+gufi module 360 -c 146
+
+# Editar módulo con tu editor
+gufi module 360 -c 146 --edit
+
+# Guardar JSON a archivo
+gufi module 360 -c 146 --file modulo.json
+
+# Actualizar módulo desde archivo
+gufi module:update 360 modulo.json -c 146
+
+# Validar sin aplicar cambios
+gufi module:update 360 modulo.json -c 146 --dry-run
+
+# Crear nueva company
+gufi company:create "Mi Empresa"
+```
+
+### Automations
+
+```bash
+# Listar automation scripts
+gufi automations -c 116
+
+# Ver código de una automation
+gufi automation calcular_stock -c 116
+
+# Editar con tu editor
+gufi automation calcular_stock -c 116 --edit
+
+# Guardar a archivo
+gufi automation calcular_stock -c 116 --file script.js
+```
+
+### Desarrollo de Views
+
+```bash
+# Ver tus packages y views
+gufi list
+
+# Descargar view para editar localmente
+gufi pull "Stock Overview"
+
+# Auto-sync al guardar archivos
+gufi watch
+
+# Ver console.log del LivePreview
+gufi logs
+
+# Subir cambios manualmente
+gufi push
+
+# Ver estado de sincronización
+gufi status
+```
+
+### Opciones Globales
+
+| Opción | Descripción |
+|--------|-------------|
+| `-c, --company <id>` | ID de company |
+| `-e, --edit` | Abrir en editor ($EDITOR) |
+| `-f, --file <path>` | Guardar a archivo |
+| `--dry-run` | Validar sin aplicar |
+| `-h, --help` | Ayuda del comando |
+
+---
+
+## Tips para Claude
+
+### Cuándo usar cada comando
+
+| El usuario quiere... | Comando |
+|---------------------|---------|
+| Ver qué companies tiene | `gufi companies` |
+| Ver estructura de una company | `gufi modules <company_id>` |
+| Ver/editar JSON de módulo | `gufi module <id> -c <company>` |
+| Ver/editar código de automation | `gufi automation <nombre> -c <company>` |
+| Desarrollar una vista | `gufi pull`, `gufi watch`, `gufi logs` |
+
+### Errores comunes
+
+| Error | Solución |
+|-------|----------|
+| "No estás logueado" | `gufi login` |
+| "Módulo no encontrado" | Verificar `-c <company_id>` |
+| "Token expirado" | `gufi login` de nuevo |
+| "JSON inválido" | Validar estructura del JSON |
+
+### Conceptos clave
+
+- **Multi-tenant**: Cada company = schema aislado en PostgreSQL
+- **Tablas físicas**: `m{moduleId}_t{entityId}`
+- **Módulos**: JSON que define estructura → Gufi crea tablas/UI
+- **Automations**: JS en DB, ejecutado por worker (pg-boss)
+- **Views**: React/TS en DB, ejecutado en frontend dinámicamente
+- **Marketplace**: Sistema de distribución de packages
+
+---
+
+## Links
+
+- **Web**: https://gogufi.com
+- **Docs**: https://github.com/juanbp23/gogufi/blob/main/docs/guide/05-marketplace.md