Guía de Refactorización Frontend - CreaRack Pro

Fecha: 27-01-2026 Versión: v6.0.1

Este documento describe la deuda técnica identificada y las estrategias de refactorización recomendadas.

Documento relacionado: Documentation/DESIGN_SYSTEM.md - Sistema de diseño centralizado

1. Design System (Fases 1-4) ✅ COMPLETADO

Estado Actual

El sistema de diseño ha sido implementado en 4 fases:

Commits Relacionados

• 6651d49 - feat: Implement semantic button system (Phases 1-3)
• cd441e1 - feat: Standardize modal structure (Phase 4)

Sistema de Botones Semánticos

/* Uso basado en INTENCIÓN, no en color */
.btn-action   /* Azul - Guardar, Crear, Confirmar */
.btn-danger   /* Rojo - Eliminar, Cancelar, Logout */
.btn-success  /* Verde - Login, Conectar, Aceptar */
.btn-neutral  /* Blanco - Navegar, Ver, Cerrar */
.btn-export   /* Amarillo - Exportar, Imprimir, Download */
.btn-warning  /* Naranja - Editar, Modificar */

Sistema de Modales Estandarizado

<div class="modal-overlay">
    <div class="modal-content modal-md">
        <div class="modal-header">
            <h3 class="modal-title">Título</h3>
            <button class="modal-close">&times;</button>
        </div>
        <div class="modal-body">
            <!-- Contenido -->
        </div>
        <div class="modal-footer">
            <button class="btn btn-neutral">Cancel</button>
            <button class="btn btn-action">Confirm</button>
        </div>
    </div>
</div>

Tamaños disponibles: .modal-sm, .modal-md, .modal-lg, .modal-xl, .modal-full

2. Scripts Inline (P2-7) ✅ PARCIALMENTE COMPLETADO

Estado Actual

• base.html: ✅ Extraído a static/js/base.js (~350 líneas)
• editor.html: Pendiente (scripts menores, ~200 líneas)
• report.html: Pendiente (~53 líneas)

Archivo Creado

static/js/base.js - Contiene:
- Dropdown toggle logic
- PWA Install logic
- Toast notifications (showToast, showAppToast)
- Download handler (handleDownload)
- Full System Restore
- Width toggle mode
- QR Label generation modal
- Report generation modal

3. Event Handlers Onclick (P2-6) - DEUDA TÉCNICA

Estadísticas

• Total onclick handlers: 83 en templates
• base.html: 22 onclick
• index.html: 16 onclick
• terminal/index.html: 17 onclick
• blueprint_editor.html: 16 onclick

Por Qué NO Migrar Ahora

1. Riesgo alto: Los onclick actuales funcionan correctamente
2. Esfuerzo vs beneficio: La migración requiere testing exhaustivo
3. Sin mejora de rendimiento: onclick inline es igual de performante

Estrategia Recomendada (Futuro)

Para nuevos desarrollos, usar event listeners con delegación:

document.addEventListener('click', (e) => {
    if (e.target.matches('[data-action="close-modal"]')) {
        closeModal(e.target.dataset.modal);
    }
});

4. Estilos Inline (P2-5) - PARCIALMENTE RESUELTO

Estadísticas Originales

• Total style= attributes: 440 en templates

Progreso Actual

Con la implementación del Design System (Fases 1-4), se han reducido significativamente:

Clases Utilitarias ✅ COMPLETADO

Ya implementadas en variables.css:

/* Spacing */
.mb-0, .mb-1, .mb-2, .mb-3  /* margin-bottom: 0/8/16/24px */
.mt-1, .mt-2                 /* margin-top: 8/16px */
.p-1, .p-2, .p-3             /* padding: 8/16/24px */
.px-1, .py-1                 /* padding horizontal/vertical: 8px */

/* Flexbox */
.d-flex, .align-center, .justify-between
.gap-1, .gap-2               /* gap: 8/16px */

/* Common */
.w-100, .d-none, .fw-bold, .cursor-pointer

5. Plan de Acción

✅ Completado

• Extraer script de base.html a base.js
• Crear tokens semánticos para botones (variables.css)
• Crear clases de botones semánticos (components.css)
• Migrar 69+ botones a clases semánticas
• Crear clases para estructura de modales
• Migrar 15+ modales a estructura estandarizada

Pendiente Corto Plazo

• Fase 5: Componente SSH Terminal reutilizable
• Crear utility classes para espaciados ✅ (implementado en variables.css)
• Documentar patrones de estilo restantes

Pendiente Largo Plazo

• Migrar onclick de modales a event listeners
• Migrar estilos inline de espaciado a utility classes ✅
• Considerar sistema de componentes (Web Components)

6. Notas Técnicas

Carga de Scripts

<!-- base.js con defer para no bloquear render -->
<script src="{% static 'js/base.js' %}" defer></script>

<!-- SSH libraries cargadas dinámicamente cuando se necesitan -->
<script>window.loadSSHLibraries()</script>

Funciones Globales de base.js

• toggleConfigDropdown(), closeConfigDropdown()
• showToast(message, type), showAppToast (alias)
• handleDownload(url, filename, label)
• toggleWidthMode()
• openGenQRModal(), printThermalLabels()
• openReportModal(), generateReport()
• Auto-detecta window.USER_AUTHENTICATED

Última actualización: 28-01-2026

Véase también

• [[crearack-tech—architecture—performance-optimization]] — optimización de rendimiento a nivel arquitectura
• [[crearack-tech—reports—audit-abril-17-2026]] — auditoría del 17-abril-2026
• [[crearack-tech—reports—auditoria-codigo-04-03-2026]] — auditoría de código 04-03-2026
• [[feature—refactor—audit-abril-2026]] — feature — refactor post-auditoría Abril 2026
• [[decision—20260417—ruff-pin]] — pin exacto de ruff por regla drift
• [[crearack-tech—guides—testing]] — estrategia general de tests