# Botón "Descargar recibo" invisible en el Paso 4 de nuevo ingreso

- **Código:** BUG-005
- **Tipo:** bugfix
- **Estado:** en curso

## Objetivo

Lograr que el botón "Descargar recibo" del bloque "Pago aprobado" del Paso 4 de nuevo ingreso sea visible y legible en tema claro y oscuro, sin cambiar su comportamiento ni el endpoint del recibo. Además, alinear todas las clases de `estado.php` que hoy no existen en el CSS compilado con clases equivalentes ya disponibles.

## Alcance

- Incluye: reemplazar en `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` las clases de Tailwind ausentes del CSS compilado por equivalentes existentes (15 clases, incluida la del botón).
- Incluye: verificar visualmente todos los estados de la vista (aprobado, pendiente, creado, pagando, reintento, cancelado) en tema claro y oscuro.
- No incluye: recompilar `public/css/tailwind-v4.css` ni editar manualmente ese archivo generado.
- No incluye: modificar rutas, filtros, controladores, servicios de pago, el endpoint `/inscripciones/nuevo-ingreso/paso-4/recibo/{id}` ni el PDF.
- No incluye: corregir clases ausentes en otras vistas del portal. Es deuda separada.
- No incluye: agregar pruebas automatizadas nuevas; la verificación principal es manual por decisión del usuario.

## Problema

En el Paso 4 de nuevo ingreso, cuando la intención está en estado aprobado (`estados_id` 3 u 8), el enlace "Descargar recibo" se renderiza sin fondo y con texto e icono en blanco, por lo que parece un botón en blanco o vacío. El enlace sigue funcionando y el PDF se descarga, pero la acción no se descubre visualmente.

El defecto se observa en tema claro y oscuro y solo se ha reportado en local/desarrollo.

## Impacto

- **Usuarios:** aspirantes de nuevo ingreso con pago aprobado. No se bloquea la descarga, pero se oculta la única acción visible para obtener el recibo; el usuario puede creer que no existe o que el proceso está incompleto.
- **Procesos:** no hay impacto en datos, pagos ni estados. El endpoint del recibo y el PDF funcionan.
- **Gravedad:** media-baja. Es un defecto de presentación y descubribilidad, no de integridad.
- **Producción:** no hay evidencia de afectación en producción; el usuario confirmó que se reproduce solo en local/desarrollo. Por eso se clasifica como **bugfix** y no como hotfix.
- **Alcance:** una vista (`app/Views/inscripciones/nuevo_ingreso/paso3/estado.php`) y solo clases CSS.

## Reproducción

1. En un entorno local o de desarrollo, iniciar sesión con una postulación de nuevo ingreso que tenga una intención de pago en estado aprobado (`pg_intenciones_pago.estados_id` igual a `3` u `8`) y `ni_inscripcion_id` de esa postulación.
2. Abrir `/inscripciones/nuevo-ingreso/paso-4` (ruta `Paso3::index`, filtro `nuevoIngresoAuth:4`).
3. Observar el bloque "Pago aprobado" y el botón "Descargar recibo".
4. Resultado actual: el botón no tiene fondo verde; el texto "Descargar recibo" y el icono `download` son blancos y no se distinguen del fondo de la página o del panel. El área parece vacía.
5. Activar el tema oscuro y repetir.
6. Resultado actual: el botón sigue sin fondo y el texto blanco queda sobre el panel claro porque las variantes `dark:` del panel tampoco están compiladas.
7. Hacer clic en el botón.
8. Resultado actual: el PDF del recibo se abre o descarga correctamente; el defecto es solo visual.

## Comportamiento esperado

- El botón "Descargar recibo" muestra fondo verde, texto blanco e icono visibles en tema claro y oscuro.
- El estado hover del botón es perceptible.
- El clic sigue abriendo `/inscripciones/nuevo-ingreso/paso-4/recibo/{id}` en una pestaña nueva y el PDF se descarga como hoy.
- Los paneles de los estados pendiente, creado, pagando, reintento y cancelado conservan contraste y legibilidad en ambos temas.
- No cambia ningún texto, ruta, filtro, monto, estado ni comportamiento funcional.

## Causa raíz (hipótesis)

Hipótesis confirmada por inspección del CSS compilado y del historial de git; la reproducción visual en navegador queda pendiente de ejecutar en desarrollo.

`estado.php` usa clases de Tailwind que no existen en los CSS compilados que carga el layout de nuevo ingreso:

- `app/Views/inscripciones/nuevo_ingreso/layout/header.php:14-15` carga `public/css/tailwind.css` (generado el 16/10/2026) y `public/css/tailwind-v4.css` (generado el 19/10/2026).
- El botón se agregó en el commit `860a1d2` del 28/10/2026 (`feat: agregar recibo PDF de nuevo ingreso con builder compartido`), después de la última compilación del CSS.
- `public/css/tailwind-v4.css` no contiene `.bg-emerald-600` ni `.hover\:bg-emerald-700`. `public/css/tailwind.css` solo contiene `.dark\:bg-emerald-600`, no la variante sin `dark:`.
- `.text-white` sí existe en ambos CSS. Al combinarse un texto blanco con un fondo inexistente, el texto y el icono desaparecen sobre fondos claros.
- El panel aprobado usa `dark:bg-emerald-950/40` y `dark:border-emerald-900/60`, que tampoco están compiladas; en tema oscuro el panel conserva el fondo claro `bg-emerald-50`, de modo que el texto blanco sigue siendo invisible.

En total faltan 15 clases de Tailwind en la vista (se excluye `material-icons`, que lo provee `public/css/material-icons.css`, y `space-y-3`, que sí existe):

`bg-emerald-600`, `hover:bg-emerald-700`, `dark:bg-amber-950/40`, `dark:border-amber-900/60`, `text-amber-700`, `dark:text-amber-300/90`, `dark:text-amber-200`, `dark:bg-emerald-950/40`, `dark:border-emerald-900/60`, `dark:text-emerald-300/90`, `dark:border-blue-900/60`, `dark:text-blue-300/90`, `dark:border-red-900/60`, `hover:bg-red-50` y `dark:hover:bg-red-950/30`.

La causa de fondo es que el CSS compilado está desactualizado respecto a las clases que usan las vistas. Este plan no recompila (decisión del usuario); corrige la vista usando clases que ya existen en los CSS cargados.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `docs/bugfix/005-boton-descargar-recibo-invisible/plan.md` | Documento de este plan. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Reemplazar las 15 clases ausentes por equivalentes ya compilados. No se cambian textos, URLs, condiciones ni estructura. |

No se modifica `public/css/tailwind-v4.css` ni `public/css/tailwind.css`: son archivos generados y el usuario optó por no recompilar.

### Mapa de reemplazo propuesto

Cada clase destino se verificó como presente en al menos uno de los dos CSS que carga el layout. Se indica el archivo cuando solo existe en uno.

| Línea(s) | Clase actual (ausente) | Reemplazo propuesto | Dónde existe |
| --- | --- | --- | --- |
| 47 | `bg-emerald-600` | `bg-green-600` | `tailwind.css` y `tailwind-v4.css` |
| 47 | `hover:bg-emerald-700` | `hover:bg-green-700` | ambos |
| 17 | `dark:bg-emerald-950/40` | `dark:bg-emerald-900/40` | `tailwind.css` |
| 17 | `dark:border-emerald-900/60` | `dark:border-green-800/40` | ambos |
| 22 | `dark:text-emerald-300/90` | `dark:text-emerald-300` | `tailwind.css` |
| 54 | `dark:bg-amber-950/40` | `dark:bg-amber-900/30` | ambos |
| 54 | `dark:border-amber-900/60` | `dark:border-amber-700/50` | ambos |
| 59 | `text-amber-700` | `text-amber-800` | ambos |
| 59 | `dark:text-amber-300/90` | `dark:text-amber-300` | ambos |
| 68 | `dark:text-amber-200` | `dark:text-amber-300` | ambos |
| 74, 121 | `dark:border-blue-900/60` | `dark:border-blue-900/30` | ambos |
| 79, 126 | `dark:text-blue-300/90` | `dark:text-blue-300` | ambos |
| 107, 146 | `dark:border-red-900/60` | `dark:border-red-900/30` | ambos |
| 107, 146 | `hover:bg-red-50` | `hover:bg-gray-50` | ambos |
| 107, 146 | `dark:hover:bg-red-950/30` | `dark:hover:bg-slate-700/50` | ambos |

Notas del mapa:

- Las líneas corresponden al archivo actual y pueden desplazarse al editar; el programador debe localizar por clase, no solo por número.
- `hover:bg-red-50` se sustituye por un gris muy claro para conservar el efecto de hover sin un rojo sólido. Es una aproximación visual: el botón "Cancelar pago" ya no tendrá tinte rojo al pasar el cursor.
- `dark:hover:bg-red-950/30` se sustituye por un slate oscuro por la misma razón; no existe una variante roja oscura compilada.
- `dark:border-emerald-900/60` pasa a verde; el cambio de matiz es leve y mantiene la semántica de "aprobado".
- Las dos clases que solo están en `tailwind.css` (`dark:bg-emerald-900/40` y `dark:text-emerald-300`) y las que podrían depender de un solo archivo funcionan porque el layout carga ambos CSS en el orden `tailwind.css` y luego `tailwind-v4.css`.

## Plan de verificación

### Prueba manual (flujo normal)

> Requiere una postulación de nuevo ingreso en desarrollo con una intención en estado aprobado (`3` u `8`). No usar datos reales de producción.

1. Abrir `/inscripciones/nuevo-ingreso/paso-4` con la sesión de la postulación aprobada.
2. En tema claro, confirmar que el bloque "Pago aprobado" muestra el botón "Descargar recibo" con fondo verde, texto blanco e icono de descarga visibles.
3. Pasar el cursor sobre el botón y confirmar que el fondo cambia a un verde más oscuro.
4. Activar el tema oscuro y confirmar que el panel cambia a fondo oscuro y que el botón sigue visible y legible.
5. Hacer clic en "Descargar recibo".
6. Resultado esperado: se abre en una pestaña nueva `/inscripciones/nuevo-ingreso/paso-4/recibo/{id}` y el PDF se descarga o visualiza correctamente, igual que antes.
7. Revisar los estados pendiente, creado, pagando, reintento y cancelado con datos de prueba (o cambiando el estado de la intención en desarrollo).
8. Resultado esperado: títulos, párrafos, montos, botones y bordes mantienen contraste y legibilidad en ambos temas; no hay texto invisible.
9. Revisar los botones "Cancelar pago" en tema claro y oscuro, incluido el hover.
10. Resultado esperado: el borde y el texto rojo se mantienen; el hover es perceptible (gris claro en tema claro, slate oscuro en tema oscuro).

### Prueba automatizada / código de verificación

No se crea una prueba nueva: el usuario eligió verificación manual y PHPUnit no evalúa el renderizado visual del CSS. Sin embargo, se deben ejecutar las pruebas existentes del área para confirmar que el cambio de clases no alteró el marcado, los textos ni el endpoint del recibo.

Comandos:

```sh
vendor\bin\phpunit.bat tests\app\Integration\Paso4NuevoIngresoTest.php --no-coverage
vendor\bin\phpunit.bat tests\app\Integration\Paso4ReciboTest.php --no-coverage
```

Estado de referencia verificado antes de este plan:

- `Paso4NuevoIngresoTest`: OK, 27 tests, 129 assertions. Incluye aserciones sobre la presencia de "Descargar recibo" y la ruta `paso-4/recibo/`.
- `Paso4ReciboTest`: OK, 7 tests, 17 assertions.

Ambas suites deben seguir en verde después del cambio, porque el texto y las URLs no se modifican.

Verificación opcional de soporte de clases (no es una prueba commiteada; confirma que los reemplazos existen en los CSS cargados):

```powershell
$css = (Get-Content public/css/tailwind.css -Raw) + (Get-Content public/css/tailwind-v4.css -Raw)
@('bg-green-600','hover:bg-green-700','dark:bg-emerald-900/40','dark:border-green-800/40','dark:text-emerald-300','dark:bg-amber-900/30','dark:border-amber-700/50','text-amber-800','dark:text-amber-300','dark:border-blue-900/30','dark:text-blue-300','dark:border-red-900/30','hover:bg-gray-50','dark:hover:bg-slate-700/50') | ForEach-Object {
    $escaped = $_ -replace '([:/\[\]\.])', '\$1'
    $pattern = '\.' + [regex]::Escape($escaped) + '(?![A-Za-z0-9_\-\\])'
    [pscustomobject]@{ Clase = $_; Presente = [regex]::IsMatch($css, $pattern) }
} | Format-Table -AutoSize
```

Todas las filas deben mostrar `Presente = True`.

## Riesgos y efectos secundarios

- **Cambios visuales menores:** los reemplazos no son idénticos. El hover de "Cancelar pago" pasa de rojo claro a gris claro, y el borde oscuro del panel aprobado pasa de emerald a green. Son aproximaciones deliberadas para usar clases ya compiladas.
- **Dependencia de dos hojas de estilo:** `dark:bg-emerald-900/40` y `dark:text-emerald-300` solo existen en `tailwind.css`; el resto se cubre entre ambas. Si en el futuro se deja de cargar `tailwind.css`, esas dos variantes fallarían. El layout actual carga ambas.
- **La causa de fondo persiste:** el CSS compilado sigue desactualizado. Cualquier clase nueva que se agregue a una vista y no se recompile volverá a quedar sin efecto. Se recomienda un `chore` separado para recompilar con `npm run build` y, opcionalmente, una comprobación en CI.
- **No se corrige el resto del proyecto:** otras vistas pueden tener el mismo problema si usan clases no compiladas. Queda fuera de este bugfix.
- **Sin impacto funcional:** no se tocan el controlador, las rutas, el filtro `nuevoIngresoAuth`, el servicio de recibo ni el PDF. La descarga y los estados no cambian.
- **Archivo generado:** no se debe editar `public/css/tailwind-v4.css` a mano; si se recompila en el futuro, el resultado debe provenir de `npm run build`.
- **Numeración:** se verificó que `001` a `004` ya existen en `docs/bugfix/`; este plan usa `005` sin colisión.

## Criterios de finalización

- [ ] El botón "Descargar recibo" se ve con fondo verde, texto e icono blancos en tema claro.
- [ ] El botón se ve correctamente en tema oscuro, junto con el panel "Pago aprobado".
- [ ] El hover del botón es perceptible.
- [ ] El clic sigue abriendo `/inscripciones/nuevo-ingreso/paso-4/recibo/{id}` y descargando el PDF.
- [ ] No quedan clases de Tailwind ausentes en `estado.php` (salvo `material-icons`, provisto por otra hoja).
- [ ] Los estados pendiente, creado, pagando, reintento y cancelado se ven legibles en ambos temas.
- [ ] `Paso4NuevoIngresoTest` y `Paso4ReciboTest` siguen en verde.
- [ ] No se modificaron rutas, filtros, controladores, pagos, PDFs, `tailwind.css` ni `tailwind-v4.css`.
- [ ] Se documentó en este plan que la desactualización del CSS compilado queda como deuda separada.

## Notas del programador

- Este plan no implementa la corrección; define alcance, causa y verificación.
- Se consultó `graphify-out/graph.json` para ubicar `Recibo`, `ReciboPdfBuilder`, `estado.php` y las pruebas del recibo. No se ejecuta `graphify update .` porque este entregable solo agrega documentación.
- Evidencia de la causa: el botón se agregó en `860a1d2` (28/10/2026); `tailwind-v4.css` se generó el 19/10/2026 y `tailwind.css` el 16/10/2026. La inspección de ambos archivos confirma la ausencia de `.bg-emerald-600` y de las demás clases listadas.
- Decisiones del usuario: reutilizar clases existentes (no recompilar), corregir todas las clases ausentes de la vista y no crear prueba automatizada nueva.
- Para implementar, editar `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` aplicando el mapa de reemplazo, sin tocar textos ni atributos de comportamiento (`href`, `target`, `rel`, `method`, `data-confirm`).
- Si durante la verificación se detecta otra clase ausente en la vista, agregarla al mapa y verificarla con el comando opcional antes de cerrar.
- `MEMORY.md` no existe en este checkout, aunque `AGENTS.md` lo referencia; no se actualiza en este plan.
- Siguiente paso sugerido: implementar el cambio en la rama actual `feature/desacoplar-contructor-pagos` y ejecutar la prueba manual en desarrollo; después, abrir un `chore` para recompilar Tailwind y evitar que el CSS vuelva a quedar desactualizado.
