--- name: shopify-auditoria-definiciones-metacampos description: "Solo lectura: lista todas las definiciones de metacampos de la tienda y marca las que no se usan, no tienen descripción o repiten la misma clave. Úsala antes de limpiar metacampos o después de instalar o desinstalar apps." --- ## Propósito Hace un inventario de todas las definiciones de metacampos (PRODUCT, VARIANT, CUSTOMER, ORDER, COLLECTION, COMPANY, LOCATION y otras) y marca las definiciones sin uso (cero valores guardados), sin documentar (sin descripción) o que comparten el mismo `namespace.key` entre distintos tipos de propietario. El exceso de definiciones es una de las principales causas de errores en temas y apps, y de búsquedas lentas en el admin. Solo lectura: no hace mutaciones. Sirve de base de datos para un proceso de limpieza de definiciones. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,read_customers,read_orders,read_inventory` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: permisos de lectura para cada tipo de propietario que se revise (por defecto: `read_products`, `read_customers`, `read_orders`) ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | owner_types | string | no | all | Tipos de propietario a revisar, separados por comas (p. ej., `PRODUCT,CUSTOMER`); `all` revisa todos los tipos compatibles | | flag_unused | bool | no | true | Marca las definiciones cuyo `metafieldsCount` es cero | | flag_undocumented | bool | no | true | Marca las definiciones con `description` vacía o null | | flag_duplicates | bool | no | true | Marca los pares `namespace.key` que existen en más de un tipo de propietario | | format | string | no | human | Formato de salida: `human` o `json` | ## Seguridad > ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento. Esta skill no elimina, actualiza ni fija ninguna definición de metacampo. ## Pasos 1. Define la lista de tipos de propietario a revisar a partir de `owner_types` (por defecto: la lista completa). 2. **OPERACIÓN:** `metafieldDefinitions` — consulta **Entradas:** para cada tipo de propietario: `first: 250`, `ownerType: `, selecciona `id`, `namespace`, `key`, `name`, `description`, `type { name }`, `pinnedPosition`, `metafieldsCount`, `validations { name value }` y el cursor de paginación **Resultado esperado:** Todas las definiciones por tipo de propietario con su conteo de uso; pagina hasta `hasNextPage: false` 3. Arma el conjunto de marcas de cada definición: - `unused`: `metafieldsCount == 0` y `flag_unused: true` - `undocumented`: `description` es null o vacía y `flag_undocumented: true` - `duplicate_key`: el `namespace.key` aparece en más de un tipo de propietario y `flag_duplicates: true` 4. Agrupa los resultados por tipo de propietario para el reporte y muestra un resumen por cada marca. ## Operaciones GraphQL ```graphql # metafieldDefinitions:query — validada con api_version 2025-01 query MetafieldDefinitionAudit($ownerType: MetafieldOwnerType!, $after: String) { metafieldDefinitions(first: 250, after: $after, ownerType: $ownerType) { edges { node { id namespace key name description ownerType pinnedPosition metafieldsCount type { name category } validations { name value type } access { admin storefront } } } pageInfo { hasNextPage endCursor } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Auditoría de definiciones de ║ ║ metacampos ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ AUDITORÍA DE DEFINICIONES DE METACAMPOS Tipos de propietario revisados: Total de definiciones: Por tipo de propietario: PRODUCT: (sin uso: , sin documentar: ) VARIANT: (sin uso: , sin documentar: ) CUSTOMER: (sin uso: , sin documentar: ) ORDER: (sin uso: , sin documentar: ) Marcas: Definiciones sin uso: Definiciones sin documentar: Claves duplicadas: Ejemplos: PRODUCT custom.swatch_hex sin uso (0 valores) CUSTOMER custom.vip_tier sin documentar ORDER+CUSTOMER custom.notes clave duplicada entre tipos de propietario Archivo: metafield_def_audit_.csv ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-auditoria-definiciones-metacampos", "store": "", "owner_types_scanned": 0, "total_definitions": 0, "unused_definitions": 0, "undocumented_definitions": 0, "duplicate_keys": 0, "output_file": "metafield_def_audit_.csv" } ``` ## Formato de salida Archivo CSV `metafield_def_audit_.csv` con las columnas: `definition_id`, `owner_type`, `namespace`, `key`, `name`, `type`, `description_present`, `metafields_count`, `pinned`, `is_unused`, `is_undocumented`, `is_duplicate_key`, `flags` ## 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 | | `ACCESS_DENIED` para un tipo de propietario | Falta el permiso de lectura para ese recurso | Omite ese tipo de propietario y deja una fila de advertencia en el CSV | | `metafieldsCount` devuelve null | El tipo de propietario no expone el conteo o el conteo aún se está calculando | Trátalo como `unknown`; no lo marques como `unused` | | Tipo de propietario no disponible en la versión de la API | Tipo de propietario nuevo que aún no está disponible | Omítelo con una advertencia; vuelve a ejecutar después de actualizar la versión de la API | ## Buenas prácticas - Ejecútala cada trimestre y después de instalar o desinstalar cualquier app: las apps suelen dejar sus definiciones cuando se desinstalan. - NO elimines en bloque las definiciones sin uso sin buscar antes en el tema de la tienda referencias a ese `namespace.key`. El Liquid del tema puede leer una definición que todavía no tiene valores guardados (p. ej., un campo recién agregado que aún no se ha llenado). - Fija las definiciones más usadas (con `pinnedPosition`) para que aparezcan en el admin; tener definiciones muy usadas sin fijar es señal de una mala experiencia de uso. - Las claves duplicadas entre tipos de propietario no siempre están mal (p. ej., `custom.notes` en ORDER y en CUSTOMER puede ser intencional), pero casi siempre indican que se crearon copiando y pegando: revisa que `type` y `validations` sean consistentes. - Antes de cualquier limpieza, combínala con una skill que tome muestras de valores de metacampos (por tipo de propietario) para confirmar que de verdad no se usan; en tiendas nuevas los conteos pueden ir atrasados. - Guarda el CSV en control de versiones junto a la documentación del esquema del tema y las apps: la diferencia en el tiempo es el registro más claro de cómo evolucionan los datos del catálogo.