Arquitectura de producto del Plugin Catalog

Este documento recoge la arquitectura de producto y la planificación del MVP para la superficie propuesta plugins.webblocksui.com antes de que comience la implementación. Es únicamente documentación. No añade código en tiempo de ejecución, rutas, migraciones, controladores, clientes de API, tablas de base de datos, pantallas de interfaz, scripts de despliegue, trabajos en segundo plano, etiquetas de versión ni incrementos de versión.

plugins.webblocksui.com es la superficie pública propuesta del Plugin Catalog para el ecosistema WebBlocks. Debe ayudar a los usuarios a descubrir plugins, comprender sus metadatos, ver la compatibilidad con los productos anfitriones, revisar el historial de versiones y seguir una guía segura de instalación manual.

El primer objetivo es el descubrimiento, los metadatos, la visibilidad de la compatibilidad y una guía segura de instalación manual mediante ZIP. No debe comenzar como un mercado comercial y no debe dar a entender que existe instalación remota automática de plugins en WebBlocks CMS, QuizTem, Herne Panel, WebBlocks Publisher ni en ningún otro producto anfitrión.

El lenguaje del producto debe distinguir tres etapas:

• Plugin Catalog: explorar, buscar y descubrir plugins; leer metadatos, compatibilidad, notas de la versión, capturas de pantalla, documentación y enlaces de descarga.
• Plugin Store: posteriormente, integración de confianza de instalación/actualización desde los metadatos del catálogo hacia los productos anfitriones.
• Marketplace: futura capa comercial con proveedores, cuentas, licencias, pagos, aprobaciones, valoraciones y distribución de plugins de pago.

El producto a corto plazo debe llamarse Plugin Catalog, no Marketplace. El lenguaje de Marketplace debe reservarse para las funciones comerciales aplazadas.

Ventajas:

• límite de producto claro
• hoja de ruta independiente
• la propiedad de la API y del catálogo a largo plazo resulta más sencilla

Inconvenientes:

• más trabajo de configuración y operación
• gestión de contenido, administración, despliegue y mantenimiento por separado

Ventajas:

• reutiliza los conceptos de publicación de actualizaciones
• puede reutilizar los patrones de artefactos, sumas de comprobación, metadatos de versión y manifiestos

Inconvenientes:

• corre el riesgo de hacer que WebBlocks Publisher abarque demasiado
• los aspectos del catálogo de plugins difieren de la publicación de actualizaciones de producto
• el descubrimiento del catálogo, las matrices de compatibilidad y las páginas públicas de plugins pueden alejar a Publisher de su función principal de producto

Ventajas:

• demuestra las capacidades de WebBlocks CMS
• las páginas de contenido son fáciles de gestionar
• el Plugin Catalog puede poner a prueba el propio sistema de plugins

Inconvenientes:

• requiere un plugin de catálogo
• necesita una separación cuidadosa entre la gestión de contenido público y la autoridad sobre artefactos y catálogo
• debe evitar que la edición de contenido del CMS se convierta en la autoridad sobre la seguridad de artefactos ejecutables

El modelo híbrido serviría las páginas públicas de marketing y de contenido desde WebBlocks CMS, mientras que la API del catálogo y los metadatos de los artefactos se servirían desde un servicio de catálogo dedicado o desde un backend derivado de Publisher.

Puede ser la dirección más práctica a largo plazo, pero sigue siendo una dirección, no un compromiso de implementación.

Documente plugins.webblocksui.com como una superficie de producto del ecosistema con un límite claro. Comience con un MVP centrado en el catálogo: descubrimiento, metadatos, visibilidad de la compatibilidad, notas de la versión, sumas de comprobación, documentación y guía de descarga manual.

La implementación puede comenzar como una aplicación Laravel dedicada o como un plugin de catálogo basado en WebBlocks CMS, pero el contrato de datos no debe depender de una única implementación de interfaz. Los conceptos de WebBlocks Publisher deben seguir siendo reutilizables, especialmente los metadatos de versión y las ideas de verificación de artefactos, sin suponer que el Plugin Catalog deba residir dentro de Publisher.

Los siguientes conceptos son únicamente de nivel de planificación. No implican tablas de base de datos, API, modelos, migraciones ni pantallas de administración en el repositorio actual.

• identificador (handle)
• etiqueta
• resumen
• descripción
• proveedor/autor
• URL del sitio web
• URL de la documentación
• URL de soporte
• tipo de licencia
• categorías
• etiquetas
• estado: borrador, listado, no listado, obsoleto, suspendido
• fecha de primera publicación
• fecha de la última versión

• nombre
• slug
• sitio web
• contacto de soporte
• estado verificado
• página de perfil pública
• futura elegibilidad comercial, aplazada

• clave del producto, por ejemplo webblocks-cms, quiztem, herne-panel o webblocks-publisher
• etiqueta del producto
• rangos de versiones admitidos
• reglas de visibilidad en el catálogo

• identificador del plugin
• versión
• canal: stable, beta, alpha, dev
• fecha de publicación
• notas de la versión
• matriz de compatibilidad
• versión de PHP/Laravel requerida cuando proceda
• URL del artefacto
• suma de comprobación
• futuros metadatos de firma
• notas de migración
• notas sobre cambios incompatibles
• notas de seguridad
• notas de obsolescencia

• ruta de almacenamiento o URL
• suma de comprobación
• tamaño
• MIME/tipo
• formato del paquete
• metadatos del manifiesto
• estado de validación
• estado del análisis
• estado de publicación

• productos anfitriones admitidos
• versiones requeridas del producto anfitrión
• versiones incompatibles del producto anfitrión
• restricciones de PHP/Laravel cuando sean relevantes
• extensiones necesarias
• identificadores de plugins en conflicto
• dependencias de plugins requeridas, si en el futuro se aprueba su soporte

• identificador del plugin
• versiones afectadas
• gravedad
• estado
• versión corregida
• resumen público
• acción recomendada para el operador

Las futuras páginas públicas de la superficie propuesta plugins.webblocksui.com pueden incluir:

• Página de inicio
• Listado de plugins
• Páginas de categorías
• Resultados de búsqueda
• Página de detalle del plugin
• Página del historial de versiones
• Página de perfil del proveedor
• Páginas de compatibilidad con productos anfitriones
• Páginas de documentación / guía de instalación
• Página de avisos de seguridad
• Guía sobre plugins obsoletos o retirados
• Futuras páginas de marketplace, explícitamente aplazadas

Las páginas de detalle del plugin deben incluir:

• nombre del plugin
• resumen
• capturas de pantalla
• productos anfitriones admitidos
• última versión compatible
• versiones requeridas del producto anfitrión
• notas de la versión
• permisos solicitados
• migraciones declaradas
• rutas, ajustes, comandos y recursos declarados
• método de instalación
• información de descarga y suma de comprobación
• estado de seguridad/obsolescencia
• enlaces de soporte y documentación

Las futuras pantallas del operador del catálogo pueden incluir:

• Plugins
• Proveedores
• Versiones
• Artefactos
• Compatibilidad
• Avisos de seguridad
• Categorías/Etiquetas
• Cola de revisión, aplazada
• Comercial/Licencias, aplazado

Se trata de conceptos de planificación del catálogo y de la administración, no de tareas de implementación de la administración del CMS.

Los futuros endpoints de API de solo lectura pueden incluir:

• GET /api/plugins
• GET /api/plugins/{handle}
• GET /api/plugins/{handle}/releases
• GET /api/plugins/{handle}/latest?host_product=webblocks-cms&version=...
• GET /api/host-products
• GET /api/security-advisories
• GET /api/catalog/index

La API V1 debe ser de solo lectura para los productos anfitriones. Las respuestas de la API nunca deben provocar por sí solas una instalación remota, la activación de plugins, la ejecución de migraciones, la aplicación de actualizaciones, una instalación arbitraria con Composer ni ningún comportamiento ejecutable.

Los futuros endpoints de publicación/operador son independientes y quedan aplazados:

• publicar una versión de plugin
• subir un artefacto
• aprobar una ficha
• suspender una ficha
• emitir un aviso

WebBlocks CMS y otros productos anfitriones pueden consumir el Plugin Catalog para:

• explorar el catálogo desde la administración del anfitrión
• mostrar la compatibilidad del plugin antes de la descarga/instalación
• enlazar con la descarga manual del ZIP
• comparar las versiones de los plugins instalados con las versiones del catálogo
• mostrar advertencias de seguridad/obsolescencia para los plugins instalados
• admitir flujos controlados de instalación/actualización solo cuando los productos anfitriones vuelvan a comprobar los metadatos de artefactos de confianza, verifiquen las sumas de comprobación, validen los paquetes y exijan acciones explícitas del operador

La exploración del catálogo no debe requerir que la gestión de plugins instalados esté en línea. La gestión de plugins instalados debe funcionar sin disponibilidad del catálogo. Los productos anfitriones deben almacenar en caché los metadatos del catálogo de forma defensiva, y los metadatos remotos no deben considerarse comportamiento ejecutable de confianza.

El futuro flujo de mantenedor/operador puede incluir:

• preparar el artefacto del plugin localmente
• validar el manifiesto del plugin
• validar la forma del paquete
• calcular la suma de comprobación
• subir el artefacto y los metadatos
• el catálogo verifica la compatibilidad y la seguridad del artefacto
• la versión solo se lista tras la aprobación explícita del operador o mediante un flujo de publicación propio de confianza

Esto se parece a las ideas de WebBlocks Publisher sobre metadatos de actualización, pero la publicación en el catálogo de plugins debe seguir siendo una capacidad independiente, salvo que una decisión posterior las unifique.

Un primer MVP práctico debe incluir:

• entradas de plugins estáticas o gestionadas por el catálogo
• páginas públicas de listado y de detalle de plugins
• metadatos de las versiones de los plugins
• matriz de compatibilidad
• enlaces de descarga manual
• sumas de comprobación visibles
• enlaces a la documentación
• sin instalación remota automática desde el CMS
• sin marketplace de pago
• sin licencias
• sin publicación autogestionada por terceros
• sin aplicación automática de actualizaciones

Esta fase de planificación no incluye:

• la implementación en esta tarea
• el despliegue en producción real
• la instalación remota automática de plugins
• la activación automática de plugins
• la ejecución automática de migraciones de plugins
• la aplicación automática de actualizaciones de plugins
• la instalación arbitraria con Composer
• un marketplace de pago
• un servidor de licencias
• un portal de autoservicio para proveedores
• valoraciones/reseñas
• la automatización de la publicación de artefactos en producción
• la verificación en el sitio en vivo

• ¿Debe plugins.webblocksui.com comenzar como una aplicación Laravel dedicada o como un plugin de catálogo basado en el CMS?
• ¿Debe WebBlocks Publisher encargarse de la publicación de artefactos de plugins, o debe el Plugin Catalog tener su propio flujo de publicación?
• ¿Deben los plugins propios y los de terceros tener flujos de aprobación distintos?
• ¿Cómo deben gestionarse las firmas de los plugins?
• ¿Cómo debe introducirse más adelante la concesión de licencias comerciales sin cambiar el contrato del catálogo?
• ¿Cómo deben representarse los plugins privados o internos?
• ¿Cómo deben declarar los plugins multi-anfitrión sus proveedores y su compatibilidad por anfitrión?