Documentación · Documentación técnica

Descripción general de la arquitectura

Este documento describe la arquitectura de alto nivel del plugin ADP Car Market Hub WordPress: cómo está organizado el árbol de fuentes, qué clases asumen las responsabilidades principales y cómo se conectan las características principales en tiempo de ejecución.

Cuándo usar este documento

Lea este documento si necesita:

  • Obtener una descripción general de la base de código PHP del plugin antes de profundizar en un subsistema específico.
  • Entender qué clase es responsable de una característica determinada.
  • Planificar una personalización, integración o revisión de código.
  • Para conocer el orden de inicialización paso a paso, consulte Plugin Bootstrap And Lifecycle.
  • Para detalles de almacenamiento, consulte Data Model y Database Schema.

Descripción general

El plugin está implementado en PHP y sigue las convenciones estándar de plugins de WordPress. Utiliza:

  • Un único archivo raíz (adp-car-market-hub.php) que define las constantes del plugin, registra un cargador automático (autoloader) y engancha los callbacks de inicialización.
  • Un espacio de nombres PHP AS24CI\ para todas las clases.
  • Las API principales de WordPress para tipos de contenido personalizados (custom post types), taxonomías, opciones, WP-Cron, REST API, manejadores AJAX y tablas personalizadas gestionadas por dbDelta.
  • Un singleton central AS24CI\Plugin que conecta todas las características en la acción plugins_loaded.

Estructura de directorios de nivel superior

El repositorio está organizado de la siguiente manera (solo se enumeran los directorios relevantes para la arquitectura en tiempo de ejecución):

  • adp-car-market-hub.php — archivo principal del plugin. Define constantes, registra el cargador automático, carga el dominio de traducción (text domain), registra los ganchos (hooks) de activación/desactivación, registra intervalos personalizados de WP-Cron e inicializa el singleton AS24CI\Plugin en plugins_loaded.
  • includes/ — clases PHP compartidas y del frontend, una clase por archivo. Los nombres de archivo siguen el patrón class-as24ci-<name>.php y se resuelven en la clase AS24CI\<Name> a través del cargador automático.
  • includes/admin/ — clases PHP exclusivas de la administración (pestañas de ajustes, ayudantes de tablas de listado, widgets del escritorio). Se resuelven mediante el mismo cargador automático como alternativa cuando no se encuentra una clase bajo includes/.
  • src/Core/Helpers.php — ayudantes procedimentales compartidos que se cargan incondicionalmente desde el archivo principal del plugin.
  • templates/ — plantillas de frontend y partes de plantillas que pueden ser anuladas por los temas.
  • assets/ — CSS, JavaScript e imágenes de administración y frontend.
  • languages/ — archivos de traducción; el dominio de traducción es adp-car-market-hub.
  • uninstall.php — se ejecuta cuando el plugin se elimina de WordPress y elimina las opciones del plugin y (opcionalmente) el contenido importado.

Cargador automático (Autoloader)

adp-car-market-hub.php registra un pequeño cargador automático compatible con PSR-4 para el prefijo AS24CI\. Los nombres de las clases se convierten a la convención de nomenclatura de archivos class-as24ci-<lower-case-name-with-dashes>.php. El cargador automático busca primero en includes/ y luego en includes/admin/, lo que permite que las clases compartidas y las exclusivas de administración compartan un único espacio de nombres.

Clases principales y sus responsabilidades

Las siguientes clases forman la columna vertebral del plugin. Los nombres se escriben en su forma completamente cualificada (AS24CI\<Class>).

Inicialización y servicios compartidos

  • AS24CI\Plugin — Punto de entrada Singleton. Construye las instancias de servicios compartidos (Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler), conecta todos los ganchos de WordPress para el conjunto de características activas y expone los callbacks estáticos activate() / deactivate() / init().
  • AS24CI\Logger — Registrador ligero (logger) utilizado en todo el plugin para los mensajes del importador y del programador.
  • AS24CI\Options — Registro centralizado de claves de opciones expuestas como constantes de clase (por ejemplo, Options::DB_VERSION, Options::DEFAULT_CURRENCY, Options::AUTO_IMPORT_ENABLED). El script uninstall.php utiliza Options::get_all_keys() para limpiar las opciones al eliminar el plugin.

Datos y almacenamiento

  • AS24CI\CPT — Registra el tipo de contenido personalizado as24ci_car con mapeo de capacidades personalizadas (as24ci_car / as24ci_cars) y la caja de metadatos (metabox) combinada "AutoScout24 API Import".
  • AS24CI\Taxonomies — Registra las 15 taxonomías de atributos de vehículos asociadas a as24ci_car (marca, modelo, tipo de carrocería, tipo de combustible, transmisión, tracción, estado, color exterior/interior, norma de emisiones, etiqueta energética, categoría de vehículo, tipo de garantía, detalles de la garantía, disposición de los cilindros).
  • AS24CI\Leads_CPT — Registra el tipo de contenido personalizado as24ci_lead utilizado para almacenar los envíos de formularios de contacto, con constantes de estado para new, contacted, closed y spam.
  • AS24CI\Vehicle_Repository — Repositorio para la tabla personalizada dedicada {$wpdb->prefix}as24_vehicles que contiene los datos de los campos del vehículo (en lugar de wp_postmeta). Proporciona gestión de esquemas (maybe_create_table()), ayudantes CRUD y listas blancas de filtrado/ordenación utilizadas por find().
  • AS24CI\Vehicle_Field_Resolver — Lector centralizado que resuelve los campos del vehículo combinando los datos del repositorio con las anulaciones manuales. Se conecta durante la construcción de Plugin a través de Vehicle_Field_Resolver::set_repository().
  • AS24CI\Vehicle_Deleter — Ruta de limpieza única e idempotente que se utiliza cada vez que se elimina permanentemente un vehículo (eliminación nativa de WP, eliminación por sincronización completa del importador, acción en lote). Se conecta durante la construcción de Plugin.

Flujo de importación (Pipeline)

  • AS24CI\Client — Cliente HTTP para la API de AutoScout24. Maneja la autenticación y la ejecución de solicitudes.
  • AS24CI\Mapper — Mapea las cargas de datos (payloads) de listados entrantes de AutoScout24 a la estructura de campos interna utilizada por el repositorio y escribe el postmeta _as24ci_listing_id para compatibilidad con versiones anteriores.
  • AS24CI\Importer — Coordina la importación por listado: obtiene datos a través de Client, los transforma a través de Mapper, persiste los vehículos a través del repositorio y realiza el seguimiento de la detección de cambios mediante las claves de postmeta _as24ci_content_hash y _as24ci_images_hash.
  • AS24CI\Image_Importer — Descarga y adjunta las imágenes de los vehículos, convirtiéndolas opcionalmente a WebP. Almacena los IDs de los adjuntos en el postmeta _as24ci_image_ids.
  • AS24CI\Scheduler — Propietario de los ganchos de WP-Cron as24ci_scheduled_import y as24ci_image_queue_process, los transitorios de bloqueo de ejecución (as24ci_cron_import_running, as24ci_image_queue_running) y el transitorio de la cola manual del asistente por lotes (Batch-Wizard) as24ci_batch_queue. El mismo flujo de run_import() es utilizado por WP-Cron, el endpoint cron de REST y el botón "Ejecutar ahora" de la administración.
  • AS24CI\Cron_Endpoint — Endpoint REST que permite a servidores externos activar importaciones a través de una URL protegida por token.

Frontend, SEO e integraciones

  • AS24CI\Templates — Enruta las plantillas de archivo y de vehículo individual a través del cargador de plantillas del plugin, permitiendo anulaciones por parte del tema.
  • AS24CI\Assets — Registra y encola los paquetes (bundles) de CSS y JavaScript de administración y frontend.
  • AS24CI\Archive_Filters — Renderiza la interfaz de usuario del filtro de archivo y aplica modificaciones de consulta basadas en las selecciones del usuario.
  • AS24CI\Schema — Añade datos estructurados de Schema.org y etiquetas meta de Open Graph / Twitter Card a las páginas de vehículos individuales. Opcional, condicionado por Options::FEATURE_SCHEMA.
  • AS24CI\Sitemap — Integra los vehículos en el mapa del sitio (sitemap) principal de WordPress y es compatible con Yoast y Rank Math. Opcional, condicionado por Options::FEATURE_SITEMAP.
  • AS24CI\Social_Share, AS24CI\Pdf_Datasheet, AS24CI\Favorites, AS24CI\Compare, AS24CI\Export, AS24CI\Bulk_Actions, AS24CI\Financing_Calculator, AS24CI\Test_Drive, AS24CI\Search_Agent — Características opcionales que registran cada una sus propios ganchos. La mayoría están condicionadas por un interruptor Options::FEATURE_* (consulte seed_safe_defaults() en AS24CI\Plugin para ver los valores predeterminados incluidos en una instalación nueva).
  • AS24CI\Webhooks — Webhooks salientes para casos de uso de CRM e integración.
  • AS24CI\Rest_Api — API REST pública para listados de vehículos, condicionada por Options::REST_API_ENABLED.
  • AS24CI\Analytics — Seguimiento de visitas a páginas, filtros y leads. Propietario de la tabla {$wpdb->prefix}as24ci_analytics y del cron de retención as24ci_daily_cleanup.
  • AS24CI\Ai_Assistant — Genera descripciones de IA, metadatos SEO y elementos destacados de equipamiento utilizando la configuración gestionada de Google Gemini expuesta por AS24CI\Ai_Config. La clave Gemini del cliente se entrega de servidor a servidor mediante la API Platform y se almacena encriptada a través de AS24CI\Ai_Credential_Manager; no se puede seleccionar ningún proveedor, modelo o clave de API en la interfaz de administración.
  • AS24CI\Data_Quality_Scanner — Detector opcional de errores tipográficos en taxonomías que utiliza la integración de IA.
  • AS24CI\Pricing_Engine — Análisis diario de precios que se ejecuta en el gancho as24ci_pricing_analysis_cron.
  • AS24CI\Locations, AS24CI\Seller_Profile_Fields — Ubicaciones del concesionario, horarios de apertura y metadatos del perfil del vendedor.
  • AS24CI\Team / AS24CI\Admin_Team — CMH Team: contactos de ventas del concesionario que no requieren cuentas de usuario de WordPress. El almacenamiento se basa en opciones (sin tabla personalizada ni CPT); los contactos se guardan en Options::TEAM_MEMBERS y claves de opciones relacionadas, imitando el patrón Locations. Admin_Team registra un menú de administración dedicado de nivel superior.
  • AS24CI\License_Manager, AS24CI\License_Client, AS24CI\License_Refresh_Signal, AS24CI\License_Signal_Secret — Licencia de la API Platform de ADP Car Market Hub / capa de acceso gestionado. License_Manager es propietario del cron de revalidación diaria (as24ci_license_refresh), el almacenamiento de derechos de características, el control de la ruta de escritura operativa/IA y los avisos de administración. License_Refresh_Signal expone el endpoint entrante POST /as24ci/v1/license-refresh-signal.
  • AS24CI\Ai_Credential_Manager — Almacena y desencripta la credencial de Gemini del cliente entregada por la API Platform.
  • Content Studio (AS24CI\Content_Studio_*, por ejemplo, Content_Studio_Repository, Content_Studio_Options, Content_Studio_Admin_Worker, Admin_Tab_Content_Studio) — Un módulo en gran parte autónomo que genera contenido de marketing a partir de los datos de vehículos existentes. Es propietario de sus propias tablas (as24ci_content_studio_jobs, as24ci_content_studio_assets), sus propias opciones as24ci_content_studio_* y un trabajador en segundo plano (background worker), y se inicializa desde el archivo principal del plugin en lugar del enrutador Admin. Lee los datos existentes de vehículos/importación en modo de solo lectura.

Interfaz de usuario de administración

  • AS24CI\Admin — Controlador de administración de nivel superior, instanciado solo cuando is_admin() es verdadero. Compone internamente las clases de pestañas de includes/admin/ (importador, ajustes, mapeo, diseño, gestor de diseño, leads, AI Assistant, estado del sistema, etc.).
  • AS24CI\Dashboard_Widget — Widget de escritorio opcional de WordPress, condicionado por Options::FEATURE_DASHBOARD_WIDGET.

Interruptores de características y "primera configuración segura"

La mayoría de las características no esenciales se registran condicionalmente en AS24CI\Plugin::register_hooks() basándose en opciones cuyas constantes se definen en AS24CI\Options (por ejemplo, FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED).

En una instalación nueva, el plugin establece valores predeterminados conservadores a través de AS24CI\Plugin::seed_safe_defaults(). Las características externas, de privacidad o por lotes están desactivadas por defecto; las características orientadas al frontend (mapa del sitio, esquema, favoritos, comparador, calculadora de financiación, widget del escritorio, exportación, carga diferida, gestor de diseño) están activadas por defecto. Las instalaciones existentes nunca se sobrescriben porque el sembrador (seeder) utiliza add_option().

Estructura de almacenamiento (nivel alto)

El plugin utiliza tres capas de almacenamiento:

  1. Tablas de base de datos personalizadas gestionadas a través de dbDelta: - {$wpdb->prefix}as24_vehicles — datos de campos de vehículos, propiedad de AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — eventos de analítica, propiedad de AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — suscripciones de alertas de búsqueda, propiedad de AS24CI\Search_Agent. - {$wpdb->prefix}as24ci_content_studio_jobs y {$wpdb->prefix}as24ci_content_studio_assets — tareas de Content Studio y recursos generados, propiedad de AS24CI\Content_Studio_Repository.
  2. Posts y postmeta de WordPress: - Los posts as24ci_car respaldan los enlaces permanentes, taxonomías y plantillas de WordPress para cada vehículo. Un pequeño conjunto de claves postmeta permanece en wp_postmeta por compatibilidad con versiones anteriores (por ejemplo, _as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids). - Los posts as24ci_lead almacenan los envíos de formularios de contacto con el estado almacenado en _as24ci_lead_status.
  3. wp_options — Todos los ajustes configurables por el usuario. Las claves se definen como constantes en AS24CI\Options (y, para Content Studio, en AS24CI\Content_Studio_Options). Las versiones de esquema para las tablas personalizadas también se almacenan como opciones (as24ci_db_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version). Los contactos de CMH Team también se almacenan en opciones (as24ci_team_*).

Para obtener detalles a nivel de columna, consulte Database Schema. Para el modelo de entidad lógica y cómo interactúan postmeta y la tabla personalizada, consulte Data Model.

Flujo de ejecución de un vistazo

Una solicitud típica pasa por las siguientes etapas (simplificadas):

  1. WordPress carga adp-car-market-hub.php, que define las constantes del plugin, registra el cargador automático (autoloader) y añade intervalos personalizados de WP-Cron.
  2. En plugins_loaded (prioridad 1) se carga el dominio de texto (text domain).
  3. En plugins_loaded (prioridad por defecto) se ejecuta AS24CI\Plugin::init(), instancia el singleton y registra todos los hooks para las características activas.
  4. Las clases de características registran sus propios hooks en init, rest_api_init, wp_ajax_*, wp_footer, etc.
  5. La actividad posterior (una ejecución de cron, una solicitud REST, una visualización de página en el frontend) es gestionada por los hooks registrados.

Notas operativas

  • El plugin asume las versiones de WordPress y PHP declaradas en la cabecera del plugin (Requires at least: 6.2, Requires PHP: 8.1). Las versiones inferiores no son compatibles.
  • La mayoría de los subsistemas utilizan wpdb directamente solo cuando dbDelta no puede expresar el esquema o la consulta requeridos. Las consultas directas se limitan al código de repositorio, analítica, agente de búsqueda y desinstalación.
  • La arquitectura mantiene deliberadamente la renderización del frontend separada de la importación de datos. El importador nunca renderiza plantillas; las plantillas nunca activan solicitudes de red a AutoScout24.
  • El plugin añade un enlace "Ajustes" a su fila en la pantalla de Plugins de WordPress a través del filtro plugin_action_links_<basename>.

Resolución de problemas

  • Una característica no parece registrarse. Compruebe el interruptor Options::FEATURE_* correspondiente. El método register_hooks() en AS24CI\Plugin omite las características desactivadas.
  • No se encuentra una clase. Verifique la convención de nomenclatura de archivos (class-as24ci-<lower-dashed-name>.php) y que el archivo se encuentre en includes/ o includes/admin/. El cargador automático solo busca en estos dos directorios.
  • Se hace referencia a una clase exclusiva de administración desde el frontend. Las clases de administración se cargan bajo demanda mediante el cargador automático, pero pueden depender de variables globales o capacidades exclusivas de administración. Verifique el comportamiento en la versión actual del plugin antes de depender de él.

Documentos relacionados