Componentes de Quartup normalizados

Guía para el Desarrollo de Componentes de Quartup normalizados

0. Contexto Actual: Componentes y Arquitectura Legacy de Componentes

A. Componentes

Los Componentes 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 son la gestión de cartera, la gestión de impuestos, la gestión de la E-factura, todos ellos dentro de la aplicación de gestión comercial.

B. Componentes Legacy

Los Componentes Legacy de Quartup son Componentes que no están normalizados de ninguna forma específica, y todos los Componentes de una misma aplicación se encuentran mezclados. Solo hay separación a nivel de Aplicacion, pero no a nivel de Componente.
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:
- Dificultad de Gestión: El acoplamiento eleva la complejidad y el riesgo en el mantenimiento.
- Baja Comodidad de Desarrollo: Ralentiza el trabajo del equipo e impacta negativamente la productividad.

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:

Una organización de clases en directorios con nomenclaturas estandarizadas.
Una separación física que aísla el código del componente del resto de la aplicación, mejorando la modularidad.

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 ConciliacionesFinancieras de la aplicación p_cial, y añadiremos algunos bloques de otros componentes 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 (en nuestro ejemplo: /p_cial).

Regla de Lenguaje Ubicuo: El nombre del directorio debe tener una nomenclatura clara, con la terminología usada por los miembros del equipo (desarrolladores, expertos de negocio, analistas, probadores, etc.) y es una norma propuesta dentro del Domain-Driven Design.

Convención: Usaremos la inicial capitalizada para el directorio, siguiendo un estilo moderno (PascalCase).

Las tablas, al desarrollarse dentro del Legacy tendrán la nomenclatura del Legacy, y han de seguir las convenciones del mismo. Lo habitual es que cada componente use un prefijo de tablas independiente, pero no siempre es así. Lo que sí es imprescindible es que cada aplicación tenga un prefijo de tablas totalmente independiente de las demás.

Aplicación	Directorio Aplicación	Nombre del Componente	Directorio del Componente	Prefijo Tablas Componente	Prefijo Tablas Aplicación
`p_cial`	`/p_cial/`	`ConciliacionesFinancieras`	`/p_cial/ConciliacionesFinancieras/`	`cialtraf`	`cial`
`p_pos`	`/p_pos/`	`FacturasVentas`	`/p_pos/FacturasVentas/`	`posfac`	`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 posibles (cada componente creará/usará solo los que necesite):

p_cial/                                             // Aplicación
└── ConciliacionesFinancieras/                      // Raíz del Componente (PascalCase)
    ├── Columns                                     // Definiciones de Columnas especiales de Tablas
    │   └── ServiceTypeColumn.php
    ├── Models                                      // Definiciones de Tablas (Persistencia)
    │   ├── cialtrafmov.php
    │   └── cialtrafcop.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
    ├── Persistence                                 // Definiciones de procesos SQL persistentes (Stored functions/procedures)
    │   └── CialtrafmovSqlStoredLogic.php
    ├── Hooks                                       // Gestión de Hooks
    │   ├── 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 estáticos
        └── StocksHelper.php

3. Responsabilidades de las Capas y Nomenclaturas

Dentro del directorio ConciliacionesFinancieras/, 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)
`Persistence/`	Definiciones de procesos SQL persistentes.	`SqlStoredLogicInterface`		SqlStoredLogic
`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)		Action Manager
`Helpers/`	Clases que aglutinan métodos variados 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.

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

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

Ejemplo de Código (Hook):

// Fichero: /p_cial/ConciliacionesFinancieras/Hooks/Cialtrafmov2reconciliacionHook.php
namespace PCial\ConciliacionesFinancieras\Hooks;    // Namespace base + Directorio

use ItieIUD;
// ... otras importaciones del Kernel

/**
 * PHP version 7
 *
 * @package    Quartup
 * ...
 */
class Cialtrafmov2reconciliacionHook 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.