# Spec 008 — Portar funcionalidades de `version2` a `develop_eneon`

**Estado:** Implementación código completa; verificación manual pendiente (T095)  
**Rama origen (funcionalidad):** `version2` (`d460ae77`)  
**Rama destino (base arquitectónica):** `develop_eneon` (`941516eb`)  
**Ancestro común:** `f4aaf9de`

---

## 1. Objetivo

Replicar en `develop_eneon` las capacidades de negocio e integración introducidas en `version2`, **sin regresiones** sobre mejoras de UX, accesibilidad, historial CUPS, validaciones de formulario, vistas en tarjetas ni CI/CD ya presentes en `develop_eneon`.

**No es un merge directo de ramas.** Es un port selectivo (cherry-pick funcional) con adaptación al código base de `develop_eneon`.

---

## 2. Alcance funcional (qué portar desde `version2`)

### Épica A — Integración ADX / Salesforce (SIPS multi-proveedor)

| ID | Historia | Prioridad |
|----|----------|-----------|
| A-01 | Como usuario, selecciono comercializadora en `/sips` y el sistema resuelve proveedor (`audax` \| `adx`) vía `T_Comercializadora.Servicio_Integracion` | Must |
| A-02 | Como usuario con comercializadora AUDAX, consulto CUPS luz/gas con persistencia en `T_ConsumosSIPSAudax*` | Must |
| A-03 | Como usuario con comercializadora ADX, consulto CUPS Electricity/Gas vía API MuleSoft sin persistencia local | Must |
| A-04 | Como operador, ejecuto `php artisan sips:adx-debug [--test]` para validar credenciales ADX | Should |
| A-05 | Como usuario en contratos, autocompleto consumo SIPS desde CUPS respetando el `CodCom` de la comercializadora activa | Must |

**Artefactos de referencia en `version2`:** `app/Services/Sips/*`, `config/sips.php`, `SipsController`, `resources/js/Pages/Eneon/Sips/**`, `SipsAdxDebugCommand`.

---

### Épica B — Tarifas ADX / ventanas de precio Salesforce

| ID | Historia | Prioridad |
|----|----------|-----------|
| B-01 | Como usuario ADX, abro modal de ventanas y obtengo tarifas vía `AdxTarifasService` (no `AudaxEnergyService`) | Must |
| B-02 | Como usuario, veo modal ADX ampliado (nombre, producto, versión, gama, precios P/E, fechas) | Must |
| B-03 | Como usuario, selecciono ventana y persisto `Id_Tarifa_Automatica`, `nombretarifa`, `productCode`, `version` en fila CUPS | Must |
| B-04 | Como usuario, configuro 7 servicios de contrato por fila CUPS (checkboxes CF, PP, SBV, SBas, SE, SP, SU) | Must |
| B-05 | Como operador, ejecuto `php artisan tarifas:adx-debug [--test]` | Should |
| B-06 | Como usuario, cargo masivamente CUPS gas con tarifas `RL.1`–`RL.6` (alineación catálogo ADX) | Should |

**Artefactos de referencia:** `AdxTarifasService`, `AdxHttpClient`, `AdxTarifaDto`, `ModalPrecios.tsx`, `ventanaPreciosUtils.ts`, `serviciosContratoConfig.ts`, `ServiciosContratoFields.tsx`, scripts SQL en `bdscripts/`.

---

### Épica C — Canal, comercial e integraciones Audax/ADX

| ID | Historia | Prioridad |
|----|----------|-----------|
| C-01 | Como usuario, al ejecutar OK Comercial debo indicar canal y comercial (obligatorios) | Must |
| C-02 | Como usuario, al enviar documentación a comercializadora debo indicar canal y comercial | Must |
| C-03 | Como usuario, al tramitar contrato debo indicar canal y comercial en payload de integración | Must |
| C-04 | Los valores canal/comercial se recuerdan en `localStorage` (`eneon_comercial`, `eneon_canal`) | Should |
| C-05 | Backend propaga `comercial` y `canal` en jobs: `OkCommercialContractJob`, `EnvioDocumentoContratoIntegracionJob`, `GenerarContratoIntegracionJob` | Must |

**Artefactos de referencia:** `promptComercialCanal.ts`, cambios en `IntegracionTraits`, `ContratoTraits`, jobs de integración.

---

### Épica D — Representante legal (TipProCom 1 y 2)

| ID | Historia | Prioridad |
|----|----------|-----------|
| D-01 | Como usuario TipProCom 1/2, al tramitar selecciono representante legal de contactos del cliente | Must |
| D-02 | Como usuario TipProCom 1/2, al generar condiciones particulares selecciono representante que firma el PDF | Must |
| D-03 | Backend valida que `CodConCli` pertenece al cliente vía `T_ContactoDetalleCliente` | Must |
| D-04 | Tramitación envía `representante_contacto` y `nif_representante_contacto` en body Audax/ADX | Must |
| D-05 | PDF condiciones particulares usa datos del representante seleccionado (nombre, NIF, cargo) | Must |
| D-06 | Carga masiva MultiCliente exige representante legal seleccionado antes de cargar CUPS | Should |

**Artefactos de referencia:** `promptCondicionesParticulares.ts`, `getRepresentantesLegalesByCodCliTrait`, `AuxiliarCondicionesParticularesTraits`, `IntegracionTraits::resolverContactoRepresentanteTramitacion`.

---

## 3. Fuera de alcance (NO portar desde `version2`)

Estas eliminaciones existen en `version2` pero **deben conservarse en `develop_eneon`**:

| Funcionalidad en `develop_eneon` | Motivo |
|----------------------------------|--------|
| **Historial CUPS** (`CupsHistorialController`, modelos, migración, tabs UI, tests) | Feature completa solo en develop |
| **Accesibilidad contratos** (`estilosFocoAccesible`, `EneonTabs`, IDs DOM, hooks validación) | Mejora UX/a11y posterior al fork |
| **Componentes Shared contratos** (`TypeaheadClienteConLimpiar`, `BarraProgresoCargaMasiva`, `cupsRowKeys`, etc.) | Infraestructura UX develop |
| **Refactor UniClienteUniPunto** (subcomponentes `SeccionDireccion`, `TarjetaSuministro`, etc.) | Arquitectura UI superior en develop |
| **Vistas tarjetas maestros** (Clientes, Contactos, Comercializadoras, Productos, Tarifas, Contratos, CUPS, Puntos) | UX develop |
| **Login accesible** (`Login.module.css`) | UX develop |
| **GitHub Actions deploy** (`.github/workflows/deploy.yml`) | CI develop |
| **Plantillas PDF en `public/storage/pdfs`** | develop mantiene assets; version2 los eliminó del repo |
| **Eliminación de tests** (CupsHistorial, AuxiliarSepa, etc.) | Conservar suite develop |

**Regla de oro:** si un archivo fue **eliminado** en `version2` pero **existe** en `develop_eneon`, mantener la versión develop salvo conflicto directo con código nuevo portado.

---

## 4. Estrategia de port (merge funcional, no git merge)

### Fase 0 — Preparación
1. Crear rama `feature/008-port-version2` desde `develop_eneon`.
2. Ejecutar scripts SQL idempotentes (ver `data-model.md`).
3. Configurar variables `.env` ADX (ver `research.md` § Configuración).

### Fase 1 — Backend servicios ADX (sin tocar UI develop)
1. Añadir `AdxHttpClient`, `AdxSipsService`, `SipsProviderRegistry`, `AdxTarifasService`, `AdxTarifaDto`.
2. Añadir `config/sips.php` y ampliar `config/services.php`.
3. Añadir commands debug.
4. Extender `IntegracionTraits::showTarifasIntegracion` con rama `adx`.
5. **Compatibilidad SIPS:** en `SipsController@consumirServicioSips`, si `cod_com` no viene, inferir desde comercializadora AUDAX por defecto o resolver desde contexto de sesión — **no romper** hooks de contratos que envían solo `{ cups, tipo }`.

### Fase 2 — Persistencia CUPS y traits
1. Extender `PropuestaComercialCups` fillable/casts con campos ventana ADX y servicios contrato.
2. Portar `mapServiciosContrato`, `mapVentanaAdxFields` en `ContratoTraits`.
3. Portar lógica representante legal y canal/comercial en traits y jobs.

### Fase 3 — Frontend SIPS (adaptado a develop)
1. Portar estructura modular SIPS (`components/`, `hooks/`, `types.ts`).
2. **Conservar** `validacionSips.ts` de develop si existe; integrar validación CUPS en paneles nuevos.
3. Usar `EneonTabs` / foco accesible de develop en lugar del Nav simple de version2.

### Fase 4 — Frontend contratos
1. Portar `ventanaPreciosUtils.ts`, `serviciosContratoConfig.ts`, `ServiciosContratoFields.tsx`.
2. Extender `ModalPrecios.tsx` con rama ADX **sin eliminar** estilos accesibles develop.
3. Añadir columnas servicios contrato en tablas CUPS **manteniendo** tooltips y `title` accesibles.
4. Portar `promptComercialCanal.ts` y `promptCondicionesParticulares.ts`.
5. Actualizar hooks `useCupsElectrico`, `useCupsGas`, secciones ReferenciasCodigo para enviar `cod_com` en SIPS y `servicio` en tarifas.
6. Integrar prompts en `EditarContrato` **sin duplicar** lógica inline.

### Fase 5 — Representante legal UI
1. Portar lógica backend `representantesLegales` en controller edición.
2. En `RepresentanteLegalSection`: **fusionar** — conservar `TypeaheadClienteConLimpiar` y props de errores develop; añadir reglas de negocio version2 (filtro clientes, bulk load guard).

### Fase 6 — Verificación manual
Checklist en §8.

---

## 5. Criterios de aceptación globales

Leyenda: ✅ código/auditoría estática | ⏳ requiere smoke manual en entorno

| # | Criterio | Estado |
|---|----------|--------|
| 1 | Comercializadora `Servicio_Integracion = adx` usa API MuleSoft para SIPS y tarifas | ⏳ T035–T036, T056, T095 |
| 2 | Comercializadora `audax` mantiene flujo EnerSpain existente | ⏳ T035, T095 |
| 3 | OK Comercial, envío documentos y tramitación fallan 422 si faltan canal/comercial | ✅ backend validado en código; ⏳ T070–T071 |
| 4 | TipProCom 1/2: modal representante; PDF y tramitación usan contacto validado | ✅ wiring T072–T083; ⏳ T084–T085 |
| 5 | Campos ventana ADX y servicios contrato persisten y se recuperan en edición | ✅ modelo + mappers T037–T055; ⏳ T056–T057 |
| 6 | Historial CUPS operativo (tabs, API, escritura en update) | ✅ T086–T087 auditoría estática; ⏳ tab UI T095 |
| 7 | Vistas tarjetas, validación accesible y barra progreso bulk operativas | ✅ T088–T091 auditoría estática; ⏳ smoke T095 |
| 8 | `sips:adx-debug --test` y `tarifas:adx-debug --test` conectan | ⏳ T020, entorno `.env` ADX |

**Resumen:** 4/8 verificables por código; 4/8 requieren entorno configurado y prueba manual (T095 consolida regresión develop).

---

## 6. Matriz de validación negocio

| Operación | Canal | Comercial | CodConCli |
|-----------|-------|-----------|-----------|
| OK Comercial | Obligatorio | Obligatorio | N/A |
| Envío documentación | Obligatorio | Obligatorio | N/A |
| Tramitar TipProCom 1/2 | Obligatorio | Default `'0'` | Obligatorio si hay contactos |
| Tramitar TipProCom 3+ | Obligatorio | Obligatorio | N/A |
| PDF Cond. Particulares Tip 1/2 | Obligatorio | Default `'0'` | Obligatorio si hay contactos |
| PDF otros | Obligatorio | Obligatorio | N/A |

---

## 7. Riesgos y mitigaciones

| Riesgo | Impacto | Mitigación |
|--------|---------|------------|
| Breaking change `sips.consumo` requiere `cod_com` | Contratos dejan de autocompletar consumo | Retrocompat: `cod_com` opcional con fallback; actualizar hooks progresivamente |
| Merge ciego elimina historial CUPS | Pérdida feature develop | Lista explícita §3; revisión diff por archivo |
| version2 simplifica a11y en SIPS/Representante | Regresión WCAG | Reimplementar paneles version2 usando primitivas develop (`EneonTabs`, foco accesible) |
| URLs `.env` ADX apuntan a WS legacy Audax | Integración falla en prod | Validar con commands debug; documentar URLs MuleSoft por entorno |
| Scripts SQL no ejecutados | Columnas faltantes en save CUPS | Ejecutar `bdscripts` antes de deploy; verificar con DESCRIBE |
| Duplicación `AdxHttpClient` vs lógica en `AdxSipsService` | Deuda técnica | Aceptable en v1; refactor unificar auth en iteración posterior |

---

## 8. Plan de pruebas manual (sin ejecutar suite automática)

1. **SIPS AUDAX:** consulta luz/gas, verificar persistencia y UI consumo.
2. **SIPS ADX:** consulta Electricity/Gas, verificar suministros + lecturas sin BD.
3. **Tarifas ADX:** modal XL, selección ventana, campos en fila y save contrato.
4. **Servicios contrato:** toggles en multipunto/unipunto/edición, persistencia BD.
5. **OK Comercial:** modal canal/comercial → job → historial proceso con body correcto.
6. **Documentos:** envío con canal/comercial.
7. **Tramitar Tip 1/2:** representante en modal, body integración, PDF condiciones particulares.
8. **Regresión develop:** historial CUPS, tabs accesibles, carga masiva con barra progreso, tarjetas listados.

---

## 9. Artefactos relacionados

| Documento | Contenido |
|-----------|-----------|
| [plan.md](./plan.md) | Plan de implementación por fases y PRs |
| [quickstart.md](./quickstart.md) | Guía rápida desarrollador (rama, BD, env) |
| [research.md](./research.md) | Análisis diff ramas, commits, inventario archivos |
| [data-model.md](./data-model.md) | Cambios BD y modelo Eloquent |
| [contracts/api-adx-integracion.md](./contracts/api-adx-integracion.md) | Contratos API internos y externos |
| [constraints-develop-eneon.md](./constraints-develop-eneon.md) | Inventario detallado de lo que NO tocar |
| [tasks.md](./tasks.md) | Checklist accionable (83 tareas, 7 PRs) |

---

## 10. Commits de referencia en `version2`

| Commit | Descripción |
|--------|-------------|
| `72522fdb` | Tramitaciones OKCom y documentaciones por canal |
| `c2cb4142` | Representante legal TipProCom 1 y 2 |
| `d9440169` / `feada276` | Módulo SIPS ADX (fases 1 y 2) |
| `85666164` / `b35d8efc` / `002e62b6` / `143da710` / `d460ae77` | Tarifas ADX, columnas servicios, tooltips, ajustes finales |