0014. Catálogo inicial de permisos (cat_permisos)

Estado: Propuesto Fecha: 2026-09-08 Autor: Duval Alcivar Módulo(s) afectado(s): svc-identidad (core_sigfa), todos los servicios que validan permisos en el JWT

Contexto

El ADR 0007 define cat_permisos (catálogo de permisos, generales y por módulo/página) y rel_usuario_permiso (asignación individual), y registra como pendiente 0014 el catálogo inicial de permisos por módulo/acción. El ADR 0013 define la plantilla de módulos → páginas → acciones. Este ADR define: (1) las reglas de códigos de permiso (el namespace que viaja en el JWT), (2) el catálogo inicial generado desde la plantilla, y (3) cómo se compactan los claims cuando el usuario acumula muchos permisos.

Decisión

1. Reglas de códigos de permiso

El codigo de cat_permisos es el identificador estable que viaja en el claim permisos del JWT y que cada servicio compara contra sus operaciones.

Regla: <modulo>.<pagina>.<accion>     → permiso de una acción de una página
       <modulo>.*                     → todo dentro del módulo (wildcard)

Ejemplos (por módulo): rrhh.nomina.crear, rrhh.asistencia.reportes.exportar, inventario.bajas.eliminar, permisos.usuarios.asignar, reportes.exportar (global, sin página), rrhh.*.

• Un permiso por acción de la plantilla (ADR 0013). El código es único por (empresa_id NULL, codigo) para los del catálogo base.
• Códigos de plataforma (empresa_id NULL): no dependen de la empresa; se otorgan con rel_usuario_permiso.empresa_id = NULL (alcance global) o con empresa_id concreto.
• Códigos de módulos propios de una empresa (creados vía ADR 0013): se insertan con empresa_id NOT NULL y mismos patrones de código.

2. 'Ver' es implícito (no gasta permisos)

Ver una página ya está dado por rel_usuario_menu (ADR 0007/0012): si el usuario tiene la página, la ve. No se genera ni se firma un permiso ver para el funcionamiento normal; solo se modela como acción/código cuando la página exige verificación especial (p. ej. permisos.detalle.confidencial).

Esto mantiene el claim pequeño: la navegación la controla rel_usuario_menu y la ejecución (crear/editar/eliminar/firmar…) la controlan los códigos de acción (ADR 0015). El root no lleva códigos (ADR 0007).

3. Catálogo inicial (cat_permisos global)

Se genera desde la plantilla del ADR 0013 (una fila por acción, más los resúmenes .* por módulo). Subconjunto representativo:

codigo	Alcance	Origen
permisos.usuarios.crear	módulo permisos	plantilla core
permisos.usuarios.editar	módulo permisos	plantilla core
permisos.usuarios.eliminar	módulo permisos	plantilla core
permisos.asignar	módulo permisos (página asignar)	plantilla core
empresas.gestion	global (root de plataforma)	plantilla core
rrhh.nomina.crear	módulo rrhh	plantilla erp
rrhh.nomina.editar	módulo rrhh	plantilla erp
rrhh.nomina.eliminar	módulo rrhh	plantilla erp
rrhh.nomina.aprobar	módulo rrhh (página registro)	plantilla erp
rrhh.asistencia.reportes.exportar	módulo rrhh (página reportes)	plantilla erp
inventario.bajas.crear	módulo inventario	plantilla erp
contabilidad.conciliar	módulo contabilidad	plantilla erp
promotores.rutas.crear	módulo promotores	plantilla crm
ventas.cotizaciones.aprobar	módulo ventas	plantilla crm
ventas.pedidos.anular	módulo ventas	plantilla crm
rrhh.*	resumen: todo rrhh	generado por módulo

• El seed vive con la plantilla (ADR 0013) en migraciones versionadas; se sincroniza cuando cambia la plantilla (nueva página/acción ⇒ nuevos códigos).
• Los resúmenes .* por módulo son filas reales de cat_permisos y se otorgan igual que cualquier otro permiso (para "todo rrhh" sin listar cada acción).

4. Wildcard y tamaño del claim

El claim permisos lleva solo los códigos otorgados. La validación en el servicio destino es:

authorized(code) ⇔ token.tipo_usuario == "root"
               ∨ ∃ granted ∈ token.permisos : granted == code
               ∨ granted == "<módulo>.*"  (prefijo del code)

• Otorgar rrhh.* reemplaza docenas de códigos sueltos: el token se mantiene pequeño y la resolución es local (sin consultas).
• Se mantiene alerta de tamaño: si un usuario supera ~40 códigos efectivos sin usar wildcards, se recomienda asignar .<modulo>.* en rel_usuario_permiso (regla antigua de la deuda del ADR 0007, ahora resuelta por .*).

5. Endpoints

Endpoint	Método	Qué hace
/api/v1/permisos	GET	listar cat_permisos (ADR 0009); filtrable por módulo/aplicación
/api/v1/permisos	POST	alta de un permiso nuevo (módulo propio de empresa, ADR 0016)
/api/v1/permisos/{id}	PATCH	editar nombre/descripción (nunca el codigo)

Alternativas descartadas

• Omitir cat_permisos y validar solo rel_usuario_menu_accion — deja sin representación los permisos de dominio que no cuelgan de una página (globales: reportes.exportar); cat_permisos es el namespace estable.
• Claims sin wildcard — el usuario "jefe de módulo" acarrearía decenas de códigos; el token crece sin razón.
• Códigos legibles solo en backend (no en el claim) — obligaría a una consulta por petición; rompe "validar sin consultar BD" (ADR 0007/0011).

Consecuencias

• Existe un único namespace de permisos (<modulo>.<pagina>.<accion> y .*) entendido por todos los servicios a partir del token.
• ver no gasta claim: navegación vs ejecución quedan separadas y baratas.
• Seed sincronizado con la plantilla del ADR 0013: página nueva ⇒ permiso nuevo, sin código muerto.
• Resuelto: pendiente 0014 del README (catálogo inicial de permisos por módulo/acción).

La asignación de estos códigos a un usuario se hace con rel_usuario_permiso (ADR 0007) o por página con rel_usuario_menu_accion (ADR 0015). La firma en el JWT está en el ADR 0011.