# Permiso administrativo `inscripciones_ni` exclusivo del perfil Auditor NI

- **Código:** FEAT-012
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-30
- **Autor:** opencode (agente)

## Objetivo

Que exista el permiso administrativo `inscripciones_ni` en `ac_accesos` y que quede asignado únicamente al perfil `Auditor NI`, creándolo o reactivándolo si hace falta. La carga debe ser idempotente y sin duplicados, de modo que el filtro `AdminPanel` pueda usarlo cuando se expongan las rutas del panel administrativo en un cambio posterior.

## Alcance

- **Incluye:**
  - Crear una migración idempotente para garantizar unicidad en `ac_accesos.codigo_acceso` y en `ac_perfiles_accesos (perfiles_id, accesos_id)`.
  - Deduplicar datos existentes antes de crear los índices: conservar el menor `id`, repuntar las asignaciones y eliminar los duplicados.
  - Registrar la migración en el flujo `init:principal`.
  - Refactorizar `AcAccesosSeeder` para hacer upsert por `codigo_acceso`, nunca por `id` fijo, e incorporar el acceso `inscripciones_ni`.
  - Refactorizar `AcPerfilesSeeder` para resolver el perfil `Auditor NI` por descripción exacta, crearlo si no existe y reactivarlo si está borrado lógicamente.
  - Refactorizar `AcPerfilesAccesosSeeder` para resolver accesos y perfiles por sus claves naturales, asignar `inscripciones_ni` solo a `Auditor NI` y revocar físicamente las asignaciones de cualquier otro perfil para ese acceso.
  - Conservar sin cambios funcionales la asignación actual del módulo `zelle` al perfil Administrador.
  - Cubrir con pruebas automatizadas los seeders, la migración y la denegación/permiso del filtro `AdminPanel`.

- **No incluye:**
  - Crear rutas, controladores, vistas, menú o pantallas administrativas.
  - Implementar el listado, el detalle o la visualización de recaudos del panel de inscripciones de nuevo ingreso. Eso corresponde a los slices 5 a 9 del plan `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`.
  - Crear usuarios en `ac_usuarios` para el perfil `Auditor NI` ni reasignar usuarios existentes.
  - Modificar la lógica del filtro `AdminPanel`; solo se prueba su comportamiento actual.
  - Cambiar las asignaciones de otros accesos distintos de `zelle` e `inscripciones_ni`.
  - Agregar unicidad sobre `ac_perfiles.descripcion`.
  - Modificar tablas de sucursal, pagos, postulaciones, Orbis o GHL.
  - Actualizar el plan de slices; la discrepancia sobre el perfil autorizado se registra en supuestos y se recomienda corregirla en un cambio de documentación aparte.

> **Evaluación de alcance:** es una sola capacidad de negocio y seguridad: registrar un permiso y dejar una única asignación activa para el perfil autorizado. La migración, los tres seeders y las pruebas no aportan valor por separado; por eso no se divide. El panel administrativo completo ya está dividido en slices independientes y queda fuera de este cambio.

## Contexto y supuestos

- La rama de trabajo detectada es `feature/panel-administrativo-documentos-ni`.
- Existe un plan de slices sin commitear en `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`. Su Slice 1 propone asignar `inscripciones_ni` al perfil Administrador. La respuesta explícita del usuario para este cambio es asignarlo **solo a `Auditor NI`**; esa decisión prevalece. Se recomienda actualizar el plan de slices en un cambio de documentación separado.
- La petición dice "ejecutar ambos seeders dos veces". Para que la verificación sea inequívoca, se consideran los tres seeders involucrados y su orden obligatorio: `AcPerfilesSeeder`, `AcAccesosSeeder` y `AcPerfilesAccesosSeeder`. También es válido ejecutar `php spark init:principal` dos veces, porque ya los invoca en ese orden.
- Hoy ninguna ruta usa `adminPanel:module=inscripciones_ni`. La denegación real de una ruta se podrá comprobar cuando exista el Slice 5; en este cambio se verifica a nivel del filtro `AdminPanel`.
- `AdminPanel` consulta siempre la conexión `default`. La prueba del filtro debe configurar o inyectar esa conexión hacia la base de pruebas SQLite en memoria y restaurarla en `tearDown`, sin tocar datos reales.
- Las tablas `ac_*` viven en la base principal (`default`), no en las bases de sucursal.
- La descripción propuesta para el nuevo acceso es `Consulta de inscripciones de nuevo ingreso`. Es un dato de presentación asumido y puede ajustarse sin cambiar el código del permiso.
- El perfil se identifica por la descripción exacta `Auditor NI`, respetando mayúsculas y espacio. No se asigna un `id` fijo.
- Si existen varios perfiles con la descripción `Auditor NI`, se usa el de menor `id` y no se eliminan los demás, porque podrían estar referenciados por usuarios. Esta situación queda registrada como riesgo de datos.
- El índice existente no único sobre `ac_accesos.codigo_acceso` se conserva. La migración agrega un índice único con nombre distinto; no es necesario eliminar el anterior.
- En MySQL el DDL no es transaccional. La migración debe ser idempotente y ordenada, no prometer atomicidad total.
- El código documental del proyecto usa el esquema `FEAT-NNN`; por eso este cambio es `FEAT-012` y no `feature-AAAAMMDD-NNN`.
- El siguiente número de migración libre es `000105`. El repositorio contiene números repetidos `000095` y `000096`, pero ninguno llega a `000105`.

## Flujo normal

1. Paso 1: Ejecutar la migración `2026-10-30-000105_AddUniqueIndexesToAcAccesos.php`. Si las tablas existen, deduplica `ac_accesos` por `codigo_acceso` y `ac_perfiles_accesos` por `(perfiles_id, accesos_id)`, conservando el menor `id` y repuntando las asignaciones al acceso superviviente.
2. Paso 2: La migración crea el índice único `uniq_ac_accesos_codigo_acceso` y el índice único `uniq_ac_perfiles_accesos_perfil_acceso` si no existen o si existen pero no son únicos.
3. Paso 3: Ejecutar `AcPerfilesSeeder`. Busca un perfil con `descripcion = 'Auditor NI'`. Si existe, lo reutiliza, limpia `borrado_dt` y actualiza `actualizado_dt`. Si no existe, lo inserta sin `id` fijo. Los perfiles Administrador y Profesor conservan su comportamiento actual.
4. Paso 4: Ejecutar `AcAccesosSeeder`. Para cada registro (`zelle` e `inscripciones_ni`), busca por `codigo_acceso`. Si existe, actualiza la descripción, limpia `borrado_dt` y actualiza `actualizado_dt`. Si no existe, lo inserta sin `id` fijo.
5. Paso 5: Ejecutar `AcPerfilesAccesosSeeder`. Resuelve el `id` de `zelle` y de `inscripciones_ni` por `codigo_acceso`, y el `id` de `Auditor NI` por descripción exacta.
6. Paso 6: El seeder mantiene la asignación de `zelle` al perfil Administrador (`id = 1`) y elimina las asignaciones de `zelle` de cualquier otro perfil, igual que hoy.
7. Paso 7: El seeder crea o reactiva una única asignación de `inscripciones_ni` para `Auditor NI`, con `activo = '1'`, `aplica_en = null` y `borrado_dt = null`.
8. Paso 8: El seeder elimina físicamente cualquier asignación de `inscripciones_ni` cuyo `perfiles_id` no sea el de `Auditor NI`. No toca asignaciones de otros accesos.
9. Paso 9: Cuando exista una ruta con `adminPanel:module=inscripciones_ni`, el filtro resuelve el acceso por código y consulta la asignación del perfil del usuario. Con la asignación activa de `Auditor NI` permite el paso; con cualquier otro perfil, asignación inactiva, borrada o inexistente, redirige al login con el mensaje correspondiente.

## Flujos alternativos / variantes

### Primera instalación sin datos

1. Paso 1: La migración detecta que `ac_accesos` y `ac_perfiles_accesos` existen pero están vacías; no hay nada que deduplicar.
2. Paso 2: Crea los índices únicos.
3. Paso 3: `AcPerfilesSeeder` inserta `Auditor NI` y conserva Administrador y Profesor.
4. Paso 4: `AcAccesosSeeder` inserta `zelle` e `inscripciones_ni`.
5. Paso 5: `AcPerfilesAccesosSeeder` crea la asignación de `zelle` a Administrador y la de `inscripciones_ni` a `Auditor NI`.

### Re-ejecución de los seeders

1. Paso 1: `AcPerfilesSeeder` encuentra `Auditor NI` y actualiza la misma fila; no inserta otra.
2. Paso 2: `AcAccesosSeeder` encuentra ambos códigos y actualiza las mismas filas; no inserta otras.
3. Paso 3: `AcPerfilesAccesosSeeder` encuentra las asignaciones por su par `(perfiles_id, accesos_id)` y actualiza las mismas filas; no inserta duplicados.
4. Paso 4: La revocación vuelve a dejar solo las asignaciones autorizadas.

### Perfil `Auditor NI` existente pero con `borrado_dt` no nulo

1. Paso 1: `AcPerfilesSeeder` lo encuentra por descripción exacta.
2. Paso 2: Limpia `borrado_dt`, actualiza `actualizado_dt` y reutiliza el mismo `id`.
3. Paso 3: `AcPerfilesAccesosSeeder` usa ese `id` para la asignación.

### Acceso existente con un `id` distinto del esperado

1. Paso 1: `AcAccesosSeeder` lo encuentra por `codigo_acceso`.
2. Paso 2: Actualiza la fila existente y no inserta una nueva con `id = 1` ni con otro `id` fijo.
3. Paso 3: `AcPerfilesAccesosSeeder` resuelve el `id` real por código y asigna ese valor.

### Asignación autorizada existente pero inactiva o borrada

1. Paso 1: `AcPerfilesAccesosSeeder` encuentra la fila por `(perfiles_id, accesos_id)`.
2. Paso 2: Actualiza `activo = '1'`, `aplica_en = null`, `borrado_dt = null` y `actualizado_dt`.
3. Paso 3: La asignación queda activa y única.

### Datos duplicados previos a la migración

1. Paso 1: La migración agrupa `ac_accesos` por `codigo_acceso` y conserva el menor `id` de cada grupo.
2. Paso 2: Repunta en `ac_perfiles_accesos` las referencias de los `id` eliminados hacia el `id` superviviente.
3. Paso 3: Elimina las filas duplicadas de `ac_accesos`.
4. Paso 4: Deduplica `ac_perfiles_accesos` por `(perfiles_id, accesos_id)` conservando el menor `id`.
5. Paso 5: Crea los índices únicos.

### Perfil `Auditor NI` ausente al ejecutar solo el seeder de asignaciones

1. Paso 1: `AcPerfilesAccesosSeeder` no encuentra el perfil por descripción exacta.
2. Paso 2: Lanza una excepción con un mensaje que indique ejecutar `AcPerfilesSeeder` primero.
3. Paso 3: La transacción del seeder se revierte y no deja asignaciones parciales.

### Perfil no autorizado intenta acceder al módulo

1. Paso 1: `AdminPanel` encuentra el acceso `inscripciones_ni`.
2. Paso 2: Busca la asignación del perfil del usuario y no la encuentra, o la encuentra inactiva o borrada.
3. Paso 3: Redirige a `admin/panel/login` con `admin_error` y elimina `admin_user` de la sesión.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Las tablas `ac_accesos` o `ac_perfiles_accesos` no existen | `tableExists()` antes de operar | La migración no hace nada y termina sin error | Migración aplicada; sin índices nuevos |
| `ac_accesos` tiene códigos duplicados | Agrupación por `codigo_acceso` con conteo mayor a 1 | Conserva el menor `id`, repunta asignaciones y elimina duplicados | Un solo registro por código |
| `ac_perfiles_accesos` tiene pares duplicados | Agrupación por `(perfiles_id, accesos_id)` con conteo mayor a 1 | Conserva el menor `id` y elimina el resto | Un solo registro por par |
| El índice único ya existe | `getIndexData()` o consulta equivalente | No lo vuelve a crear | Migración idempotente |
| Existe un índice con el mismo nombre pero no es único | `getIndexData()` indica que no es único | Lo elimina y lo crea como único | Índice único garantizado |
| La migración se ejecuta dos veces | Segunda ejecución de `up()` | No hay duplicados que limpiar y los índices ya existen | Sin cambios adicionales |
| `AcPerfilesSeeder` encuentra un `Auditor NI` borrado | `borrado_dt` no nulo | Limpia `borrado_dt` y actualiza la fecha | Perfil reactivado, mismo `id` |
| `AcAccesosSeeder` encuentra un código borrado | `borrado_dt` no nulo | Limpia `borrado_dt` y actualiza la fecha | Acceso reactivado, mismo `id` |
| `AcPerfilesAccesosSeeder` no encuentra `Auditor NI` | Búsqueda por descripción sin resultados | Lanza excepción y revierte la transacción | Sin asignaciones nuevas; error visible |
| `AcPerfilesAccesosSeeder` no encuentra un código de acceso | Búsqueda por `codigo_acceso` sin resultados | Lanza excepción y revierte la transacción | Sin asignaciones nuevas; error visible |
| Dos procesos intentan insertar el mismo código o par a la vez | Violación del índice único | Uno de los procesos falla; no se crean duplicados | Una sola fila; el proceso perdedor reporta error |
| Usuario sin sesión administrativa | `admin_user` ausente o inválido | Redirige al login con `admin_error` | Acceso denegado |
| Usuario de sesión ya no existe o fue borrado | Consulta a `ac_usuarios` sin resultado | Redirige al login, limpia `admin_user` | Acceso denegado |
| El módulo `inscripciones_ni` no existe o está borrado | Consulta a `ac_accesos` sin resultado o `borrado_dt` no nulo | Redirige al login con `admin_error` | Acceso denegado |
| El perfil no tiene asignación activa | Consulta a `ac_perfiles_accesos` sin resultado, inactiva o borrada | Redirige al login, limpia `admin_user` | Acceso denegado |

## Reglas de negocio y validaciones

- El acceso se identifica por `codigo_acceso`. Ningún seeder debe asumir `accesos_id = 1` ni otro `id` fijo.
- El perfil `Auditor NI` se identifica por `descripcion = 'Auditor NI'` exacta. Si se crea, no se le impone un `id` fijo.
- Solo `Auditor NI` debe tener una asignación activa de `inscripciones_ni`. Administrador, Profesor y cualquier otro perfil quedan revocados para ese acceso.
- La asignación autorizada debe quedar con `activo = '1'`, `aplica_en = null`, `borrado_dt = null` y `actualizado_dt` con la fecha de ejecución.
- La revocación de `inscripciones_ni` es física: se eliminan las filas de otros perfiles. No se usa borrado lógico.
- La revocación debe estar acotada al `accesos_id` de `inscripciones_ni`; no puede afectar `zelle` ni otros accesos.
- La asignación de `zelle` al perfil Administrador conserva el comportamiento actual: se crea o reactiva y se revoca de los demás perfiles.
- `ac_accesos.codigo_acceso` debe ser único a nivel de tabla, incluso si la fila está borrada lógicamente. Esto evita ambigüedad al resolver el módulo por código.
- `ac_perfiles_accesos (perfiles_id, accesos_id)` debe ser único a nivel de tabla. Si una fila está borrada o inactiva, el seeder la reactiva en lugar de insertar otra.
- La deduplicación conserva el menor `id` de cada grupo. Las asignaciones que apuntaban a un acceso duplicado se repuntan al acceso superviviente antes de borrar el duplicado.
- La migración es idempotente: una segunda ejecución no modifica datos ni vuelve a crear índices.
- La migración no crea ni elimina tablas, columnas o datos ajenos a la deduplicación y los índices.
- Los seeders son idempotentes en ejecución secuencial y deben poder ejecutarse dos veces sin duplicar filas.
- El seeder de asignaciones usa una transacción para que la revocación y el upsert no queden a medias.
- No se crean usuarios ni se modifican contraseñas, sedes o datos académicos.
- Todas las consultas usan el query builder o bindings; no se concatenan valores de usuario en SQL.
- Los datos nuevos y los comentarios se escriben en español, según las convenciones del repositorio.

## Áreas afectadas

- `app/Database/Migrations/2026-10-30-000105_AddUniqueIndexesToAcAccesos.php` (nueva migración).
- `app/Commands/InitPrincipalDb.php` (registrar la migración en `runPrincipalMigrations()`).
- `app/Database/Seeds/AcPerfilesSeeder.php` (resolver, crear y reactivar `Auditor NI`).
- `app/Database/Seeds/AcAccesosSeeder.php` (upsert por `codigo_acceso`; agregar `inscripciones_ni`).
- `app/Database/Seeds/AcPerfilesAccesosSeeder.php` (resolver IDs por clave natural; asignar solo `Auditor NI`; revocar otros; transacción).
- `tests/app/Database/Migrations/AcAccesosUniqueIndexesMigrationTest.php` (nueva).
- `tests/app/Database/Seeds/AcPerfilesSeederTest.php` (nueva).
- `tests/app/Database/Seeds/AcAccesosSeederTest.php` (nueva).
- `tests/app/Database/Seeds/AcPerfilesAccesosSeederTest.php` (nueva).
- `tests/app/Filters/AdminPanelTest.php` (nueva).
- `docs/features/012-permiso-administrativo-inscripciones-ni/plan.md` (este documento).

No se modifican `app/Filters/AdminPanel.php`, `app/Config/Routes.php`, controladores, vistas, la SPA ni archivos de `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

## Criterios de finalización

- [ ] La migración `000105` existe, está registrada en `init:principal` y pasa su prueba de ejecución doble sin cambios adicionales.
- [ ] La migración omite su trabajo sin error cuando `ac_accesos` o `ac_perfiles_accesos` no existen.
- [ ] Con duplicados previos en `ac_accesos`, sobrevive el menor `id`, las asignaciones se repuntan y los duplicados se eliminan.
- [ ] Con duplicados previos en `ac_perfiles_accesos`, sobrevive el menor `id` de cada par `(perfiles_id, accesos_id)`.
- [ ] Los índices únicos `uniq_ac_accesos_codigo_acceso` y `uniq_ac_perfiles_accesos_perfil_acceso` existen al finalizar la migración y rechazan inserciones duplicadas en las pruebas.
- [ ] `AcPerfilesSeeder` ejecutado dos veces deja exactamente un perfil `Auditor NI`, conserva Administrador y Profesor, y reactiva un `Auditor NI` con `borrado_dt` no nulo.
- [ ] `AcAccesosSeeder` ejecutado dos veces deja exactamente un `zelle` y un `inscripciones_ni`, incluso si sus `id` existentes no son `1`.
- [ ] `AcPerfilesAccesosSeeder` ejecutado dos veces deja exactamente una asignación activa de `inscripciones_ni`, solo para `Auditor NI`.
- [ ] Después de `AcPerfilesAccesosSeeder` no existe ninguna asignación de `inscripciones_ni` para Administrador, Profesor ni otros perfiles.
- [ ] Después de `AcPerfilesAccesosSeeder` existe exactamente una asignación activa de `zelle` para Administrador y ninguna para otros perfiles.
- [ ] Si falta el perfil `Auditor NI`, `AcPerfilesAccesosSeeder` lanza un error claro y no deja asignaciones parciales.
- [ ] La prueba del filtro `AdminPanel` confirma que un usuario con perfil `Auditor NI` y asignación activa accede al módulo `inscripciones_ni`.
- [ ] La prueba del filtro confirma que un usuario con perfil Profesor o Administrador, sin asignación, es redirigido a `admin/panel/login` con `admin_error`.
- [ ] La prueba del filtro confirma que una asignación inactiva o con `borrado_dt` no nulo también es denegada.
- [ ] La prueba del filtro confirma que un módulo inexistente o borrado es denegado.
- [ ] Se ejecutan las pruebas del área con `vendor/bin/phpunit tests/app/Database/Seeds tests/app/Database/Migrations/AcAccesosUniqueIndexesMigrationTest.php tests/app/Filters/AdminPanelTest.php` (en Windows, `vendor\bin\phpunit.bat` con los mismos argumentos) y pasan.
- [ ] Se ejecutan los tres seeders dos veces, o `php spark init:principal` dos veces, y se comprueba una sola fila por código, una sola fila `Auditor NI` y una sola asignación activa de `inscripciones_ni`.
- [ ] No se modificaron rutas, controladores, vistas, la SPA ni archivos de dependencias.
- [ ] Se actualiza `MEMORY.md` si la implementación cambia el estado o las decisiones documentadas del proyecto.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial. Se decide asignar `inscripciones_ni` solo a `Auditor NI`, crear el perfil por descripción exacta, revocar físicamente a otros perfiles y garantizar unicidad con migración más lógica de seeders. | opencode (agente) |
| 2026-10-30 | Implementación completada en `p-feature/permiso-administrativo-inscripciones-ni`: migración `000105`, seeders por clave natural, pruebas de migración, seeders y filtro `AdminPanel`. | opencode (agente) |
