# Logos de bancos rotos en las formas de pago de nuevo ingreso

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

## Objetivo

Lograr que la lista de formas de pago del Paso 4 de nuevo ingreso muestre correctamente los logos de los bancos en las familias "Pagar en línea" (`po`) y "Reportar pagos" (`rp`). La imagen debe resolverse contra `public/assets/bancos`, respetar rutas o URLs ya configuradas y mostrar un icono de respaldo cuando no haya logo o el archivo no exista.

## Alcance

- Incluye: normalizar la resolución de `pg_bancos.logo` en la vista parcial compartida `app/Views/pagos/partials/_formas_pago.php`.
- Incluye: soportar nombre de archivo simple (`banesco.png`), ruta relativa (`assets/bancos/banesco.png`, `imagenes/bancos/banesco.png`) y URL absoluta (`https://...`).
- Incluye: mostrar el icono `account_balance` cuando el logo venga vacío, cuando el archivo local no exista o cuando una URL remota no cargue.
- Incluye: verificación manual en ambas familias y una prueba PHPUnit nueva sobre el HTML renderizado por la vista parcial.
- No incluye: modificar la base de datos, `pg_bancos`, `pg_formas_pago`, sus seeders o migraciones.
- No incluye: modificar `FormasPagoModel`, `NuevoIngresoPagoService`, el controlador `Paso3`, las rutas, los filtros ni el flujo de pago.
- No incluye: corregir `app/Views/pagos/elegir_tp_forma_pago.php`; ese flujo legacy ya antepone `/assets/bancos/` y no forma parte del reporte.
- No incluye: eliminar o unificar las carpetas duplicadas `public/assets/bancos` y `public/imagenes/bancos`.
- No incluye: reemplazar archivos de imagen, recompilar Tailwind ni tocar CSS.

## Problema

En el Paso 4 de nuevo ingreso, al entrar a "Pagar en línea" o "Reportar pagos", todas las tarjetas de formas de pago que tienen logo muestran la imagen rota. El texto, el banco y el enlace de la forma de pago sí funcionan; el defecto es visual y no bloquea el pago.

El usuario confirmó la petición fallida:

```text
http://localhost/PORTAL-ESTUDIANTIL-V2/public/banesco.png
```

El navegador busca el archivo en la raíz pública, pero los logos están en `public/assets/bancos/`.

## Impacto

- **Usuarios:** aspirantes de nuevo ingreso en local/desarrollo. Ven las tarjetas sin el identificador visual del banco o pasarela, lo que reduce la confianza y dificulta reconocer la forma de pago.
- **Procesos:** no se bloquea la selección ni el pago. No hay impacto en montos, estados, intenciones ni datos.
- **Gravedad:** baja. Es un defecto de presentación y no de integridad.
- **Producción:** el usuario confirmó que solo se reproduce en local/desarrollo. No hay evidencia de afectación a producción, por lo que se clasifica como **bugfix** y no como hotfix.
- **Alcance:** ambas familias (`po` y `rp`) porque comparten la misma vista parcial; todas las formas con logo se ven afectadas.

## Reproducción

1. En local, iniciar una postulación de nuevo ingreso con una intención de pago en estado `pagando`.
2. Abrir `/inscripciones/nuevo-ingreso/paso-4/metodos` (ruta `Paso3::metodos`, filtro `nuevoIngresoAuth:4`).
3. Entrar a "Reportar pagos" (`/inscripciones/nuevo-ingreso/paso-4/reportar`).
4. Resultado actual: las tarjetas de las formas de pago con `pg_bancos.logo` no vacío muestran la imagen rota.
5. Repetir con "Pagar en línea" (`/inscripciones/nuevo-ingreso/paso-4/en-linea`).
6. Resultado actual: también se ven rotas.
7. Abrir la pestaña Red del navegador y recargar.
8. Resultado actual: la petición del logo apunta a `.../public/banesco.png` (u otro nombre de archivo) y devuelve 404; no incluye la carpeta `assets/bancos/`.

## Comportamiento esperado

- Cada logo se carga desde `public/assets/bancos/{archivo}` cuando `pg_bancos.logo` contiene solo el nombre del archivo.
- Si `pg_bancos.logo` ya contiene una ruta relativa, se respeta sin duplicar segmentos.
- Si `pg_bancos.logo` es una URL absoluta, se usa tal cual.
- Si el logo está vacío, el archivo local no existe o una URL remota falla, se muestra el icono `account_balance` en lugar de una imagen rota.
- El enlace a `paso-4/prepago/{codigo}/{intencion}` y el resto de la tarjeta no cambian.
- El defecto deja de reproducirse en ambas familias y en tema claro/oscuro.

## Causa raíz (hipótesis)

Hipótesis confirmada por inspección del código, de los datos sembrados y de la evidencia de red aportada por el usuario; la reproducción visual en navegador queda pendiente de ejecutar durante la verificación.

- `app/Views/pagos/partials/_formas_pago.php:27` toma `$forma['logo']`.
- En `app/Views/pagos/partials/_formas_pago.php:31-36`, si el logo no es una URL absoluta, se construye con `base_url(ltrim($logo, '/'))`. Un valor `banesco.png` se convierte en `http://localhost/PORTAL-ESTUDIANTIL-V2/public/banesco.png`, sin la carpeta `assets/bancos/`.
- `app/Models/PagosOnline/FormasPagoModel.php:109` entrega `pg_bancos.logo AS logo`, y `app/Database/Seeds/PgBancosSeeder.php:19`, `:33`, `:47`, `:61`, `:355` y `:369` siembra nombres simples como `banesco.png`, `mercantil.png`, `bnc.png`, `unir.png`, `venezuela.png` y `zelle.png`.
- Los archivos existen en `public/assets/bancos/` y también en `public/imagenes/bancos/`; la carpeta canónica elegida es `public/assets/bancos/`.
- El flujo legacy `app/Views/pagos/elegir_tp_forma_pago.php:66` ya usa `base_url('/assets/bancos/' . $formas_pago[$i]['logo'])`, lo que confirma el prefijo correcto.
- La vista parcial y su llamada desde nuevo ingreso se incorporaron en el commit `b66d673` (`feat(nuevo-ingreso): implementar metodos y pago en linea del paso 4`). El defecto está presente desde entonces.

La causa es la resolución incompleta de la ruta del logo en la vista compartida, no un problema de datos ni de permisos.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `docs/bugfix/006-logos-bancos-formas-pago-nuevo-ingreso/plan.md` | Documento de este plan. |
| Modificar | `app/Views/pagos/partials/_formas_pago.php` | Resolver el logo contra `assets/bancos`, respetar rutas/URLs y aplicar el icono de respaldo. Es la única vista que usa el flujo de nuevo ingreso para listar formas de pago. |
| Agregar (al implementar) | `tests/app/Integration/FormasPagoLogoTest.php` | Prueba de regresión sobre el HTML renderizado por la vista parcial. Se propone en este plan; no se creó en esta fase para no dejar la suite en rojo antes de la corrección. |

No se modifican modelos, servicios, controladores, rutas, filtros, seeders, migraciones ni archivos generados de CSS.

### Cambio propuesto en la vista

Sustituir la resolución actual por una función local que aplique estas reglas, en este orden:

1. Hacer `trim` al valor; si queda vacío, devolver cadena vacía.
2. Si coincide con `^https?://`, devolver la URL tal cual.
3. Quitar las barras iniciales y normalizar separadores.
4. Si no contiene `/`, anteponer `assets/bancos/`.
5. Si contiene ruta, respetarla; si empieza por `public/`, quitar ese prefijo para no duplicar la carpeta pública.
6. Comprobar `is_file(FCPATH . $ruta)` para archivos locales. Si no existe, devolver cadena vacía.
7. Devolver `base_url($ruta)`.

Para las URLs remotas no se puede comprobar la existencia desde el servidor. Por eso la etiqueta `<img>` debe incluir un `onerror` que oculte la imagen y muestre un icono `account_balance` hermano. El HTML debe mantener el `alt` escapado y no interpolar datos de usuario en JavaScript.

Esbozo del bloque:

```php
$resolverLogo = static function (string $logo): string {
    $logo = trim($logo);

    if ($logo === '') {
        return '';
    }

    if (preg_match('#^https?://#i', $logo) === 1) {
        return $logo;
    }

    $ruta = ltrim(str_replace('\\', '/', $logo), '/');

    if (strpos($ruta, '/') === false) {
        $ruta = 'assets/bancos/' . $ruta;
    }

    if (strpos($ruta, 'public/') === 0) {
        $ruta = substr($ruta, strlen('public/'));
    }

    return is_file(FCPATH . $ruta) ? base_url($ruta) : '';
};
```

El icono de respaldo se renderiza cuando el resolvedor devuelve vacío. Cuando hay imagen, se agrega un icono oculto con `style="display:none"` y el `onerror` lo muestra:

```html
<img src="..." alt="..." onerror="this.style.display='none';this.nextElementSibling.style.display='inline-flex';">
<span class="material-icons text-primary dark:text-blue-400 text-2xl" style="display:none" aria-hidden="true">account_balance</span>
```

El programador puede ajustar el marcado siempre que conserve las reglas de resolución, el escapado y el respaldo visual.

## Plan de verificación

### Prueba manual (flujo normal)

> Usar una postulación de nuevo ingreso en local/desarrollo con una intención en estado `pagando`. No usar datos reales de producción.

1. Abrir `/inscripciones/nuevo-ingreso/paso-4` y entrar a "Pagar en línea" o directamente a `/inscripciones/nuevo-ingreso/paso-4/en-linea`.
2. Confirmar que cada tarjeta con logo muestra la imagen del banco o pasarela, sin icono roto.
3. Abrir la pestaña Red y recargar con caché deshabilitada.
4. Resultado esperado: las peticiones de logos apuntan a `.../assets/bancos/{archivo}` y responden 200. No debe aparecer ninguna petición a `.../public/{archivo}`.
5. Repetir en `/inscripciones/nuevo-ingreso/paso-4/reportar` (familia `rp`).
6. Resultado esperado: mismos logos correctos y ninguna imagen rota.
7. Alternar tema claro y oscuro.
8. Resultado esperado: los logos se mantienen legibles y el icono de respaldo, si aparece, conserva el color del tema.
9. Simular un logo inexistente (por ejemplo, cambiar temporalmente el valor solo en una copia local de la base de desarrollo a `no-existe.png`) y recargar.
10. Resultado esperado: no se muestra una imagen rota; se muestra el icono `account_balance`.
11. Dejar un logo vacío o nulo en la copia local y recargar.
12. Resultado esperado: se muestra el icono `account_balance` sin `<img>`.
13. Verificar que el clic en una tarjeta sigue llevando a `paso-4/prepago/{codigo}/{intencion}` y que el pago no cambia.
14. Revisar el flujo legacy de pagos regulares (`elegir_tp_forma_pago.php`) para confirmar que no se tocó y sigue igual.

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

Al implementar la corrección, agregar `tests/app/Integration/FormasPagoLogoTest.php` (namespace `App\Integration`, extiende `CodeIgniter\Test\CIUnitTestCase`). La prueba renderiza `pagos/partials/_formas_pago` con formas de ejemplo y valida:

- nombre simple (`banesco.png`) se resuelve en `assets/bancos/banesco.png` y no en la raíz;
- ruta relativa (`assets/bancos/bnc.png`) no se duplica;
- ruta alterna existente (`imagenes/bancos/banesco.png`) se respeta;
- URL absoluta se conserva;
- archivo inexistente (`no-existe.png`) muestra `account_balance` y no la ruta rota;
- logo vacío muestra `account_balance` y no renderiza `<img>`.

Contenido propuesto:

```php
<?php

namespace App\Integration;

use CodeIgniter\Test\CIUnitTestCase;

class FormasPagoLogoTest extends CIUnitTestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        helper('url');
    }

    public function testNombreSimpleUsaAssetsBancos(): void
    {
        $html = $this->render(['logo' => 'banesco.png']);

        $this->assertStringContainsString('assets/bancos/banesco.png', $html);
        $this->assertStringNotContainsString('src="' . base_url('banesco.png') . '"', $html);
    }

    public function testRutaRelativaSeRespeta(): void
    {
        $html = $this->render(['logo' => 'assets/bancos/bnc.png']);

        $this->assertSame(1, substr_count($html, 'assets/bancos/bnc.png'));
    }

    public function testRutaAlternaExistenteSeRespeta(): void
    {
        $html = $this->render(['logo' => 'imagenes/bancos/banesco.png']);

        $this->assertStringContainsString('imagenes/bancos/banesco.png', $html);
    }

    public function testUrlAbsolutaSeMantiene(): void
    {
        $url  = 'https://cdn.example.test/bancos/banesco.png';
        $html = $this->render(['logo' => $url]);

        $this->assertStringContainsString('src="' . $url . '"', $html);
    }

    public function testArchivoInexistenteMuestraIconoDeRespaldo(): void
    {
        $html = $this->render(['logo' => 'no-existe.png']);

        $this->assertStringNotContainsString('no-existe.png', $html);
        $this->assertStringContainsString('account_balance', $html);
    }

    public function testLogoVacioMuestraIconoDeRespaldo(): void
    {
        $html = $this->render(['logo' => '']);

        $this->assertStringNotContainsString('<img', $html);
        $this->assertStringContainsString('account_balance', $html);
    }

    private function render(array $forma): string
    {
        $forma += [
            'codigo'       => 'bnscboton',
            'descripcion'  => 'Banesco',
            'banco_nombre' => 'Banesco',
        ];

        return view('pagos/partials/_formas_pago', [
            'formas'       => [$forma],
            'urls'         => ['prepago' => base_url('inscripciones/nuevo-ingreso/paso-4/prepago')],
            'intencion_id' => 1,
            'tipo'         => 'po',
        ]);
    }
}
```

Comandos:

```sh
vendor\bin\phpunit.bat tests\app\Integration\FormasPagoLogoTest.php --no-coverage
vendor\bin\phpunit.bat tests\app\Integration\Paso4PagoTest.php --no-coverage
vendor\bin\phpunit.bat tests\app\Integration\Paso4NuevoIngresoTest.php --no-coverage
vendor\bin\phpunit.bat tests\app\Models\PagosOnline\FormasPagoModelTest.php --no-coverage
vendor\bin\phpunit.bat tests\app\Libraries\Inscripciones\NuevoIngreso\Pago\NuevoIngresoPagoServiceTest.php --no-coverage
```

La prueba nueva debe pasar después de la corrección. Antes de corregir, se espera que falle en el caso de nombre simple y en el de archivo inexistente; eso confirma que reproduce el defecto. Si la prueba no puede renderizar la vista por infraestructura, el programador debe ajustar el arranque del test (por ejemplo, cargar `helper('url')` o usar `Services::renderer()`), no relajar las aserciones.

## Riesgos y efectos secundarios

- **Vista compartida:** `_formas_pago` solo se invoca desde `app/Views/inscripciones/nuevo_ingreso/paso3/formas_pago.php`. El flujo regular usa `elegir_tp_forma_pago.php`, que no se toca. Aun así, cualquier consumidor futuro heredará la nueva resolución y el respaldo visual.
- **Comprobación en disco:** `is_file(FCPATH . $ruta)` depende de que los archivos estén desplegados en `public/assets/bancos`. Si en producción faltan archivos, se verá el icono de respaldo en lugar de una imagen rota, que es el comportamiento acordado.
- **URLs remotas:** no se puede validar su existencia en el servidor. El `onerror` cubre el fallo en el navegador, pero requiere JavaScript habilitado.
- **Carpetas duplicadas:** `public/imagenes/bancos` sigue existiendo. Si un registro apunta allí y el archivo existe, se respeta; no se unifican carpetas en este bugfix.
- **Caso en el nombre del archivo:** en sistemas Linux el nombre es sensible a mayúsculas. Los valores sembrados están en minúsculas y coinciden con los archivos; si un registro nuevo usa otra capitalización, caerá al icono de respaldo.
- **Rendimiento:** `is_file` se ejecuta una vez por forma visible; el catálogo es pequeño y no representa un costo relevante.
- **Sin impacto funcional:** no se tocan montos, intenciones, estados, rutas, filtros ni pasarelas.
- **Numeración:** se verificó que `001` a `005` ya existen en `docs/bugfix/`; este plan usa `006` sin colisión.

## Criterios de finalización

- [ ] Los logos de ambas familias (`po` y `rp`) se cargan desde `public/assets/bancos/{archivo}` y responden 200.
- [ ] No queda ninguna petición de logo apuntando a la raíz pública (`.../public/banesco.png`).
- [ ] Los logos se ven correctamente en tema claro y oscuro.
- [ ] Un logo vacío, inexistente o con URL remota fallida muestra el icono `account_balance` en lugar de una imagen rota.
- [ ] Las rutas relativas ya configuradas y las URLs absolutas se respetan sin duplicar segmentos.
- [ ] El enlace de cada tarjeta y el flujo de pago no cambian.
- [ ] `FormasPagoLogoTest` pasa y las suites `Paso4PagoTest`, `Paso4NuevoIngresoTest`, `FormasPagoModelTest` y `NuevoIngresoPagoServiceTest` siguen en verde.
- [ ] No se modificaron modelos, servicios, controladores, rutas, filtros, seeders, migraciones ni CSS generado.
- [ ] El flujo legacy de pagos regulares conserva su comportamiento.

## Notas del programador

- Este plan no implementa la corrección; define alcance, causa y verificación. La prueba PHPUnit se deja propuesta para crearla junto con la corrección y no dejar la suite en rojo antes de tiempo.
- Se consultó `graphify-out/graph.json` con `graphify query "formas de pago nuevo ingreso imagenes bancos"` para ubicar `NuevoIngresoPagoService`, `FormasPagoModel`, `Paso3` y los parciales de pago.
- Evidencia principal: la URL reportada por el usuario (`.../public/banesco.png`), el flujo legacy que sí usa `/assets/bancos/` y los archivos reales en `public/assets/bancos/`.
- No se ejecuta `graphify update .` porque esta fase solo agrega documentación.
- `MEMORY.md` no existe en este checkout, aunque `AGENTS.md` lo referencia; no se actualiza en este plan.
- Rama actual: `feature/desacoplar-contructor-pagos`.
- Siguiente paso sugerido: implementar la resolución en `app/Views/pagos/partials/_formas_pago.php`, agregar `tests/app/Integration/FormasPagoLogoTest.php`, ejecutar las suites indicadas y validar manualmente ambas familias en local.
