Guía para el Desarrollo de Componentes de Quartup normalizados

0. Contexto Actual: Arquitectura Legacy de Componentes

Los actuales Componentes Legacy de Quartup son extensiones de las aplicaciones de Quartup, diseñadas para una funcionalidad específica y autocontenida (generalmente representada en un bloque contíguo de opciones de un menú, y operando sobre un conjunto de tablas dedicadas). Un ejemplo de componentes actuales son la gestión de cartera o la gestión de impuestos dentro de la aplicación de gestión comercial.

El principal desafío de esta arquitectura reside en su estructura monolítica: las clases del componente se integran y mezclan directamente con el código base de la aplicación principal de la que dependen.

Esta integración estrecha y sin segregación de responsabilidades provoca:

1. Componentes de Quartup Normalizados: Un Enfoque Moderno

Los Componentes de Quartup Normalizados representan la evolución de los componentes Legacy, adoptando un estilo de desarrollo moderno y una arquitectura flexible.

El objetivo de esta normalización es establecer una estructura clara y separada de responsabilidades dentro del componente. Esto se logra mediante:

Este nuevo enfoque garantiza una mayor facilidad de gestión, productividad y mantenibilidad a largo plazo.

2. Definición y Creación del Componente (Guía Práctica)

Para ilustrar este proceso, utilizaremos el componente Sed (Sistemas Externos de Documentos) de la aplicación p_cial (Gestión Comercial), que gestiona funcionalidades clave como el sistema Veri-Factu, y añadiremos algunos bloques de componentes de la aplicación p_pos para presentar una relación exhaustiva de los directorios usables en cualquier componente.

2.1. Nomenclatura del Componente

El componente debe crearse como un subdirectorio dentro del directorio de la aplicación (/p_cial).

Regla Legacy: El nombre del directorio debe corresponder con el prefijo de las tablas (Modelos de datos) que usará el componente (en este ejemplo Sed/, con tablas como sedcon, sedemp, o Pos/, con tablas como postie, posart).

Aplicación Directorio Aplicación Nombre del Componente Directorio del Componente Prefijo de Tablas
p_cial /p_cial/ Sed /p_cial/Sed/ sed
p_pos /p_pos/ Pos /p_pos/Pos/ pos

2.2. Estructura Estándar del Directorio

El componente debe seguir una Arquitectura de Capas con la siguiente jerarquía de directorios. Esta estructura separa las responsabilidades del Modelo, la Lógica y los Mecanismos de Persistencia.

Ejemplo de Estructura con los directorios normalizados más comunes:

p_cial/                                     // Aplicación
└── Sed/                                    // Raíz del Componente (PascalCase)
    ├── Columns                                     // Definiciones de Columnas especiales de Tablas
    │   └── ServiceTypeColumn.php
    ├── Models                                      // Definiciones de Tablas (Persistencia)
    │   ├── sedcon.php
    │   └── sedemp.php
    ├── ModelAugments                               // Ampliación de Models de otros Componentes, añadiendo más campos/índices/módulos
    │   ├── MaesartiPosStructureModelAugment.php
    │   └── MaesartiPosModulesModelAugment.php
    ├── ModelExtensions                             // Extensiones de clase Models reutilizables
    │   └── PostieDefault.php
    ├── Hooks                                       // Gestión de Eventos
    │   ├── Sedempser2sedempconHook.php
    │   └── Sedcue2DocuHubCustomerHook.php
    ├── DTOs                                        // DTOs
    │   └── SedcueDTO.php
    ├── Services                                    // Cálculos de lógica de negocio, pero sin persistencia
    │   └── Sedempser2sedempconService.php
    ├── Actions                                     // Acciones de lógica de negocio Adaptada a Eventos
    │   ├── SedcueStore.php
    │   ├── SedfacvenStore.php
    │   └── SedvefxxxStore.php
    └── Helpers                                     // Clases que aglutinan métodos variados habitualmente estáticos
        └── StocksHelper.php

3. Responsabilidades de las Capas y Nomenclaturas

Dentro del directorio Sed/, cada subdirectorio agrupa clases con una responsabilidad funcional clara:

Directorio Responsabilidad Principal Clase Padre (Kernel) Traits Sufijo Clase
Columns/ Definición de algunas columnas y su tipo de dato dentro de un Model. QU_ColReal, QU_ColLink Column
Models/ Definición de las tablas del componente. Representan la capa de Persistencia pura. QU_Table
ModelAugments/ Ampliación de otras clases Models, añadiendo más campos/índices/módulos. ItieStructure, ItieModules ModelAugment
ModelExtensions/ Extensiones de clase Models reutilizables. (Clases Propias)
Hooks/ Contiene clases para manejar eventos de persistencia (INSERT/UPDATE/DELETE) y de transacción. ITieIUD, ITieTransaction Hook
DTOs/ Contiene clases DTO. (Clases Propias) ArrayableTrait, AutoAssignPropertiesTrait DTO
Services/ Contiene la lógica de negocio sin persistencia. (Clases Propias) Service
Actions/ Contiene la lógica de negocio adaptada que se ejecuta como respuesta a eventos (Hooks), como la creación automática de datos. (Clases Propias)
Helpers/ Clases que aglutinan métodos variados habitualmente estáticos. (Clases Propias) Helper

4. Uso de Namespaces (PSR-4)

Es obligatorio utilizar namespaces en todas las clases de la extensión (salvo en los Models debido a restricciones del Legacy), siguiendo la recomendación PSR-4. Esto mantiene el código organizado y evita conflictos de nombres.

4.1. Regla de Nomenclatura del Namespace

El namespace base debe formarse uniendo el nombre de la aplicación y el nombre del componente.

  1. La aplicación (p_cial) debe capitalizar las dos iniciales y eliminar el guion bajo: PCial.
  2. El nombre del componente (Sed) se añade directamente: PCial\Sed.

Por lo tanto, el namespace base para este componente es PCial\Sed\. A partir de ahí, se definen sub-namespaces según la estructura de directorios.

Ejemplo de Código (Hook):

// Fichero: /p_cial/Sed/Hooks/Sedcue2DocuHubCustomerHook.php
namespace PCial\Sed\Hooks;    // Namespace base + Directorio

use App\DocuHub\Clients\ClientCustomer;
use ItieIUD;
// ... otras importaciones del Kernel

/**
 * PHP version 7
 *
 * @package    Quartup
 * ...
 */
class Sedcue2DocuHubCustomerHook implements ItieIUD
{
    // ... lógica del Hook
}

5. Carga de Clases (Autoloading)

Restricción y Particularidad de Quartup:

A diferencia de un proyecto estándar de PHP, no se debe utilizar composer.json ni Composer para la carga de clases (autoloading).

El sistema de Quartup se encarga de interpretar los namespaces que has definido y de cargar las clases automáticamente. Esta es una particularidad del entorno de Quartup que simplifica el proceso, evita conflictos, y se integra totalmente con el sistema Legacy de autoloading.