--- name: shopify-unificar-proveedores description: "Solo lectura: detecta nombres de proveedor escritos de varias formas (errores de tipeo, mayúsculas, espacios de más) y propone un nombre único para cada grupo. Úsala para ordenar el campo de proveedor de tu catálogo antes de unificarlo." --- ## Propósito Recorre todos los productos del catálogo, normaliza el campo `vendor` (proveedor) y agrupa los casi duplicados, como `Acme`, `ACME`, `Acme Inc` y `Acme ` (con espacios al final). Recomienda un nombre canónico por grupo y cuenta cuántos productos tendrían que cambiar. Cuando un mismo proveedor aparece escrito de muchas formas, se dañan los reportes por proveedor, la navegación y la conciliación con proveedores. Solo lectura: no ejecuta mutaciones; el resultado es la lista de trabajo para una unificación posterior. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products` - Las consultas se ejecutan con `shopify store execute`. - Permisos de la API: `read_products` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | texto | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) | | similarity_threshold | decimal | no | 0.88 | Umbral de similitud de Levenshtein para agrupar (0.0–1.0) | | min_cluster_size | entero | no | 2 | Solo muestra los grupos con al menos esta cantidad de nombres de proveedor distintos | | ignore_suffixes | texto | no | "Inc,LLC,Ltd,Co,Corp" | Sufijos de empresa, separados por comas, que se quitan antes de comparar | | status_filter | texto | no | ALL | Estado de producto que se incluye: `ACTIVE`, `DRAFT`, `ARCHIVED` o `ALL` | | format | texto | no | human | Formato de salida: `human` o `json` | ## Seguridad > ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento. La skill produce una lista de recomendaciones; la unificación se tiene que aplicar con un flujo aparte y revisado. ## Pasos 1. **OPERACIÓN:** `products` — consulta **Entradas:** `first: 250`, `query: `; selecciona `vendor`, `id`, `title`, `status` y el cursor de paginación **Resultado esperado:** Cada producto con su proveedor; pagina hasta que `hasNextPage: false` 2. Arma un mapa de frecuencias: nombre de proveedor distinto → cantidad de productos. Normaliza cada proveedor así: quita los espacios al inicio y al final, reduce los espacios repetidos a uno, quita los sufijos configurados y pasa todo a minúsculas para comparar. 3. Agrupa los nombres de proveedor cuya forma normalizada tenga una similitud de Levenshtein por encima de `similarity_threshold`. Elige como canónico de cada grupo la variante más usada; en caso de empate, la más corta y, después, la primera en orden alfabético. 4. Descarta los grupos con menos de `min_cluster_size` nombres distintos. Calcula el impacto: cuántos productos pasarían al nombre canónico. 5. Ordena los grupos por impacto, de mayor a menor, para que primero aparezcan las unificaciones que más rinden. ## Operaciones GraphQL ```graphql # products:query — validada con api_version 2025-01 query AllVendors($query: String, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title vendor status productType updatedAt } } pageInfo { hasNextPage endCursor } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar la siguiente salida en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Unifica nombres de proveedores ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ REPORTE DE UNIFICACIÓN DE PROVEEDORES Productos revisados: Proveedores distintos: Grupos detectados: Productos por cambiar: Grupos con mayor impacto: Canónico: "" Variantes: Productos: "" () "" () Archivo: vendor_consolidation_.csv ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-unificar-proveedores", "store": "", "products_scanned": 0, "distinct_vendors": 0, "clusters": [ { "canonical": "Acme", "variants": [ { "value": "Acme", "products": 0 }, { "value": "ACME", "products": 0 }, { "value": "Acme Inc", "products": 0 } ], "products_to_migrate": 0 } ], "output_file": "vendor_consolidation_.csv" } ``` ## Formato de salida Archivo CSV `vendor_consolidation_.csv` con las columnas: `cluster_id`, `canonical_vendor`, `variant_vendor`, `is_canonical`, `product_count`, `sample_product_id`, `sample_product_title`, `status` ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces | | Campo `vendor` vacío en un producto | Nunca se definió el proveedor | Ponlo en el grupo `(sin definir)` y muestra su cantidad aparte | | Dos proveedores distintos y válidos quedan juntos por similitud | Falso positivo (p. ej., `Apple` y `Appel`) | Bajar `similarity_threshold` no es seguro; revisa el grupo a mano antes de aplicar cambios | | Proveedores que se ven iguales pero son distintos en Unicode | Comillas tipográficas o espacio de no separación | El paso de normalización los quita antes de comparar | ## Buenas prácticas - Empieza con el valor predeterminado `similarity_threshold: 0.88`. Por debajo de 0.85, los falsos positivos se multiplican rápido. - Revisa a mano cada grupo antes de aplicar cambios: `ABC Corp` y `ABC Co.` pueden ser o no el mismo proveedor en tu contabilidad. - Usa `ignore_suffixes` para absorber el ruido de la razón social (`Inc`, `LLC`), que rara vez cambia la identidad real del proveedor. - Después de revisar, aplica la unificación con un flujo de actualización aparte (por ejemplo, un script interno de actualización de productos) y vuelve a correr esta auditoría hasta que los grupos queden por debajo de `min_cluster_size`. - Combínala con `shopify-calidad-fichas-producto` para seguir en el tiempo qué tan limpio está el campo de proveedor, junto con otras métricas de calidad del catálogo.