Arquitectura del Sistema

Proyecto

Sistema de Gestión de Reparaciones - Plugin completo de WordPress para talleres de reparación de dispositivos electrónicos. Versión actual: 1.0.0 (MVP completo, ~27,500 líneas de código).

Entorno de Desarrollo

Este es un plugin de WordPress. Para trabajar en el proyecto:

# Copiar el plugin a WordPress
cp -r "SISTEMA DE REPARACIONES" /path/to/wordpress/wp-content/plugins/sistema-reparaciones

# Activar desde WordPress Admin → Plugins
# Esto creará automáticamente:
# - 11 tablas en la base de datos (prefijo wp_sr_*)
# - 5 roles personalizados (sr_shop_owner, sr_manager, sr_technician, sr_receptionist, sr_customer)
# - Configuración por defecto en wp_options

Requisitos

WordPress 6.0+
PHP 7.4+
MySQL 5.7+

Debugging

Habilitar en wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Los logs aparecerán en /wp-content/debug.log.

Arquitectura del Sistema

Estructura de Alto Nivel

sistema-reparaciones.php          # Plugin principal (define constantes, inicia SR_Core)
├── includes/
│   ├── class-core.php           # Orquestador principal, carga dependencias y registra hooks
│   ├── class-loader.php         # Sistema de hooks centralizado
│   ├── class-activator.php      # Crea tablas, roles y configuración
│   ├── database/
│   │   └── class-database.php   # Definición de 11 tablas SQL
│   ├── models/                  # Modelos de datos (CRUD)
│   │   ├── class-shop.php
│   │   ├── class-customer.php
│   │   ├── class-device.php
│   │   ├── class-repair-order.php  # MODELO CENTRAL
│   │   ├── class-part.php
│   │   ├── class-budget.php
│   │   └── class-invoice.php
│   ├── admin/                   # Panel de administración
│   │   ├── class-admin.php      # Enqueue de CSS/JS, AJAX handlers
│   │   ├── class-menu.php       # Menús de WordPress
│   │   └── pages/               # Páginas CRUD
│   ├── public/                  # Frontend público
│   │   ├── class-public.php
│   │   └── shortcodes/          # [sr_tracking_form], [sr_customer_portal], [sr_budget_request]
│   ├── api/                     # REST API con JWT
│   │   ├── class-api-controller.php
│   │   └── class-authentication.php
│   ├── notifications/           # Sistema de emails
│   │   ├── class-email-manager.php
│   │   └── templates/           # Plantillas HTML de emails
│   ├── pdf/                     # Generación de PDF
│   │   ├── class-pdf-generator.php
│   │   └── templates/
│   └── utils/
│       ├── class-validator.php  # 20+ métodos de validación
│       └── class-sanitizer.php  # 25+ métodos de sanitización
├── assets/
│   ├── css/
│   │   ├── admin.css
│   │   └── public.css
│   └── js/
│       ├── admin.js
│       └── public.js
└── templates/                   # Plantillas PHP para imprimir

Flujo de Ejecución

Activación del Plugin (SR_Activator::activate()):
- Crea 11 tablas en la BD
- Crea 5 roles con 20+ capabilities
- Inserta configuración por defecto en wp_options (moneda, prefijos de facturas, etc.)
Inicialización (SR_Core::__construct()):
- Carga dependencias usando safe_require() (silencioso si falta archivo)
- Registra hooks de admin (define_admin_hooks())
- Registra hooks públicos (define_public_hooks())
- Registra hooks de API REST (define_api_hooks())
- Registra hooks de notificaciones (define_notification_hooks())
Sistema de Hooks (SR_Loader):
- Centraliza todos los add_action() y add_filter()
- Ejecuta todos los hooks en SR_Loader::run()

Base de Datos

Las 11 tablas tienen prefijo wp_sr_ (definidas como constantes SR_TABLE_*):

Entidades Principales:

shops - Tiendas/talleres (multi-tienda)
customers - Clientes (individual/business)
devices - Dispositivos (marca, modelo, IMEI, accesorios JSON)
repair_orders - TABLA CENTRAL (órdenes de reparación con estados: pending → diagnosis → in_progress → completed → delivered)
parts - Repuestos (SKU, stock, precios)

Relaciones:

order_parts - Repuestos usados en órdenes (N:M)
stock_movements - Historial de inventario (in/out/adjustment)
budgets - Presupuestos con line_items JSON
invoices - Facturas con line_items JSON
status_history - Historial de cambios de estado
notifications - Log de emails enviados

Importante: SIEMPRE filtrar por shop_id en queries (soporte multi-tienda).

Sistema de Roles y Permisos

5 roles con capabilities granulares:

Rol	Capabilities Clave
`sr_shop_owner`	Todos (25 caps) incluyendo `sr_manage_settings`, `sr_manage_shops`
`sr_manager`	Gestión completa SIN `sr_manage_settings` ni `sr_manage_shops`
`sr_technician`	Solo `sr_view_orders`, `sr_edit_assigned_orders`
`sr_receptionist`	`sr_create_orders`, `sr_view/create_customers`, `sr_create_budgets`
`sr_customer`	Solo `sr_view_own_orders`

Al crear funcionalidades que modifiquen datos, verificar capabilities:

if ( ! current_user_can( 'sr_edit_orders' ) ) {
    wp_die( __( 'No tienes permiso.', 'sistema-reparaciones' ) );
}

Patrones de Código

Modelos (CRUD Pattern)

Todos los modelos siguen este patrón (ver class-shop.php, class-customer.php):

class SR_Model_Name {
    public static function get( $id ) { /* SELECT por ID */ }
    public static function get_by_shop( $shop_id ) { /* SELECT filtrado */ }
    public static function create( $data ) {
        // 1. Validar con SR_Validator
        // 2. Sanitizar con SR_Sanitizer
        // 3. INSERT con $wpdb->insert()
        // 4. Disparar hook: do_action('sr_model_created', $id)
        return $id;
    }
    public static function update( $id, $data ) {
        // Similar a create()
        // 5. Disparar hook: do_action('sr_model_updated', $id)
    }
    public static function delete( $id ) { /* Soft delete o DELETE */ }
}

Validación y Sanitización

CRÍTICO: SIEMPRE usar antes de guardar en BD:

// Validación (returns true/false)
if ( ! SR_Validator::is_required( $data['name'] ) ) {
    return new WP_Error( 'missing_name', 'El nombre es obligatorio' );
}
if ( ! SR_Validator::is_valid_email( $data['email'] ) ) {
    return new WP_Error( 'invalid_email', 'Email no válido' );
}

// Sanitización (devuelve valor limpio)
$clean_data = array(
    'name'  => SR_Sanitizer::sanitize_text( $data['name'] ),
    'email' => SR_Sanitizer::sanitize_email( $data['email'] ),
    'phone' => SR_Sanitizer::sanitize_phone( $data['phone'] ),
    'price' => SR_Sanitizer::sanitize_price( $data['price'] ),
);

Ver class-validator.php (20+ métodos) y class-sanitizer.php (25+ métodos).

Páginas de Admin

Las páginas en includes/admin/pages/ siguen esta estructura:

// 1. Verificar permisos
if ( ! current_user_can( 'sr_view_orders' ) ) {
    wp_die( __( 'No tienes permiso.', 'sistema-reparaciones' ) );
}

// 2. Procesar formulario (POST)
if ( $_SERVER['REQUEST_METHOD'] === 'POST' ) {
    check_admin_referer( 'sr_create_order' ); // Verificar nonce
    // Validar, sanitizar, guardar
}

// 3. Obtener datos
$shop_id = get_user_meta( get_current_user_id(), 'sr_shop_id', true );
$orders = SR_Repair_Order::get_by_shop( $shop_id );

// 4. Renderizar HTML con escape
echo '<h1>' . esc_html__( 'Órdenes', 'sistema-reparaciones' ) . '</h1>';
// ... tabla con WP_List_Table o HTML manual

Sistema de Notificaciones

Los emails se disparan automáticamente mediante hooks:

// En los modelos, después de crear/actualizar:
do_action( 'sr_order_created', $order_id );
do_action( 'sr_order_status_changed_to_completed', $order_id );
do_action( 'sr_budget_created', $budget_id );
do_action( 'sr_invoice_status_changed_to_sent', $invoice_id );

// SR_Email_Manager escucha estos hooks y envía emails
// usando plantillas en includes/notifications/templates/

Las plantillas usan variables como {{order_number}}, {{customer_name}}, {{shop_name}}.

API REST

Endpoints bajo /wp-json/sr/v1/:

Autenticación: JWT en class-authentication.php
Controladores en includes/api/class-api-controller.php
Verificar permisos con current_user_can() en cada endpoint

Comandos Comunes

Testing Manual

# Ver tablas creadas
mysql -u root -p nombre_db -e "SHOW TABLES LIKE 'wp_sr_%';"

# Ver roles creados
mysql -u root -p nombre_db -e "SELECT option_value FROM wp_options WHERE option_name = 'wp_user_roles';"

# Insertar tienda de prueba
mysql -u root -p nombre_db -e "INSERT INTO wp_sr_shops (name, code, email, status) VALUES ('Taller Test', 'test', 'test@test.com', 'active');"

Probar Modelos PHP

Crear archivo test.php en raíz del plugin:

<?php
require_once '../../../wp-load.php';

// Crear tienda
$shop_id = SR_Shop::create(array(
    'name' => 'Taller Prueba',
    'code' => 'taller-1',
    'email' => 'info@taller.com',
));
echo "Tienda creada: $shop_id\n";

// Crear cliente
$customer_id = SR_Customer::create(array(
    'shop_id' => $shop_id,
    'first_name' => 'Juan',
    'last_name' => 'Pérez',
    'email' => 'juan@test.com',
    'phone' => '600123456',
));
echo "Cliente creado: $customer_id\n";

Acceder a http://localhost/wordpress/wp-content/plugins/sistema-reparaciones/test.php.

Generación de Traducciones

# Generar archivo POT (requiere WP-CLI)
wp i18n make-pot . languages/sistema-reparaciones.pot

Contexto Importante

Estados de Órdenes de Reparación

Flujo típico (ver SR_Repair_Order::STATUSES):

pending - Orden recibida
diagnosis - Técnico diagnosticando
waiting_approval - Esperando aprobación de presupuesto
approved - Cliente aprobó presupuesto
in_progress - Reparación en curso
waiting_parts - Esperando repuestos
completed - Reparación completada
delivered - Entregada al cliente
cancelled - Cancelada
warranty - Garantía activa

Los cambios de estado se registran en wp_sr_status_history y disparan emails automáticos.

Prioridades

Ver SR_Repair_Order::PRIORITIES: low, medium, high, urgent.

Multi-tienda

El sistema soporta múltiples talleres/sucursales:

Cada usuario tiene un sr_shop_id en user_meta
SIEMPRE filtrar queries por shop_id
Los propietarios (sr_shop_owner) pueden gestionar múltiples tiendas

Configuración Global

Almacenada en wp_options con key sr_settings:

$settings = get_option( 'sr_settings', array() );
$currency = $settings['general']['default_currency'] ?? 'EUR';
$tax_rate = $settings['general']['default_tax_rate'] ?? 21;

Generación de PDF

Usa class-pdf-generator.php con plantillas en includes/pdf/templates/:

budget-template.php - Presupuestos
invoice-template.php - Facturas

Se descargan mediante admin_init hooks (ver SR_Admin::download_budget_pdf()).

Shortcodes Públicos

[sr_tracking_form] - Formulario para rastrear orden por número/teléfono (NO requiere login)
[sr_customer_portal] - Portal completo para clientes (requiere login, muestra sus órdenes)
[sr_budget_request] - Formulario para solicitar presupuesto (NO requiere login, crea lead)

Convenciones de Código

Prefijo: Todas las funciones, clases y constantes usan prefijo sr_ o SR_
Text Domain: sistema-reparaciones
Nombres de clases: SR_ seguido de palabras con mayúscula inicial (ej: SR_Repair_Order)
Nombres de archivos: class-nombre-minusculas.php
Escape: SIEMPRE usar esc_html(), esc_attr(), esc_url() en outputs
Nonces: SIEMPRE usar wp_nonce_field() en formularios y check_admin_referer() al procesar
i18n: SIEMPRE usar __(), _e(), _n() para strings traducibles
Queries: Usar $wpdb->prepare() para prevenir SQL injection

Notas de Seguridad

Validación: Usar SR_Validator antes de guardar
Sanitización: Usar SR_Sanitizer antes de insertar en BD
Escape: Usar funciones de WordPress al mostrar
Nonces: En todos los formularios
Capabilities: Verificar permisos en cada operación
SQL Injection: SIEMPRE usar $wpdb->prepare()
XSS: NUNCA usar echo $variable sin escape
CSRF: Verificar nonces con check_admin_referer() o wp_verify_nonce()

Documentación Adicional

Ver archivos en raíz del proyecto:

README.md - Documentación completa del usuario
INSTALACION.md - Guía de instalación detallada
ESTADO_ACTUAL.md - Estado del desarrollo y tareas pendientes
NOTIFICACIONES_EMAIL.md - Documentación del sistema de emails
CHANGELOG.md - Historial de cambios

Proyecto​

Entorno de Desarrollo​

Requisitos​

Debugging​

Arquitectura del Sistema​

Estructura de Alto Nivel​

Flujo de Ejecución​

Base de Datos​

Sistema de Roles y Permisos​

Patrones de Código​

Modelos (CRUD Pattern)​

Validación y Sanitización​

Páginas de Admin​

Sistema de Notificaciones​

API REST​

Comandos Comunes​

Testing Manual​

Probar Modelos PHP​

Generación de Traducciones​

Contexto Importante​

Estados de Órdenes de Reparación​

Prioridades​

Multi-tienda​

Configuración Global​

Generación de PDF​

Shortcodes Públicos​

Convenciones de Código​

Notas de Seguridad​

Documentación Adicional​

Proyecto

Entorno de Desarrollo

Requisitos

Debugging

Arquitectura del Sistema

Estructura de Alto Nivel

Flujo de Ejecución

Base de Datos

Sistema de Roles y Permisos

Patrones de Código

Modelos (CRUD Pattern)

Validación y Sanitización

Páginas de Admin

Sistema de Notificaciones

API REST

Comandos Comunes

Testing Manual

Probar Modelos PHP

Generación de Traducciones

Contexto Importante

Estados de Órdenes de Reparación

Prioridades

Multi-tienda

Configuración Global

Generación de PDF

Shortcodes Públicos

Convenciones de Código

Notas de Seguridad

Documentación Adicional