# Extraer la paginación del panel Zelle a un partial reutilizable

- **Código:** REF-004
- **Tipo:** refactor
- **Estado:** completado
- **Fecha:** 2026-10-30
- **Autor:** Antigravity (agente)

## Objetivo

Extraer el marcado y la lógica de construcción de enlaces de paginación de la vista `app/Views/admin/zelle/reportes.php` hacia un partial reutilizable en `app/Views/admin/templates/_paginacion.php`, parametrizado por URL base, número de página actual, total de páginas y parámetros de consulta (`query params`), sin alterar el HTML generado, los estilos CSS, las clases de Tailwind ni la preservación de filtros en las URLs generadas.

## Motivación

Actualmente el bloque de paginación está acoplado de forma rígida dentro de `app/Views/admin/zelle/reportes.php`. La implementación calcula internamente un closure `$url` que concatena la ruta fija `admin/panel/zelle/reportes`, dificultando su reutilización en otras vistas administrativas (como el próximo listado de postulaciones de nuevo ingreso en el Slice 4/5 de `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`). Además, duplicar dicho marcado en nuevos módulos incrementaría la deuda técnica y el costo de mantenimiento de los estilos y comportamiento de la paginación administrativa.

## Estado actual

- En `app/Views/admin/zelle/reportes.php` (líneas 194-216), la paginación se renderiza condicionalmente si `$total_paginas > 1`.
- Se genera un arreglo local `$queryBase` filtrando las claves de `$filtros` que no estén vacías (`fn($v) => $v !== ''`).
- Se define una función anónima `$url = function (int $p) use ($queryBase) { return base_url('admin/panel/zelle/reportes?' . http_build_query($queryBase + ['page' => $p])); };`.
- Se imprimen los botones "Anterior" y "Siguiente" con clases Tailwind condicionales (`pointer-events-none opacity-50` cuando se alcanza el límite y `hover:bg-slate-100 dark:hover:bg-slate-800` cuando está habilitado).
- No existe un componente o plantilla compartida para paginación dentro de `app/Views/admin/templates/` (solo existen `header.php` y `footer.php`).
- No existen pruebas unitarias o de integración automatizadas en `tests/app/` que validen la salida HTML de `app/Views/admin/zelle/reportes.php`.

## Qué mejora este refactor

- **Mantenibilidad:** Centraliza en una única plantilla partial los estilos visuales, accesibilidad y lógica de enlaces de paginación para el panel administrativo.
- **Duplicación / acoplamiento:** Desacopla la vista de reportes Zelle del algoritmo de construcción de enlaces de página, permitiendo que futuras vistas administrativas reutilicen la misma plantilla sin duplicar HTML ni estilos Tailwind.
- **Testabilidad:** Al aislar el partial en `app/Views/admin/templates/_paginacion.php`, es posible escribir pruebas unitarias de renderizado con diferentes combinaciones de filtros, límites y páginas sin necesidad de instanciar la base de datos ni la sesión administrativa completa.
- **Legibilidad:** Reduce el ruido visual en `app/Views/admin/zelle/reportes.php`, reemplazando ~25 líneas de lógica y marcado repetido por una invocación limpia `<?= view('admin/templates/_paginacion', [...]); ?>`.
- **Rendimiento:** Equivalente; no realiza consultas adicionales a base de datos ni procesamiento pesado en runtime.

## Invariantes (qué NO debe cambiar)

- **Marcado y estilos exactos:** El HTML generado, las etiquetas `<a>` y `<span>`, el texto (`Anterior`, `P&aacute;gina X de Y`, `Siguiente`), y las clases Tailwind exactas (`flex items-center justify-center gap-2 mt-6`, `px-3 py-1.5 rounded border border-slate-300 dark:border-slate-600 text-sm ...`) deben ser idénticos.
- **Comportamiento en límites:** 
  - Si `$page <= 1`, el enlace "Anterior" apunta a página 1 y mantiene `pointer-events-none opacity-50`.
  - Si `$page >= $total_paginas`, el enlace "Siguiente" apunta a `$total_paginas` y mantiene `pointer-events-none opacity-50`.
  - Si `$total_paginas <= 1`, no se debe renderizar ningún bloque HTML visible (cadena vacía).
- **Parámetros de consulta (Query Strings):** Los filtros activos (`estado`, `identificacion`, `remitente`, `nro_confirmacion`, `desde`, `hasta`, `sucursal`, etc.) deben preservarse fielmente en el parámetro `href` generado mediante `http_build_query(...)`.
- **Rutas y contratos HTTP:** Ninguna ruta, controlador ni contrato de respuesta HTTP del panel administrativo (`admin/panel/zelle/reportes`) se modifica.

## Alcance

- **Incluye:**
  - Creación del partial `app/Views/admin/templates/_paginacion.php`.
  - Parametrización para recibir: `$baseUrl` (string), `$page` (int), `$total_paginas` o `$totalPaginas` (int), y `$queryParams` (array asociativo de parámetros adicionales).
  - Manejo interno en el partial para retornar vacío cuando `$total_paginas <= 1`.
  - Sustitución del bloque de paginación en `app/Views/admin/zelle/reportes.php` por la llamada `view('admin/templates/_paginacion', [...])`.
  - Creación de pruebas de caracterización de la vista en `tests/app/Views/Admin/PaginationPartialTest.php`.
- **No incluye:**
  - Modificación del controlador `app/Controllers/Admin/Panel.php`.
  - Adopción de la paginación en otros módulos no relacionados (eso corresponde a sus respectivos slices/features).
  - Modificación de estilos visuales, temas oscuro/claro o adición de números de página individuales (eso constituiría un cambio funcional o de diseño).

## Contexto y supuestos

- **Framework:** CodeIgniter 4.0.3 provee el helper/función `view($name, $data)` que renderiza plantillas y hereda el contexto de datos proporcionado.
- **Convención de partials:** En `app/Views/admin/zelle/` se usa el patrón `_estado_badge.php` con prefijo de guión bajo para partials incluidos; se adopta la misma convención: `app/Views/admin/templates/_paginacion.php`.
- **Soporte de claves variables:** Para máxima flexibilidad y compatibilidad, el partial aceptará tanto `$total_paginas` como `$totalPaginas`, y construirá la URL base agregando `?` o `&` según corresponda si `$baseUrl` ya contuviera query strings preexistentes.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `app/Views/admin/templates/_paginacion.php` | Nuevo partial reutilizable de paginación para el panel administrativo. |
| Modificar | `app/Views/admin/zelle/reportes.php` | Reemplazar bloque inline de paginación por `view('admin/templates/_paginacion', ...)`. |
| Agregar | `tests/app/Views/Admin/PaginationPartialTest.php` | Pruebas de caracterización que verifiquen el HTML generado y la preservación de parámetros. |

## Plan de pasos

1. **Paso 1: Escribir la prueba de caracterización previa**
   - Crear `tests/app/Views/Admin/PaginationPartialTest.php` extendiendo `CodeIgniter\Test\CIUnitTestCase`.
   - Probar escenarios antes de modificar código:
     - Escenario 1: `$total_paginas <= 1` produce salida vacía.
     - Escenario 2: `$page = 1` y `$total_paginas = 5` con filtros activos (deshabilita "Anterior", habilita "Siguiente", preserva query params en href).
     - Escenario 3: `$page = 3` y `$total_paginas = 5` (habilita ambos enlaces con sus respectivas páginas 2 y 4).
     - Escenario 4: `$page = 5` y `$total_paginas = 5` (habilita "Anterior", deshabilita "Siguiente").
     - Escenario 5: Caracteres especiales y filtros múltiples escapados correctamente por `http_build_query`.

2. **Paso 2: Crear el partial `app/Views/admin/templates/_paginacion.php`**
   - Normalizar variables de entrada con valores por defecto seguros:
     - `$page = (int) ($page ?? 1);`
     - `$total_paginas = (int) ($total_paginas ?? $totalPaginas ?? 1);`
     - `$baseUrl = (string) ($baseUrl ?? '');`
     - `$queryParams = (array) ($queryParams ?? $filtros ?? []);`
   - Retornar vacío si `$total_paginas <= 1`.
   - Construir la función o cálculo de URL respetando `base_url()` y `http_build_query()`.
   - Trasladar el bloque HTML exacto de Tailwind presente en `reportes.php`.

3. **Paso 3: Refactorizar `app/Views/admin/zelle/reportes.php`**
   - Mantener el arreglo `$queryBase` filtrado con `array_filter` (para no enviar claves vacías a la URL).
   - Sustituir las líneas 194-216 por la llamada a la vista:
     ```php
     <?= view('admin/templates/_paginacion', [
         'baseUrl'       => 'admin/panel/zelle/reportes',
         'page'          => $page,
         'total_paginas' => $total_paginas,
         'queryParams'   => $queryBase,
     ]); ?>
     ```

4. **Paso 4: Ejecución de pruebas automatizadas**
   - Ejecutar la suite de pruebas unitarias sobre `PaginationPartialTest`.
   - Asegurar que no haya regresiones.

5. **Paso 5: Verificación y smoke test manual**
   - Iniciar sesión administrativa y navegar a `admin/panel/zelle/reportes`.
   - Validar paginación con filtros activos y comprobar que los enlaces navegan correctamente sin cambios visuales ni roturas de filtros.

## Estrategia de verificación

### Pruebas existentes que cubren el comportamiento
- No existen pruebas de vista automatizadas previas para el módulo Zelle en `tests/app/`.

### Pruebas de caracterización (si no hay cobertura)
- Se implementará `tests/app/Views/Admin/PaginationPartialTest.php` con casos de prueba:
  - `testNoRenderizaCuandoTotalPaginasEsMenorOIgualAUno()`: valida cadena vacía o sin marcado para `0` y `1`.
  - `testRenderizaPrimeraPaginaConBotonAnteriorDeshabilitado()`: valida clases de opacidad y `pointer-events-none` en "Anterior".
  - `testRenderizaPaginaIntermediaConAmbosBotonesHabilitados()`: valida enlaces a `$page - 1` y `$page + 1`.
  - `testRenderizaUltimaPaginaConBotonSiguienteDeshabilitado()`: valida clases en "Siguiente".
  - `testPreservaParametrosDeConsultaEnEnlaces()`: valida que parámetros como `sucursal`, `desde`, `hasta`, `estado` se conserven idénticos a los generados previamente.

### Prueba manual (smoke test)
1. Entrar con credenciales administrativas a `/admin/panel/zelle/reportes`.
2. Aplicar un filtro que devuelva más de una página de resultados (e.g. estado "Aprobado" o rango de fechas).
3. Inspeccionar el HTML del bloque de paginación: verificar que las clases Tailwind, tipografías y textos coincidan exactamente con la versión previa.
4. Hacer clic en "Siguiente" y verificar que la URL conserve todos los filtros (`&estado=...&desde=...&page=2`).
5. En la página 2, hacer clic en "Anterior" y verificar el retorno a la página 1 con los filtros intactos.
6. Aplicar un filtro que retorne 1 o 0 registros y verificar que el bloque de paginación desaparezca limpiamente sin warnings de PHP.

## Riesgos y efectos secundarios

- **Riesgo:** Incompatibilidad en nombres de variables al invocar la vista partial (por ejemplo, usar `$totalPaginas` en lugar de `$total_paginas`).
  - **Mitigación:** El partial soportará defensivamente ambas nomenclaturas (`$total_paginas ?? $totalPaginas ?? 1`).
- **Riesgo:** Omisión de filtros en la query string si `$queryParams` contiene valores nulos o vacíos.
  - **Mitigación:** Mantener la limpieza de filtros vacíos con `array_filter` antes de delegar al helper `http_build_query`.

## Rollback

Para revertir el cambio en caso de problemas:
1. Restaurar `app/Views/admin/zelle/reportes.php` a su versión original desde git (`git checkout HEAD -- app/Views/admin/zelle/reportes.php`).
2. Eliminar el partial `app/Views/admin/templates/_paginacion.php` y el archivo de pruebas `tests/app/Views/Admin/PaginationPartialTest.php`.

## Criterios de finalización

- [x] El partial `app/Views/admin/templates/_paginacion.php` ha sido creado e implementado sin lógica de negocio ni dependencias externas.
- [x] La vista `app/Views/admin/zelle/reportes.php` utiliza el partial reutilizable.
- [x] La salida HTML, clases CSS y enlaces generados son idénticos a la versión original.
- [x] La suite de pruebas de caracterización `tests/app/Views/Admin/PaginationPartialTest.php` pasa satisfactoriamente al 100%.
- [x] El smoke test manual confirma la navegación fluida y la preservación de filtros en el panel Zelle.

## Preguntas abiertas

- Ninguna. Las decisiones de diseño (convención `_paginacion.php`, contrato de parámetros y condición de visibilidad interna) fueron resueltas durante la entrevista de aclaración.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Creación del plan de refactorización para extraer la paginación del panel Zelle (Slice 3). | Antigravity (agente) |
