# Feature Specification: Rediseño visual del módulo SIPS

**Feature Branch**: `012-redisenio-ui-sips`

**Created**: 2026-07-09

**Status**: Draft

**Input**: El módulo SIPS en la interfaz necesita un cambio de look & feel alineado con el diseño del sistema, buenas prácticas y los principios de accesibilidad web ya aplicados en Contratos. Ambas tablas del módulo deben mejorar su aspecto y estandarizar su visualización respecto al patrón de referencia de Contratos. La primera tabla (datos del punto de suministro) debe presentarse de forma intuitiva, con iconografía y amigable al usuario, mostrando **únicamente** los campos definidos en la referencia visual aprobada. El mapeo de atributos debe validarse contra una consulta real de tipo eléctrico con CUPS `ES0022000005446022YT`.

> **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`.

---

## Referencia visual y alcance

### Pantallas incluidas

1. **Tab «Datos Suministros»** — visualización estructurada del punto de suministro (sustituye la tabla clave-valor dinámica actual que muestra nombres técnicos de API sin etiquetas legibles).
2. **Tab «Consumo»** — tabla de historial de consumo y bloque de resumen anual (tarjetas + tabla), alineados visual y funcionalmente con el estándar de tablas accesibles de Contratos.

### Pantallas excluidas (fuera de alcance)

- Cambios en la lógica de consulta a proveedores SIPS (ADX / AUDAX).
- Nuevos campos de negocio no presentes en la referencia visual.
- Rediseño del formulario extendido de búsqueda AUDAX (optimización, rangos de consumo, etc.) salvo estandarización visual mínima de contenedores y foco accesible.

### Referencia de diseño y accesibilidad

La nueva experiencia MUST reutilizar los mismos principios ya aplicados en Contratos:

- Contenedor con foco visible coherente en toda la pantalla.
- Tabs accesibles con roles ARIA (`tablist`, `tab`, `tabpanel`), navegación por teclado y etiquetas asociadas.
- Campos y valores de solo lectura con etiquetas humanas, jerarquía visual por secciones y contraste suficiente.
- Tablas con cabeceras semánticas, desplazamiento horizontal en viewports estrechos y lectura comprensible por teclado y lectores de pantalla.
- Tokens visuales del sistema (tipografía, bordes, espaciado, tarjetas) coherentes con Contratos y el resto del backoffice Eneon.

---

## Catálogo de campos — Punto de suministro (tipo eléctrico)

La interfaz MUST mostrar **exactamente** los siguientes campos, en el orden indicado, agrupados en secciones con iconografía representativa. No MUST mostrar otros atributos devueltos por la API aunque estén presentes en la respuesta.

### Sección A — Identificación del suministro

| Etiqueta en interfaz | Atributo origen (API ADX) | Notas de presentación |
|----------------------|---------------------------|------------------------|
| CUPS | `CUPS` | Valor principal destacado |
| Código distribuidora | `Cod_Dist` | |
| Distribuidora | `Distribuidora` | |
| Tarifa | `Tarifa` | |
| Descripción Tarifa | `Des_Tarifa` | Mostrar `—` si vacío |
| Tensión | `Tension` | |

### Sección B — Ubicación del suministro

| Etiqueta en interfaz | Atributo origen (API ADX) | Notas de presentación |
|----------------------|---------------------------|------------------------|
| Dirección suministro | `Direccion_Suministro` | Mostrar `—` si vacío |
| C.P. suministro | `Cod_Postal_Suministro` | Aceptar fallback a `CodigoPostal_Suministro` si el primero está vacío |
| Localidad suministro | `Localidad_Suministro` | |
| Provincia suministro | `Provincia_Suministro` | |

### Sección C — Equipos y perfil técnico

| Etiqueta en interfaz | Atributo origen (API ADX) | Notas de presentación |
|----------------------|---------------------------|------------------------|
| Indicativo ICP | `Indicativo_ICP` | |
| Propiedad ICP | `Propiedad_ICP` | |
| Telegestionado | `telegestion` | Aceptar fallback a `Telegestionado_Activo` si `telegestion` está vacío |
| Perfil consumo | `Perfil_Consumo` | |
| Tipo PM | `Tipo_PM` | |
| Propiedad EM | `Propiedad_Equipo_Medida` | |
| Última Comercializadora | `last_comer_known` | Aceptar fallback a `Comercialitzadora`; mostrar `—` si vacío |

### Sección D — Titular y datos administrativos

| Etiqueta en interfaz | Atributo origen (API ADX) | Notas de presentación |
|----------------------|---------------------------|------------------------|
| Titular del suministro | `NombreCompleto_Titular` | Aceptar fallback a `Nombre_Titular` |
| CIF Titular | `CIF_Titular` | |
| Dirección del Titular | `Direccion_Titular` | |
| C.P. del Titular | `Cod_Postal_Titular` | |
| Localidad Titular | `Municipio_Titular` | |
| Provincia Titular | `Provincia_Titular` | |
| Código CNAE | `cnae_code` | |
| CNAE | `cnae_desc` | |
| Teléfono | `Telefono_Titular` | |
| Tipo titular | `Tipo_Titular` | Aceptar fallback a `Persona` |
| Persona de Contacto | `persona_contacto` | |
| Cargo del Contacto | `cargo_persona_contacto` | |
| Primera vivienda | `Primera_vivienda` | |
| Cortes | `Cortes` | |
| Impago | `Impago` | |
| Depósito garantía | `importeDepositoGarantiaEuros` | Aceptar fallback a `Fianza`; formatear como importe en euros cuando aplique |

### Sección E — Potencias y fechas contractuales

| Etiqueta en interfaz | Atributo origen (API ADX) | Notas de presentación |
|----------------------|---------------------------|------------------------|
| Potencia contratada P1 (kW) | `Pot_Cont_P1` | Formato numérico con hasta 2 decimales |
| Potencia contratada P2 (kW) | `Pot_Cont_P2` | |
| Potencia contratada P3 (kW) | `Pot_Cont_P3` | |
| Potencia contratada P4 (kW) | `Pot_Cont_P4` | |
| Potencia contratada P5 (kW) | `Pot_Cont_P5` | |
| Potencia contratada P6 (kW) | `Pot_Cont_P6` | |
| Potencia máxima BIE | `Pot_Max_BIE` | |
| Potencia máxima APM | `Pot_Max_Puesta` | |
| Derechos de acceso (kW) | `Der_Acceso_Llano` | Aceptar fallback a `Der_Extension` |
| Relación de transformación | `Relacion_Transformacion` | Mostrar `—` si el atributo no existe o está vacío |
| Fecha Cambio Comercializadora | `Fec_Ult_Camb_Comer` | Formato fecha legible `DD/MM/AAAA` |
| Fecha de alta | `Fec_Alta_Suministro` | |
| Fecha última lectura | `Fec_Ult_Lect` | Aceptar fallback a `lastlectura` |
| Fecha caducidad BIE o APM | `Fec_Lim_Exten` | Aceptar fallback a `fechaLimiteDerechosReconocidos` |
| Suministro contratable | `Suministro_Contratable` | Mostrar `—` si el atributo no existe o está vacío |
| Estado no contratable | `Estado_No_Contratable` | Mostrar `—` si el atributo no existe o está vacío |

### Reglas transversales de formato

- Valores nulos, vacíos o no numéricos equivalentes a cero en campos descriptivos MUST mostrarse como `—`.
- Fechas ISO MUST normalizarse a formato `DD/MM/AAAA` para el usuario.
- Potencias y consumos MUST usar separador decimal coherente con el locale español.
- Los campos numéricos con valor `0` en potencias P3–P6 MUST mostrarse como `0` (no ocultarse), coherente con la referencia visual.

### Caso de validación obligatorio

Al consultar el CUPS `ES0022000005446022YT` con tipo eléctrico, la interfaz MUST renderizar al menos los siguientes valores no vacíos verificados en la respuesta real del proveedor:

| Etiqueta | Valor esperado |
|----------|----------------|
| CUPS | ES0022000005446022YT |
| Código distribuidora | 0022 |
| Distribuidora | UNION FENOSA DISTRIBUCION, S.A. |
| Tarifa | 2.0TD |
| Tensión | 1X230 |
| C.P. suministro | 19002 |
| Localidad suministro | Guadalajara |
| Provincia suministro | Guadalajara |
| Indicativo ICP | 0 |
| Propiedad ICP | Otros |
| Perfil consumo | P2.0TD |
| Tipo PM | Punto de medida tipo 5 |
| Propiedad EM | Distribuidor |
| Tipo titular | NIF |
| Primera vivienda | SI |
| Cortes | 0 |
| Impago | 0 |
| Potencia contratada P1 (kW) | 5,75 |
| Potencia contratada P2 (kW) | 5,75 |
| Potencia máxima BIE | 5,75 |
| Derechos de acceso (kW) | 5,75 |

> **Nota**: Los valores concretos de fechas y campos opcionales pueden variar según la fecha de consulta SIPS; lo crítico es el **mapeo correcto** de etiquetas y atributos, no la inmutabilidad de cada valor.

---

## Catálogo de campos — Tabla de consumo (tipo eléctrico)

### Resumen anual (tarjetas)

Mantener la información actual, con rediseño visual alineado a Contratos:

| Etiqueta | Atributo origen |
|----------|-----------------|
| Consumo anual total | `lecturas.LastTotalYearkWh` |
| Periodo P1 | `lecturas.LastTotalYearkWh_p1` |
| Periodo P2 | `lecturas.LastTotalYearkWh_p2` |
| Periodo P3 | `lecturas.LastTotalYearkWh_p3` |
| Periodo P4–P6 | `lecturas.LastTotalYearkWh_p4` … `_p6` | Ocultar tarjeta solo si el valor es exactamente 0 y el periodo es P4, P5 o P6 (comportamiento actual) |

### Tabla de historial

| Columna | Atributo origen |
|---------|-----------------|
| Fecha Inicio | `FLectAntM1` |
| Fecha Fin | `FLectM1` |
| Tarifa | `Tarifa` |
| P1 – P6 | `CActP1M1` … `CActP6M1` |
| Consumo Total | Suma de P1–P6 del periodo |

### Estándar visual de tablas (alineado a Contratos)

- Cabecera fija visible al desplazarse verticalmente cuando la tabla supera el alto del panel.
- `scope` en cabeceras de columna.
- Contenedor con scroll horizontal en pantallas estrechas sin pérdida de contexto.
- Estados vacíos y de carga con mensaje claro y contraste adecuado.
- Densidad y tipografía coherentes con tablas de CUPS en Contratos.

---

## User Scenarios & Testing *(mandatory)*

### User Story 1 — Consultar punto de suministro de forma legible (Priority: P1)

Como usuario del backoffice que consulta SIPS, necesito ver los datos del punto de suministro eléctrico organizados por secciones con iconos y etiquetas en español, para comprender la información sin interpretar nombres técnicos de API.

**Why this priority**: Es el principal problema de usabilidad actual; sin esto el módulo no cumple su función informativa.

**Independent Test**: Consultar `ES0022000005446022YT` (eléctrico), abrir «Datos Suministros» y verificar que aparecen las 5 secciones, las 47 etiquetas del catálogo y los valores mapeados del caso de validación.

**Acceptance Scenarios**:

1. **Given** una consulta SIPS exitosa con datos de suministro, **When** el usuario abre la pestaña «Datos Suministros», **Then** la interfaz muestra secciones con iconografía (identificación, ubicación, equipos, titular, potencias/fechas) y no muestra claves técnicas crudas de API.

2. **Given** el CUPS `ES0022000005446022YT`, **When** se renderizan los datos, **Then** los campos del catálogo muestran las etiquetas en español y los valores coinciden con el mapeo definido en este spec.

3. **Given** un campo sin valor en la respuesta, **When** se muestra en la interfaz, **Then** el usuario ve `—` y no un espacio en blanco ni el nombre del atributo.

---

### User Story 2 — Revisar consumo histórico con tabla estandarizada (Priority: P1)

Como usuario del backoffice, necesito consultar el historial de consumo y el resumen anual en una tabla clara y consistente con Contratos, para analizar periodos y potencias sin fricción visual.

**Why this priority**: La segunda tabla del módulo es igual de crítica para la operativa diaria; comparte prioridad con la visualización del suministro.

**Independent Test**: Tras consultar un CUPS eléctrico con lecturas, abrir «Consumo» y verificar resumen + tabla con columnas definidas y comportamiento accesible.

**Acceptance Scenarios**:

1. **Given** una consulta con lecturas históricas, **When** el usuario abre «Consumo», **Then** ve el resumen anual en tarjetas y la tabla con columnas Fecha Inicio, Fecha Fin, Tarifa, P1–P6 y Consumo Total.

2. **Given** una tabla con muchas filas, **When** el usuario se desplaza vertical u horizontalmente, **Then** las cabeceras permanecen legibles y la tabla es navegable por teclado.

3. **Given** una consulta sin lecturas, **When** el usuario abre «Consumo», **Then** ve un estado vacío informativo, no una tabla rota ni filas sin sentido.

---

### User Story 3 — Experiencia accesible y coherente con Contratos (Priority: P2)

Como usuario que navega con teclado o lector de pantalla, necesito que el módulo SIPS respete los mismos patrones de accesibilidad que Contratos, para trabajar con igual comodidad en todo el sistema.

**Why this priority**: Requisito transversal de calidad; no bloquea el dato pero sí la adopción y cumplimiento.

**Independent Test**: Recorrer la pantalla SIPS solo con teclado y verificar foco visible, tabs ARIA y lectura de secciones/campos.

**Acceptance Scenarios**:

1. **Given** el módulo SIPS abierto, **When** el usuario navega con Tab y Shift+Tab, **Then** el foco es siempre visible y sigue un orden lógico (selector → formulario → tabs → contenido).

2. **Given** las pestañas «Datos Suministros» y «Consumo», **When** el usuario activa una pestaña con Enter o Espacio, **Then** el panel asociado recibe foco/contenido visible y `aria-selected` refleja el estado activo.

3. **Given** un campo de solo lectura en una sección, **When** un lector de pantalla lo anuncia, **Then** se escucha primero la etiqueta humana y después el valor formateado.

---

### User Story 4 — Soporte gas sin regresión (Priority: P3)

Como usuario que consulta CUPS de gas, necesito que el rediseño no rompa la visualización existente de consumo gas, manteniendo coherencia visual con el nuevo estándar.

**Why this priority**: El alcance principal es eléctrico, pero el módulo es dual; evitar regresiones.

**Independent Test**: Consultar un CUPS gas y verificar tab Consumo con columnas gas y resumen gas.

**Acceptance Scenarios**:

1. **Given** una consulta gas exitosa, **When** el usuario abre «Consumo», **Then** la tabla y resumen gas mantienen sus columnas actuales con el nuevo estilo visual.

---

### Edge Cases

- Respuesta con múltiples registros en `suministros[]`: mostrar el primero como caso principal; si hay más de uno, indicar al usuario que existen suministros adicionales sin expandir el catálogo de campos.
- Proveedor AUDAX sin objeto `suministros` estructurado: la pestaña «Datos Suministros» conserva su formulario actual (ver plan).
- Comercializadora sin integración SIPS: mensaje «La comercializadora {nombre} no cuenta con capacidad de consulta SIPS» (sin códigos técnicos ni referencias a proveedores internos).
- Error de consulta o timeout: mensaje de error accesible con opción de reintentar; no mostrar restos de consultas anteriores mezclados.
- Campos con fechas inválidas: mostrar el valor original de forma segura o `—`, sin romper el layout.
- Viewport móvil/tablet: secciones apiladas verticalmente; tablas con scroll horizontal; iconos no deben ser el único portador de significado (siempre acompañados de texto).

---

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: El sistema MUST sustituir la visualización dinámica de claves API por un layout estructurado de solo lectura con las 5 secciones y 47 campos del catálogo de punto de suministro eléctrico.
- **FR-002**: El sistema MUST aplicar el mapeo etiqueta ↔ atributo definido en este spec, incluyendo fallbacks documentados.
- **FR-003**: El sistema MUST formatear fechas, números y valores vacíos según las reglas transversales.
- **FR-004**: El sistema MUST rediseñar la tabla de consumo eléctrico y el resumen anual siguiendo el estándar visual y accesible de Contratos.
- **FR-005**: El sistema MUST conservar las columnas funcionales actuales de consumo gas, aplicando el mismo estándar visual.
- **FR-006**: El sistema MUST mantener las pestañas «Datos Suministros» y «Consumo» con comportamiento accesible equivalente al estándar EneonTabs de Contratos.
- **FR-007**: El sistema MUST cumplir el caso de validación del CUPS `ES0022000005446022YT` para comprobar mapeo y nombramiento.
- **FR-008**: El sistema MUST NOT mostrar atributos de API adicionales fuera del catálogo en la vista de punto de suministro.
- **FR-009**: Cada sección del punto de suministro MUST incluir un encabezado visible con icono y título descriptivo en español.
- **FR-011**: Cuando el usuario selecciona una comercializadora sin proveedor SIPS configurado (sin capacidad técnica ADX/AUDAX), el sistema MUST mostrar un mensaje claro indicando que esa comercializadora no cuenta con capacidad de consulta SIPS, sin exponer detalles técnicos de integración al usuario final.

### Key Entities

- **Consulta SIPS**: Resultado de búsqueda por comercializadora, CUPS y tipo de servicio; incluye suministro(s), lecturas históricas y resumen anual.
- **Punto de suministro (vista)**: Proyección de solo lectura con 47 campos normalizados para tipo eléctrico, agrupados en 5 secciones.
- **Historial de consumo**: Colección de periodos con fechas, tarifa, lecturas por periodo horario y total calculado.
- **Resumen anual**: Agregados de consumo por periodo P1–P6 y total anual.

---

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: El 100 % de las 47 etiquetas del catálogo aparecen en la interfaz para una consulta eléctrica con datos completos.
- **SC-002**: En la validación con `ES0022000005446022YT`, al menos 20 de los 22 valores de control del caso de validación coinciden con el mapeo definido.
- **SC-003**: Un usuario puede identificar CUPS, tarifa, potencias P1–P2 y localidad del suministro en menos de 10 segundos sin ayuda externa (prueba moderada con 3 usuarios internos).
- **SC-004**: La pantalla SIPS es navegable completamente por teclado sin foco atrapado ni elementos inalcanzables.
- **SC-005**: Las tablas de consumo mantienen todas las columnas funcionales actuales sin pérdida de datos respecto al comportamiento previo.
- **SC-006**: No se muestran claves técnicas de API como etiquetas visibles al usuario en la vista de punto de suministro.

---

## Assumptions

- La referencia visual aportada corresponde al proveedor ADX y tipo eléctrico; es el caso prioritario de este rediseño.
- Los campos `Relacion_Transformacion`, `Suministro_Contratable` y `Estado_No_Contratable` pueden no estar presentes en todas las respuestas; se mostrarán como `—` cuando falten.
- El rediseño es exclusivamente de capa de presentación; no se modifican contratos de API con proveedores externos.
- Los patrones de accesibilidad y visual de Contratos (tabs Eneon, foco accesible, tablas con cabecera semántica) son la referencia válida y actual del sistema.
- AUDAX seguirá usando su formulario de búsqueda actual en «Datos Suministros» hasta una futura feature que unifique ambos proveedores bajo el mismo catálogo de campos.