gufi-cli 0.1.50 → 0.1.52

package/docs/mcp/08-common-errors.md

@@ -0,0 +1,284 @@
+# Errores Comunes y Soluciones
+
+## Datos y tipos
+
+### Currency como objeto (INCORRECTO)
+
+```javascript
+// ERROR: Formato legacy
+precio: { currency: 'EUR', amount: 150 }
+
+// CORRECTO: Solo el numero
+precio: gufi.CB.currency(150)
+// o directamente:
+precio: 150
+```
+
+Currency ahora es NUMERIC. El codigo de moneda va en el schema del campo.
+
+### Phone con formato incorrecto
+
+```javascript
+// ERROR: Formato legacy
+telefono: { country: 'ES', number: '612345678' }
+
+// CORRECTO: Usar CB.phone
+telefono: gufi.CB.phone('612345678')
+// Resultado: { prefix: '+34', number: '612345678' }
+```
+
+### Olvidar __display en updates
+
+```javascript
+// ERROR: UI no muestra el cambio
+await dataProvider.update({
+  resource: table,
+  id: 5,
+  variables: { estado: 'completado' }
+});
+
+// CORRECTO: Actualizar ambos
+await dataProvider.update({
+  resource: table,
+  id: 5,
+  variables: {
+    estado: 'completado',
+    estado__display: 'Completado'
+  }
+});
+```
+
+Aplica a: `select`, `relation`, `currency` (si tenia formato viejo)
+
+### Base64 en campos file
+
+```javascript
+// ERROR: Base64 directo
+foto: 'data:image/png;base64,iVBOR...'
+
+// CORRECTO: Subir primero, luego guardar URL
+const { url, name } = await uploadFile(file);
+foto: gufi.CB.file(url, name)
+```
+
+Solo `signature` acepta base64 directo.
+
+## Vistas
+
+### Hardcodear IDs físicos de tabla
+
+```typescript
+// ERROR: IDs físicos difíciles de leer y no portables
+const data = await dataProvider.getList({ resource: 'm360_t16192' });
+
+// CORRECTO: Usar nombres lógicos (dataProvider los resuelve automáticamente)
+const pedidosTable = 'ventas.pedidos';
+const data = await dataProvider.getList({ resource: pedidosTable });
+```
+
+### Importar stores directamente
+
+```typescript
+// ERROR: Rompe aislamiento
+import { useAuthStore } from '@/stores/useAuthStore';
+
+// CORRECTO: Usar gufi.context
+const user = gufi.context?.user;
+const company = gufi.context?.activeCompany;
+```
+
+### Toast de shadcn
+
+```typescript
+// ERROR: No es el toast de Gufi
+import { toast } from '@/components/ui/toast';
+
+// CORRECTO: Toast del SDK
+import { toastSuccess, toastError } from '@/sdk';
+toastSuccess('Guardado');
+```
+
+### Olvidar exportar featureConfig
+
+```typescript
+// ERROR: Vista no tiene dataSources
+export default function MiVista() { ... }
+
+// CORRECTO: Exportar featureConfig
+export { featureConfig } from './core/dataProvider';
+export default function MiVista() { ... }
+```
+
+## Automations
+
+### Destructuring en api.query
+
+```javascript
+// ERROR: api.query devuelve rows directamente
+const { rows } = await gufi.query("SELECT * FROM table");
+
+// CORRECTO:
+const rows = await gufi.query("SELECT * FROM table");
+```
+
+### SQL injection
+
+```javascript
+// ERROR: Interpolacion directa
+const rows = await gufi.query(`SELECT * FROM users WHERE id = ${id}`);
+
+// CORRECTO: Parametros
+const rows = await gufi.query("SELECT * FROM users WHERE id = $1", [id]);
+```
+
+### Return sin success
+
+```javascript
+// ERROR: Worker no sabe si funciono
+async function mi_automation(ctx, api, logger) {
+  // ... hacer cosas
+}
+
+// CORRECTO: Retornar estado
+async function mi_automation(ctx, api, logger) {
+  // ... hacer cosas
+  return { success: true, message: 'OK' };
+}
+```
+
+## API y autenticacion
+
+### Falta X-Company-ID
+
+```
+// ERROR: 400 Bad Request
+GET /api/company/schema
+Authorization: Bearer xxx
+
+// CORRECTO:
+GET /api/company/schema
+Authorization: Bearer xxx
+X-Company-ID: 116
+```
+
+### Token expirado
+
+```
+// Response: 401 Unauthorized
+// Solucion: Refresh token
+
+POST /api/auth/refresh
+X-Refresh-Token: {refreshToken}
+```
+
+### Sin permisos
+
+```
+// Response: 403 Forbidden
+// Causa: Usuario no tiene permiso para esa accion
+
+// Verificar permisos de la entidad:
+gufi_context({ company_id: "116" })
+// Ver permissions de cada entity
+```
+
+## Modulos
+
+### Field type incorrecto
+
+```json
+// ERROR: Tipo no existe
+{ "name": "fecha", "type": "timestamp" }
+
+// CORRECTO: Usar date (con includeTime si necesitas hora)
+{ "name": "fecha", "type": "date" }
+{ "name": "fecha_hora", "type": "date", "includeTime": true }
+```
+
+Tipos validos: `text`, `email`, `url`, `barcode`, `number`, `number_int`, `number_float`, `percentage`, `date`, `time`, `select`, `multiselect`, `boolean`, `relation`, `users`, `currency`, `phone`, `location`, `file`, `signature`, `json`, `formula`, `mirror`
+
+### Relacion sin displayField
+
+```json
+// WARNING: Muestra ID en lugar de nombre
+{
+  "name": "cliente",
+  "type": "relation",
+  "relation": { "module": "crm", "entity": "clientes" }
+}
+
+// MEJOR: Especificar displayField
+{
+  "name": "cliente",
+  "type": "relation",
+  "relation": {
+    "module": "crm",
+    "entity": "clientes",
+    "displayField": "nombre"
+  }
+}
+```
+
+### Select sin options
+
+```json
+// ERROR: No hay opciones que seleccionar
+{ "name": "estado", "type": "select" }
+
+// CORRECTO:
+{
+  "name": "estado",
+  "type": "select",
+  "options": [
+    { "value": "activo", "label": "Activo", "color": "green" },
+    { "value": "inactivo", "label": "Inactivo", "color": "gray" }
+  ]
+}
+```
+
+## Packages
+
+### Publicar sin cambios guardados
+
+```javascript
+// ERROR: Cambios no se reflejan
+
+// CORRECTO: Verificar con get antes de publicar
+gufi_package({ action: "get", id: "14" })
+// Ver has_unpublished_changes
+
+// Publicar
+gufi_package({ action: "publish", id: "14" })
+```
+
+## Debug tips
+
+### Ver logs de automation
+
+```javascript
+gufi_automation_executions({
+  company_id: "116",
+  script_name: "mi_automation",
+  limit: 5
+})
+```
+
+### Ver schema completo
+
+```javascript
+gufi_context({ company_id: "116" })
+```
+
+### Verificar configuracion
+
+```javascript
+gufi_whoami()
+```
+
+### Probar API directamente
+
+```bash
+curl -X GET "https://api.gogufi.com/api/company/schema" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Company-ID: 116"
+```