Skip to main content

1. Introducción

1.1. Propósito y alcance​

El presente sistema constituye una arquitectura API basada en PHP diseñada para modernizar y estandarizar el acceso a los sistemas legacy de la plataforma Quartup. Su propósito principal es proporcionar una capa de abstracción que facilite la interacción con la infraestructura existente a través de interfaces RESTful modernas, manteniendo la compatibilidad con Quartup.

Esta API se ha concebido como un puente tecnológico que permite:

  • Facilitar la migración progresiva desde el sistema legacy hacia arquitecturas modernas
  • Proporcionar endpoints RESTful estandarizados para consumo por parte de clientes diversos
  • Implementar patrones de diseño actuales que mejoran la mantenibilidad y extensibilidad
  • Establecer una capa de seguridad homogénea y robusta

La arquitectura está diseñada para ser modular y extensible, permitiendo la incorporación de nuevos dominios de negocio sin afectar al núcleo operativo.

1.2. Visión general del sistema​

La arquitectura del sistema se basa en una implementación moderna de principios de diseño orientados a objetos, siguiendo una estructura de capas claramente definidas:

  1. Capa de presentación (API): Expone los endpoints RESTful y gestiona las interacciones HTTP, implementada principalmente a través de controladores y rutas.

  2. Capa de aplicación: Coordina la lógica de negocio a través de servicios e implementa casos de uso específicos.

  3. Capa de dominio: Contiene las entidades y reglas de negocio fundamentales organizadas en dominios funcionales.

  4. Capa de infraestructura: Gestiona la comunicación con el legacy, a través de repositorios y modelos, y es el lugar indicado para implementar conectividad con otras fuentes de datos.

El sistema implementa varios patrones de diseño fundamentales:

  • Patrón Repositorio: Abstrae el acceso a datos, permitiendo una separación clara entre la lógica de negocio y la persistencia.
  • Patrón Servicio: Implementa la lógica de negocio asociada a los diferentes dominios.
  • Data Transfer Objects (DTOs): Facilitan la transferencia de datos entre capas, encapsulando y validando estructuras.
  • Middleware Pipeline: Proporciona un mecanismo flexible para procesar solicitudes HTTP.
  • Dependency Injection: Facilita la gestión de dependencias y mejora la testabilidad del código.

La organización estructural del sistema se divide en:

  • ApiLayer: Contiene los elementos expuestos a través de la API.

    • Domains: Agrupa la funcionalidad por dominios de negocio independientes.
    • Modules: Implementa funcionalidades transversales que pueden abarcar varios dominios.

  • App: Contiene los componentes fundamentales del framework.

    • Core: Implementa el núcleo del sistema (router, container, kernel).
    • Middlewares: Define los interceptores de peticiones.
    • Base: Proporciona clases base para los diferentes patrones implementados.
    • Helpers: Incluye utilidades y funciones auxiliares.

  • Infrastructures: Gestiona la comunicación con fuentes de datos.

    • Legacy: Contiene adaptadores para el sistema Quartup existente.

1.3. Requisitos técnicos​

El sistema requiere un entorno con las siguientes características para su correcto funcionamiento:

Requisitos de servidor​

  • PHP: Versión 7.2
  • MySQL/MariaDB: Compatible con el esquema de base de datos utilizado por Quartup
  • Servidor web: Apache o Nginx con soporte para PHP-FPM
  • Extensiones PHP requeridas:
    • PDO y PDO_MySQL
    • mbstring
    • json
    • OpenSSL (para funcionalidades JWT)
    • session

Dependencias principales​

  • Symfony Components:
    • symfony/console: Para herramientas CLI
    • symfony/http-foundation: Objetos Request y Response
  • JWT: Biblioteca para manejo de tokens de autenticación
  • GuzzleHTTP: Cliente HTTP para comunicaciones externas

Requisitos de desarrollo​

  • Entorno de desarrollo compatible con PHP 7.2
  • Herramientas de desarrollo:
    • Acceso al comando 'artesano' para generación de código
  • Comprensión de los constructores de las "Clases-Tablas" de Quartup

1.4. Convenciones y nomenclatura​

El sistema sigue un conjunto coherente de convenciones de nomenclatura para facilitar su comprensión y mantenimiento:

Estructura de archivos y directorios​

  • CamelCase: Utilizado para nombres de clases y archivos PHP (ej. ProductsController.php)
  • snake_case: Utilizado para nombres de tablas en la base de datos (ej. posarttic_v)
  • kebab-case: Utilizado en URLs y rutas de API (ej. /permut/products/)

Convenciones de código​

  • PSR-4: Autoloading estándar de PHP para clases
  • Namespaces: Reflejan la estructura de directorios (ej. ApiLayer\Domains\Products)
  • Interfaces: Sufijo "Interface" para todas las interfaces (ej. RepositoryInterface)
  • Traits: Sufijo "Trait" para todos los traits (ej. CollectionTrait)
  • Clases abstractas: Prefijo "Base" para clases base (ej. BaseModel)

Convenciones de API​

  • Rutas RESTful: Siguen convenciones estándar:

    • GET /recurso/ - Listar recursos
    • GET /recurso/:id - Obtener un recurso específico
    • POST /recurso/ - Crear un nuevo recurso
    • PUT /recurso/:id - Actualizar un recurso existente
    • DELETE /recurso/:id - Eliminar un recurso

  • Request/Response:

    • Cuerpo de solicitud en JSON para operaciones POST/PUT
    • Respuestas siempre en formato JSON con estructura consistente: 
      {
        "collection": [...],  // Para colecciones
        "totalRows": 100,     // Metadata para paginación
        "pages": 10,
        "page": 1,
        "itemsPerPage": 10
      }
    • Códigos HTTP estándar para respuestas:
      • 200: Éxito general
      • 201: Recurso creado
      • 400: Error en la solicitud
      • 401: No autorizado
      • 404: Recurso no encontrado
      • 500: Error del servidor

Patrones de nomenclatura específicos​

  • DTOs:
    • Req{Entidad}DTO para DTOs de entrada
    • Res{Entidad}DTO para DTOs de salida
  • Repositorios: {Entidad}Repository
  • Servicios: {Entidad}Service
  • Controladores: {Entidad}Controller
  • Modelos: {Entidad}Model
  • Validadores: {Tipo}Validator

Estilo de codificación​

  • Indentación: 4 espacios
  • Apertura de llaves: Nueva línea para clases y funciones, misma línea para estructuras de control
  • Uso coherente de espacios alrededor de operadores
  • Comentarios DocBlock para clases y métodos públicos
  • Longitud máxima de línea recomendada: 100 caracteres

Estas convenciones y estándares se aplican consistentemente en todo el código base para asegurar legibilidad y facilitar el mantenimiento por parte de diferentes equipos de desarrollo.