# Feature Specification: Mejoras de Rendimiento - Formularios de Contratos

**Feature Branch**: `009-mejoras-rendimiento-contratos`

**Created**: 2026-07-03

**Status**: Draft

**Input**: User description: "Mejoras de Rendimiento - Formularios de Contratos"

> **Constitution (I. Spec-First)**: Este spec MUST ser agnóstico de stack.
> No mencionar Laravel, React, Inertia.js ni rutas de código. El CÓMO va en `plan.md`.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Carga instantánea del formulario de contratos (Priority: P1)

Como usuario comercializador, necesito que el formulario de creación o edición de contratos cargue casi de forma instantánea al seleccionarlo, para no perder tiempo esperando que la interfaz esté lista, incluso si tengo un gran volumen de datos (tarifas, CUPS).

**Why this priority**: La velocidad de carga del formulario principal impacta directamente la productividad diaria del equipo comercial. Es el caso de uso más frecuente.

**Independent Test**: Puede probarse accediendo a la vista de creación de contrato; la estructura de la página y los campos principales deben ser visibles inmediatamente, mostrando indicadores de carga únicamente en las partes que requieran datos asíncronos pesados.

**Acceptance Scenarios**:

1. **Given** que el usuario navega a la sección de nuevo contrato, **When** la página es solicitada, **Then** la interfaz base (esqueleto) se renderiza de inmediato sin bloquearse por la carga de datos auxiliares.
2. **Given** que el formulario está cargando datos pesados (ej. lista completa de tarifas), **When** el usuario visualiza la pantalla, **Then** se muestran indicadores de progreso o esqueletos (skeletons) claros.

---

### User Story 2 - Interacción fluida al rellenar campos y selectores (Priority: P2)

Como usuario comercializador, necesito que al teclear en los inputs o al abrir listas desplegables (como clientes, tarifas o CUPS), la interfaz responda inmediatamente sin percibir "congelamientos" o "tirones".

**Why this priority**: Un rendimiento pobre durante la captura de datos (lag al escribir) genera frustración y errores de transcripción.

**Independent Test**: Puede probarse introduciendo texto rápidamente en campos de búsqueda o interactuando con listas desplegables que contengan miles de registros; la experiencia debe sentirse a 60fps.

**Acceptance Scenarios**:

1. **Given** un selector con miles de opciones (ej. Tarifas/SIPS), **When** el usuario lo despliega, **Then** la lista se muestra al instante (idealmente usando técnicas de paginación visual o virtualización).
2. **Given** que el usuario escribe rápido en un input de búsqueda, **When** teclea cada carácter, **Then** lo ve aparecer inmediatamente en pantalla y la búsqueda subyacente se realiza eficientemente (con debounce) sin interrumpir la escritura.

---

### User Story 3 - Respuesta ágil al enviar el formulario (Priority: P3)

Como usuario, necesito saber inmediatamente que mi formulario se está procesando cuando hago clic en "Guardar" o "Tramitar", para no tener dudas y evitar clics duplicados.

**Why this priority**: Evitar la creación de contratos duplicados por envíos múltiples debido a la falta de feedback del sistema.

**Independent Test**: Simular una latencia de red alta (throttling) y guardar un contrato, verificando que el sistema responda inmediatamente desactivando el botón de envío y mostrando el estado de carga.

**Acceptance Scenarios**:

1. **Given** un contrato completamente rellenado, **When** el usuario presiona "Guardar", **Then** el botón se deshabilita instantáneamente y muestra un spinner.
2. **Given** un formulario en proceso de guardado, **When** la operación finaliza, **Then** la interfaz actualiza el estado fluidamente mediante una transición o notificación de éxito.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: El sistema MUST disociar la carga de la interfaz principal de la carga de catálogos pesados.
- **FR-002**: Los componentes de selección (dropdowns) con alto volumen de datos MUST implementar mecanismos que eviten el bloqueo de la interfaz al abrirlos o buscar en ellos.
- **FR-003**: El sistema MUST optimizar las re-evaluaciones visuales (re-renders) para que actualizar un campo del formulario no provoque recalcular o redibujar campos no relacionados.
- **FR-004**: Los inputs de búsqueda o autocompletado MUST no saturar el servidor con peticiones simultáneas (se requiere control de concurrencia/debounce).
- **FR-005**: Las acciones de envío o cambios de estado pesados MUST prever un feedback visual inmediato y prevenir acciones repetidas (doble clic).

### Key Entities

- **Contratos**: Entidad principal que agrupa toda la información capturada en el formulario.
- **Catálogos (Tarifas, Comercializadoras, Clientes, CUPS)**: Entidades auxiliares cuyo volumen de datos suele ser el principal cuello de botella en formularios complejos.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: El tiempo de First Contentful Paint (FCP) o carga inicial interactiva del formulario debe ser inferior a 1 segundo en redes de velocidad estándar.
- **SC-002**: El tiempo de respuesta a interacciones de usuario (como escribir un carácter o desplegar un menú) debe ser inferior a 16ms para garantizar una sensación de 60 FPS (First Input Delay mínimo).
- **SC-003**: No deben registrarse "long tasks" (tareas que bloqueen el hilo principal por más de 50ms) en las herramientas de perfilado durante la interacción estándar de rellenar el contrato.

## Assumptions

- Asumimos que parte del problema actual de rendimiento proviene del intento de cargar grandes volúmenes de datos directamente al inicio (ej. enviando todas las tarifas y clientes de golpe).
- Asumimos que los cuellos de botella se producen al redibujar el formulario completo ante cambios mínimos en los campos.
- El alcance de esta feature se centra principalmente en la optimización de la entrega de datos, el renderizado de la UI y la interacción, manteniendo la lógica de negocio del contrato intacta.