# Prototipo de ejecución — FEAT-012 Permiso administrativo `inscripciones_ni` exclusivo del perfil Auditor NI

- **Rama:** p-feature/permiso-administrativo-inscripciones-ni
- **Rama base:** feature/panel-administrativo-documentos-ni
- **Plan:** docs/features/012-permiso-administrativo-inscripciones-ni/plan.md
- **Fecha:** 2026-10-30
- **Estado:** consolidado
- **Consolidado en:** feature/panel-administrativo-documentos-ni
- **Fecha de consolidación:** 2026-10-30
- **Estrategia de integración:** merge --no-ff
- **Rama prototipo eliminada:** sí

## Resumen

Se implementó el permiso administrativo `inscripciones_ni` en la base principal y se asignó únicamente al perfil `Auditor NI`, creando o reactivando ambos registros por sus claves naturales. La migración `000105` deduplica datos previos y garantiza índices únicos, mientras los seeders quedan idempotentes y protegidos por una transacción en la asignación de accesos.

## Tareas realizadas

- [x] Crear migración idempotente `AddUniqueIndexesToAcAccesos` con deduplicación de `ac_accesos` y `ac_perfiles_accesos` e índices únicos.
- [x] Registrar la migración `2026-10-30-000105` en `InitPrincipalDb::runPrincipalMigrations()`.
- [x] Refactorizar `AcPerfilesSeeder` para resolver, crear y reactivar `Auditor NI` por descripción exacta, sin id fijo.
- [x] Refactorizar `AcAccesosSeeder` para hacer upsert por `codigo_acceso` e incorporar `inscripciones_ni`.
- [x] Refactorizar `AcPerfilesAccesosSeeder` para resolver IDs por clave natural, asignar solo `Auditor NI`, conservar `zelle` en Administrador y revocar físicamente a otros perfiles dentro de una transacción.
- [x] Crear pruebas de migración, de los tres seeders y del filtro `AdminPanel`.
- [x] Ejecutar las pruebas del área y registrar los resultados.
- [x] Actualizar el estado del plan y crear este `prototipo.md`.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| La migración `000105` existe, está registrada en `init:principal` y pasa su prueba de ejecución doble sin cambios adicionales. | `AcAccesosUniqueIndexesMigrationTest::testEsIdempotente` y revisión de `InitPrincipalDb`. | ok |
| La migración omite su trabajo sin error cuando `ac_accesos` o `ac_perfiles_accesos` no existen. | `testOmiteSuTrabajoSiFaltanLasTablas`. | ok |
| Con duplicados previos en `ac_accesos`, sobrevive el menor `id`, las asignaciones se repuntan y los duplicados se eliminan. | `testDeduplicaAccesosYRepuntaAsignaciones`. | ok |
| Con duplicados previos en `ac_perfiles_accesos`, sobrevive el menor `id` de cada par. | `testDeduplicaParesPerfilAccesoConservandoElMenorId`. | ok |
| Los índices únicos existen y rechazan inserciones duplicadas. | `testCreaLosIndicesUnicosConLosNombresEsperados` y `testRechazaInsercionesDuplicadasDespuesDeMigrar`. | ok |
| `AcPerfilesSeeder` ejecutado dos veces deja un solo `Auditor NI` y conserva Administrador y Profesor. | `AcPerfilesSeederTest::testEsIdempotenteYNoDuplicaElAuditorNi` y `testCreaAdministradorProfesorYAuditorNi`. | ok |
| `AcPerfilesSeeder` reactiva un `Auditor NI` borrado lógicamente. | `testReactivaUnAuditorNiBorradoLogicamente`. | ok |
| `AcAccesosSeeder` ejecutado dos veces deja un solo `zelle` y un solo `inscripciones_ni`, incluso con ids distintos de 1. | `AcAccesosSeederTest::testCreaZelleEInscripcionesNiUnaSolaVez` y `testRespetaElIdExistenteYNoAsumeElIdUno`. | ok |
| `AcPerfilesAccesosSeeder` deja una sola asignación activa de `inscripciones_ni`, solo para `Auditor NI`. | `AcPerfilesAccesosSeederTest::testDejaUnaSolaAsignacionActivaDeCadaAcceso` y `testResuelveLosIdsRealesPorClaveNatural`. | ok |
| No quedan asignaciones de `inscripciones_ni` para Administrador, Profesor ni otros perfiles. | La prueba deja una sola fila para el acceso y verifica que pertenece a `Auditor NI`. | ok |
| Queda exactamente una asignación activa de `zelle` para Administrador y ninguna para otros perfiles. | La prueba cuenta una sola fila para `zelle` y verifica el perfil Administrador. | ok |
| Si falta `Auditor NI`, el seeder de asignaciones lanza un error claro y no deja asignaciones parciales. | `testFallaSinPerfilAuditorNiYSinAsignacionesParciales`. | ok |
| El filtro permite a un usuario `Auditor NI` con asignación activa acceder al módulo `inscripciones_ni`. | `AdminPanelTest::testPermiteAuditorNiConAsignacionActiva`. | ok |
| El filtro deniega a Profesor y Administrador sin asignación. | `testDeniegaAProfesorSinAsignacion` y `testDeniegaAAdministradorSinAsignacion`. | ok |
| Una asignación inactiva o borrada lógicamente también es denegada. | `testDeniegaUnaAsignacionInactiva` y `testDeniegaUnaAsignacionBorradaLogicamente`. | ok |
| Un módulo inexistente o borrado es denegado. | `testDeniegaUnModuloInexistente` y `testDeniegaUnModuloBorradoLogicamente`. | ok |
| Se ejecutan las pruebas del área y pasan. | Suites de `tests/app/Database/Seeds`, `tests/app/Database/Migrations` y `tests/app/Filters`. | ok |
| No se modificaron rutas, controladores, vistas, la SPA ni dependencias. | Revisión de `git status` y `git diff --stat`. | ok |
| Se actualiza `MEMORY.md` si la implementación cambia el estado o decisiones documentadas. | `MEMORY.md` no existe en este repositorio; se actualizó el estado y la bitácora del plan. | ok, con nota |

## Flujos cubiertos

- **Flujo normal:** creación de la migración, carga de perfiles y accesos, asignación exclusiva a `Auditor NI` y permiso del filtro con asignación activa.
- **Flujos alternativos:** primera instalación sin datos, re-ejecución de seeders, perfil o acceso borrado lógicamente, IDs existentes distintos de los históricos, asignación inactiva o borrada y datos duplicados previos.
- **Control de errores:** tablas ausentes, duplicados previos, índices ya existentes o no únicos, inserción duplicada posterior a la migración, perfil `Auditor NI` ausente, código de acceso ausente, sesión administrativa ausente, usuario borrado, módulo inexistente o borrado y perfil sin asignación activa.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| app/Database/Migrations/2026-10-30-000105_AddUniqueIndexesToAcAccesos.php | Deduplicar accesos y asignaciones y crear los índices únicos. |
| tests/app/Database/Migrations/AcAccesosUniqueIndexesMigrationTest.php | Probar deduplicación, índices, idempotencia y omisión segura. |
| tests/app/Database/Seeds/AcPerfilesSeederTest.php | Probar creación, re-ejecución y reactivación de `Auditor NI`. |
| tests/app/Database/Seeds/AcAccesosSeederTest.php | Probar upsert por `codigo_acceso` y re-ejecución. |
| tests/app/Database/Seeds/AcPerfilesAccesosSeederTest.php | Probar asignación exclusiva, revocación, IDs naturales y errores. |
| tests/app/Filters/AdminPanelTest.php | Probar permiso y denegación del filtro sin modificarlo. |
| docs/features/012-permiso-administrativo-inscripciones-ni/prototipo.md | Registrar la ejecución de la feature. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| app/Commands/InitPrincipalDb.php | Se registró la migración `2026-10-30-000105`. |
| app/Database/Seeds/AcPerfilesSeeder.php | Upsert por id histórico para Administrador y Profesor; alta/reactivación de `Auditor NI` por descripción. |
| app/Database/Seeds/AcAccesosSeeder.php | Upsert por `codigo_acceso`, reactivación lógica y nuevo acceso `inscripciones_ni`. |
| app/Database/Seeds/AcPerfilesAccesosSeeder.php | Resolución por clave natural, asignación exclusiva, revocación física y transacción. |
| docs/features/012-permiso-administrativo-inscripciones-ni/plan.md | Estado cambiado a `completado` y bitácora actualizada. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** no aplica. No se crearon rutas ni controladores; el permiso queda listo para ser usado por `adminPanel:module=inscripciones_ni` en un cambio posterior.
- **Permisos y validaciones:** el acceso `inscripciones_ni` se identifica por `codigo_acceso`; el perfil autorizado se identifica por `descripcion = 'Auditor NI'`; solo ese perfil conserva una asignación activa. La revocación se limita al `accesos_id` correspondiente.
- **Migraciones/seeds:** `2026-10-30-000105_AddUniqueIndexesToAcAccesos.php` es idempotente y se omite si faltan las tablas. Los tres seeders son idempotentes en ejecución secuencial; su doble ejecución se verificó con pruebas SQLite en memoria.
- **Compatibilidad:** no se modificaron contratos HTTP, controladores, vistas, SPA ni dependencias. Se conserva la asignación de `zelle` al perfil Administrador. El índice no único histórico sobre `ac_accesos.codigo_acceso` se conserva.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `vendor\bin\phpunit.bat tests/app/Database/Seeds` (línea base) | Éxito: 35 pruebas, 101 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Database/Migrations` (línea base) | Éxito: 28 pruebas, 72 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Database/Seeds` (después) | Éxito: 47 pruebas, 142 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Database/Migrations` (después) | Éxito: 36 pruebas, 95 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Database/Migrations/AcAccesosUniqueIndexesMigrationTest.php` | Éxito: 8 pruebas, 23 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Filters/AdminPanelTest.php` | Éxito: 9 pruebas, 23 aserciones. |
| `vendor\bin\phpunit.bat tests/app/Database/Seeds tests/app/Database/Migrations/AcAccesosUniqueIndexesMigrationTest.php tests/app/Filters/AdminPanelTest.php` | PHPUnit 8.5 ejecutó solo un archivo (8 pruebas, 23 aserciones). Por eso se ejecutó cada suite por separado, con los resultados anteriores. |
| `php -l` sobre los archivos PHP creados y modificados | Sin errores de sintaxis. |

## Verificación

- **Línea base (antes):** `tests/app/Database/Seeds` con 35 pruebas y 101 aserciones; `tests/app/Database/Migrations` con 28 pruebas y 72 aserciones. Ambas suites pasaron.
- **Prueba manual (flujo normal):** no se ejecutó `php spark init:principal` ni seeders contra MySQL real para no tocar la base principal. El flujo se verificó con pruebas automatizadas sobre SQLite en memoria y conexiones aisladas.
- **Flujos alternativos y errores:** cubiertos en las pruebas de migración, seeders y filtro descritas en los criterios de aceptación.
- **Pruebas automatizadas:** `tests/app/Database/Seeds` (47/47), `tests/app/Database/Migrations` (36/36) y `tests/app/Filters/AdminPanelTest.php` (9/9).
- **Criterios del plan:** todos los criterios verificables quedaron cumplidos; el criterio de `MEMORY.md` se resolvió actualizando el plan porque el archivo no existe en el repositorio.

## Desviaciones del plan

- No se ejecutó `init:principal` contra una base MySQL real. Se priorizó no tocar datos reales; la idempotencia se comprobó con pruebas sobre SQLite en memoria.
- El comando combinado de PHPUnit indicado en el plan no ejecuta las tres rutas en PHPUnit 8.5; se ejecutaron las suites por separado.
- `MEMORY.md` no existe en el repositorio; el estado se registró en `plan.md` y en este prototipo.

## Consolidación

- **Fecha:** 2026-10-30
- **Rama destino:** feature/panel-administrativo-documentos-ni
- **Estrategia:** merge --no-ff
- **Commits integrados:** `bfa39d1` (feat) y `f528feb` (docs)
- **Verificación:** rama prototipo contenida en la destino, sin commits pendientes y sin diferencias de archivos; suites de pruebas del área en verde.
- **Rama prototipo eliminada:** sí, con `git branch -d`.

## Riesgos y pendientes

- La rama MySQLi de la migración (`ALTER TABLE ... DROP INDEX`, `SHOW INDEX`) no se ejecutó contra MySQL; conviene probarla en staging antes de desplegar.
- Si existen varios perfiles con descripción exacta `Auditor NI`, se usa el de menor `id` y los demás no se eliminan para no romper referencias de usuarios. Queda como riesgo de datos.
- La ruta real con `adminPanel:module=inscripciones_ni` aún no existe; su creación corresponde a un slice posterior.
- El plan de slices `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md` sigue mencionando al perfil Administrador para este acceso; debe corregirse en un cambio de documentación aparte.
- No se hizo commit ni push; la rama `p-feature/permiso-administrativo-inscripciones-ni` permanece local.
