# Agregar los campos del aspirante a la planilla de inscripción de nuevo ingreso

- **Código:** EDT-001
- **Tipo:** edit
- **Estado:** en curso
- **Fecha:** 2026-11-03
- **Autor:** opencode (agente)

## Objetivo

Ampliar la planilla PDF de inscripción de nuevo ingreso (Paso 4) para que muestre todos los datos del aspirante guardados en `ni_inscripciones` que hoy no aparecen, excluyendo identificadores y metadatos técnicos. La presentación debe seguir el orden y las etiquetas del formulario de datos básicos (Paso 0), con el formato `dd/mm/aaaa` y `HH:MM`.

## Motivación

La planilla actual solo imprime datos básicos de contacto, carrera, sede, turno y modalidad. El formulario de Paso 0 ya captura y persiste información del representante, salud, antecedentes académicos y datos laborales, pero esa información no se refleja en el PDF. Se busca que la planilla sea un documento completo de inscripción sin agregar captura ni cambiar el modelo de datos.

## Estado actual

- La vista `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` imprime:
  - **Información personal:** apellidos, nombres, cédula, correo, teléfono, país, estado/provincia, ciudad y dirección.
  - **Información académica:** carrera, sede, turno y modalidad.
  - Bloque de firmas.
- El servicio `NuevoIngresoPlanillaService::datosPlanilla()` solo construye esas claves.
- `ni_inscripciones` ya guarda, entre otros: `fecha_nacimiento`, `sexo`, `rep_nombres`, `rep_apellidos`, `rep_parentesco`, `rep_telefono`, `rep_pais_provincia_id`, `rep_ciudad`, `rep_direccion`, `discapacidad`, `alergia`, `plantel_egreso`, `plantel_ano_egreso`, `plantel_tipo`, `plantel_mencion`, `trabajo_empresa`, `trabajo_hora_entrada` y `trabajo_hora_salida`.
- El formulario de Paso 0 agrupa esos datos en cinco secciones: Información personal, Información del representante, Información de salud, Información académica e Información laboral.

## Cambios propuestos

| # | Archivo / ubicación | Antes | Después | Motivo |
| --- | --- | --- | --- | --- |
| 1 | `NuevoIngresoPlanillaService::datosPlanilla()` | No devuelve fecha de nacimiento ni sexo. | Devuelve `fecha_nacimiento` formateada como `dd/mm/aaaa` y `sexo` traducido a `Masculino` o `Femenino`. Si el dato falta o es inválido: `No disponible`. | Mostrar los datos personales capturados en Paso 0. |
| 2 | `NuevoIngresoPlanillaService::datosPlanilla()` | No devuelve datos del representante. | Devuelve `tiene_representante` (booleano), `rep_nombres`, `rep_apellidos`, `rep_parentesco` traducido, `rep_telefono`, `rep_pais`, `rep_provincia`, `rep_ciudad` y `rep_direccion`. `rep_pais` y `rep_provincia` se resuelven desde `rep_pais_provincia_id` con `gb_paises_provincias` y `gb_paises`. | Reflejar la sección del representante solo cuando exista información. |
| 3 | `NuevoIngresoPlanillaService::datosPlanilla()` | No devuelve discapacidad ni alergia. | Devuelve `discapacidad` y `alergia` como `Sí: {texto}` cuando hay valor, o `No` cuando el campo está vacío. | Mostrar el detalle solo cuando el aspirante declaró que sí. |
| 4 | `NuevoIngresoPlanillaService::datosPlanilla()` | No devuelve antecedentes académicos del plantel. | Devuelve `plantel_egreso`, `plantel_ano_egreso`, `plantel_tipo` traducido (`Público`, `Privado`, `Parasistema`) y `plantel_mencion` traducido (`Ciencias`, `Humanidades`, `Integral`, `Contable`, `Industrial`). | Completar la sección académica conservando carrera, sede, turno y modalidad. |
| 5 | `NuevoIngresoPlanillaService::datosPlanilla()` | No devuelve información laboral. | Devuelve `trabaja` (`Sí` si hay empresa u horario; `No` en caso contrario), `trabajo_empresa`, `trabajo_hora_entrada` y `trabajo_hora_salida` normalizadas a `HH:MM`. | Reflejar la sección laboral del formulario. |
| 6 | `NuevoIngresoPlanillaService` (métodos privados) | Solo existen `identificacion()` y `modalidad()` como traductores. | Agregar métodos privados para fecha, hora, sexo, parentesco, tipo de plantel, mención, presencia del representante y condición laboral. | Mantener la traducción y el saneamiento fuera de la vista. |
| 7 | `app/Views/.../paso3/planilla.php` - Información personal | Filas: Apellidos/Nombres; Cédula/Correo; Teléfono/País/Provincia; Ciudad/Dirección. | Agregar una fila con `Fecha de Nacimiento` y `Sexo` después de Apellidos/Nombres, manteniendo las filas existentes. | Seguir el orden del formulario de datos básicos. |
| 8 | `app/Views/.../paso3/planilla.php` - Representante | No existe la sección. | Agregar `INFORMACIÓN DEL REPRESENTANTE` entre Información personal e Información de salud, visible solo si `tiene_representante` es verdadero. Mostrar Nombres, Apellidos, Parentesco, Teléfono Móvil, País, Estado / Provincia, Ciudad y Dirección de Habitación. | Reflejar la sección condicional del formulario. |
| 9 | `app/Views/.../paso3/planilla.php` - Salud | No existe la sección. | Agregar `INFORMACIÓN DE SALUD` con `Discapacidad` y `Es alérgico a algún Medicamento`, mostrando el valor calculado por el servicio. | Reflejar la sección de salud del formulario. |
| 10 | `app/Views/.../paso3/planilla.php` - Información académica | Solo Carrera/Sede y Turno/Modalidad. | Conservar esas filas y agregar `Nombre del Plantel donde Egresó`, `Año de Egreso`, `Plantel` y `Mención`. | Unificar la oferta académica y los antecedentes del plantel en una sola sección. |
| 11 | `app/Views/.../paso3/planilla.php` - Laboral | No existe la sección. | Agregar `INFORMACIÓN LABORAL` con `¿Trabajas?`. Si `trabaja` es `Sí`, mostrar Empresa, Hora de Entrada y Hora de Salida; si es `No`, mostrar solo `No`. | Reflejar la sección laboral del formulario. |
| 12 | `tests/app/Libraries/.../NuevoIngresoPlanillaServiceTest.php` - esquema SQLite | `ni_inscripciones` de prueba no tiene columnas nuevas. | Agregar las columnas de fecha de nacimiento, sexo, representante, salud, plantel y trabajo. | Permitir que el servicio lea los campos nuevos en las pruebas. |
| 13 | `tests/app/Libraries/.../NuevoIngresoPlanillaServiceTest.php` - datos de prueba | La postulación sembrada solo tiene datos básicos. | Agregar valores de ejemplo para todos los campos nuevos, incluida una segunda provincia para el representante. | Verificar la traducción, el formato y la sección condicional. |
| 14 | `tests/app/Libraries/.../NuevoIngresoPlanillaServiceTest.php` - aserciones | Solo se comprueban los datos actuales. | Agregar aserciones de los valores y etiquetas nuevos, la ausencia de la sección del representante cuando no hay datos y los casos `No` de salud y trabajo. | Demostrar que la edición quedó bien y evitar regresiones. |

### Detalle de traducciones

| Campo | Valor guardado | Texto en la planilla |
| --- | --- | --- |
| `sexo` | `0` / `1` | `Masculino` / `Femenino` |
| `rep_parentesco` | `0` a `6` | `Padre / Madre`, `Tío / Tía`, `Hermano / Hermana`, `Abuelo / Abuela`, `Primo / Prima`, `Tutor Legal`, `Otro` |
| `plantel_tipo` | `0` / `1` / `2` | `Público` / `Privado` / `Parasistema` |
| `plantel_mencion` | `0` a `4` | `Ciencias`, `Humanidades`, `Integral`, `Contable`, `Industrial` |
| `discapacidad` | vacío / texto | `No` / `Sí: {texto}` |
| `alergia` | vacío / texto | `No` / `Sí: {texto}` |
| `trabaja` | sin empresa ni horario / con algún dato | `No` / `Sí` |

### Campos que no se mostrarán

- Identificadores y claves: `id`, `sucursal_carrera_id`, `turno_id`, `pais_provincia_id`, `rep_pais_provincia_id`, `pais_provincia_liceo_id`, `ghl_contact_id`.
- Metadatos técnicos: `paso_actual`, `ghl_sincronizado`, `orbis_sincronizado`, `created_at`, `updated_at`, `correo_aprobacion`.
- Códigos ya traducidos en otros campos: `identificacion_tipo` y `modalidad` se siguen mostrando como parte de la cédula y de la modalidad, no como números.

## Alcance

- Incluye:
  - Agregar al servicio de la planilla de nuevo ingreso los campos faltantes de `ni_inscripciones`, con traducción de códigos y formato de fecha/hora.
  - Reorganizar la vista PDF en cinco secciones siguiendo el formulario de datos básicos: personal, representante, salud, académica y laboral.
  - Mostrar la sección del representante solo cuando exista al menos un dato `rep_*`.
  - Mantener el comportamiento de `No disponible` para datos obligatorios ausentes.
  - Permitir que el PDF ocupe más de una página sin forzar una sola página.
  - Actualizar las pruebas unitarias del servicio para cubrir los campos nuevos.
- No incluye:
  - Agregar campos al formulario de Paso 0 ni modificar su captura.
  - Crear migraciones, columnas o seeds nuevos.
  - Cambiar `NiInscripcionModel`, rutas, controladores, filtros, permisos, pagos, recibos, correos o la SPA.
  - Modificar la planilla regular de pre-inscripción (`app/Views/imprimir/planilla.php` ni `Imprimir::planilla()`).
  - Cambiar el diseño del recibo, el mensaje de éxito o el panel administrativo.
  - Almacenar el PDF o auditar descargas.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaService.php` | Construir las claves nuevas, resolver país/provincia del representante y traducir códigos. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php` | Agregar las secciones y filas nuevas, condicionar representante y salud/trabajo. |
| Modificar | `tests/app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaServiceTest.php` | Ampliar el esquema SQLite, los datos de prueba y las aserciones. |
| Revisar | `tests/app/Integration/Paso4PlanillaTest.php` | No requiere cambios esperados porque usa las claves con valores por defecto, pero debe ejecutarse para confirmar que no hay regresión. |

No se crean archivos nuevos de producción.

## Verificación

### Prueba manual (flujo normal)

1. Disponer de una postulación de nuevo ingreso con `paso_actual = 4`, pago en estado aprobado o verificado, y datos completos en `ni_inscripciones` (incluido representante, salud, plantel y trabajo).
2. Iniciar sesión en el portal con la sesión de nuevo ingreso correspondiente.
3. Abrir `/inscripciones/nuevo-ingreso/paso-4` y pulsar **Descargar planilla de inscripción**.
4. Resultado esperado:
   - Se descarga `PlanillaNI{id}.pdf`.
   - Aparecen las secciones **Información personal**, **Información del representante**, **Información de salud**, **Información académica** e **Información laboral**, en ese orden.
   - La fecha de nacimiento se ve como `dd/mm/aaaa`; los horarios como `HH:MM`.
   - El sexo, parentesco, tipo de plantel y mención se ven como texto, no como números.
   - El país y estado/provincia del representante se ven como nombres.
   - Discapacidad y alergia muestran `Sí: {texto}` cuando hay valor y `No` cuando no lo hay, sin línea de detalle.
   - Si el aspirante no trabaja, se muestra `¿Trabajas?: No` sin empresa ni horarios.
   - Se conservan Carrera, Sede, Turno y Modalidad.
   - No aparecen IDs ni banderas de sincronización.
   - El contenido puede ocupar más de una página.
5. Repetir con una postulación de mayor de edad sin datos de representante: la sección **Información del representante** no debe aparecer.
6. Repetir con textos especiales (`<`, `>`, `&`) en nombres o direcciones: deben verse escapados, no ejecutarse.

### Lint / build / prueba automatizada

```powershell
php -l app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaService.php
php -l app/Views/inscripciones/nuevo_ingreso/paso3/planilla.php
vendor\bin\phpunit.bat tests/app/Libraries/Inscripciones/NuevoIngreso/Planilla/NuevoIngresoPlanillaServiceTest.php
vendor\bin\phpunit.bat tests/app/Integration/Paso4PlanillaTest.php
```

- `php -l` valida la sintaxis de los archivos modificados.
- La primera prueba valida las claves nuevas, las traducciones, los formatos y la sección condicional del representante.
- La segunda prueba de integración valida que la descarga de la planilla y sus reglas de acceso sigan funcionando.
- No se ejecuta la suite completa porque `tests/app/Models/BotChatSystemTest.php` tiene un fallo preexistente documentado en `AGENTS.md`.

## Riesgos y efectos secundarios

- **Datos sensibles en el PDF:** la planilla ahora incluirá salud, representante y datos laborales. El acceso sigue restringido a la intención propia y aprobada; no se agregan rutas ni permisos nuevos.
- **Extensión del PDF:** con todos los campos es probable que ocupe dos páginas. El usuario aceptó permitir varias páginas.
- **Registros antiguos incompletos:** las postulaciones previas pueden no tener datos de representante, salud o trabajo. La sección del representante se omite si no hay datos; los campos obligatorios ausentes muestran `No disponible`; salud y trabajo muestran `No` cuando están vacíos.
- **Catálogo del representante:** si `rep_pais_provincia_id` apunta a un registro inactivo o inexistente, se mostrará `No disponible` y se registrará una advertencia, sin romper la generación.
- **Formato de horas:** si el valor guardado trae segundos, se recorta a `HH:MM`; si no cumple el formato esperado, se muestra `No disponible`.
- **Pruebas SQLite:** el esquema de prueba debe declarar las columnas nuevas para que `NiInscripcionModel::find()` las devuelva. Las pruebas de integración que no las declaren no deben fallar porque el servicio usa valores por defecto, pero se ejecutan para confirmarlo.

## Criterios de finalización

- [ ] Todos los campos listados en «Cambios propuestos» se muestran en la planilla de nuevo ingreso.
- [ ] La sección del representante solo aparece cuando existe al menos un dato `rep_*`.
- [ ] Discapacidad, alergia y trabajo muestran `No` sin detalle cuando corresponden.
- [ ] Fecha y horas respetan `dd/mm/aaaa` y `HH:MM`.
- [ ] Se conservan Carrera, Sede, Turno y Modalidad.
- [ ] No se muestran IDs ni metadatos técnicos.
- [ ] La verificación manual muestra el resultado esperado en una postulación completa y en una sin representante.
- [ ] `php -l` y las pruebas indicadas pasan sin errores nuevos.
- [ ] No se modificó nada fuera del alcance (sin migraciones, rutas, controladores, pagos ni planilla regular).

## Notas del programador

- La petición se limita a la planilla de nuevo ingreso; la planilla regular de pre-inscripción queda intacta.
- Los datos ya se capturan y persisten en `ni_inscripciones`; no se requiere migración ni cambio en `Paso0`.
- La vista debe seguir el orden del formulario de Paso 0, pero conservando las filas actuales de Carrera, Sede, Turno y Modalidad dentro de la sección académica.
- Se recomienda implementar primero el servicio (claves y traducciones) y luego la vista, para que las pruebas del servicio validen los datos antes de ajustar el PDF.
- Si más adelante se desean estos campos en la planilla regular, debe tratarse como una edición separada porque usa otras tablas (`personales`, `representantes`, `academica`, `laboral`).
