Saltar al contenido principal

INV-002 Fase 4 — Roles y permisos por bodega

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Última fase de la mejora INV-002 (Almacenes Múltiples). Cierra el ciclo: ya se puede tener varias bodegas, mover stock entre ellas, despachar con recomendación… y ahora limitar quién opera en cuál.


📋 Alcance​

Hasta ahora, cualquier almacenista podía despachar, transferir o recibir en cualquier bodega. Esta fase añade una restricción opcional por bodega, gestionable por el Administrador.


🔑 Regla de compatibilidad​

Un usuario SIN almacenes asignados puede operar en TODAS las bodegas.

Es el punto clave del diseño. Preserva el comportamiento anterior (nada se rompe en instalaciones existentes) y convierte la asignación en una restricción opcional: en cuanto el Administrador asigna al menos una bodega, el usuario queda limitado a ellas.

Además, el rol Administrador nunca se restringe.

puedeOperar(idUsuario, rol, idAlmacen) =
rol === 'Administrador'
|| sin asignaciones // restricción no configurada
|| asignaciones.includes(idAlmacen)

🗄️ Base de datos​

Tabla usuarios_almacenes (id_usuario_almacen, id_usuario, id_almacen, creado) con UNIQUE (id_usuario, id_almacen) y FK ON DELETE CASCADE en ambas: la asignación no es un registro de negocio con vida propia, si desaparece el usuario o la bodega deja de tener sentido.

Migración: 016_create_usuarios_almacenes_table.sql.


🔌 API​

MétodoRutaDescripción
GET/api/usuarios/:id/almacenesBodegas asignadas al usuario
PUT/api/usuarios/:id/almacenesReemplaza el conjunto ({ idAlmacenes: number[] })
POST/api/usuarios/:id/almacenesAsigna una ({ idAlmacen })
DELETE/api/usuarios/:id/almacenes/:idAlmacenQuita una
GET/api/almacenes/:id/usuariosUsuarios con esa bodega asignada

Todas las de escritura son solo Administrador. PUT con arreglo vacío devuelve al usuario al modo sin restricción.

Nota de diseño: la UI de asignación usa POST/DELETE granulares en lugar de PUT, para poder alternar el acceso a una bodega sin borrar las demás asignaciones del usuario.


🛡️ Dónde se aplica​

OperaciónBodega validada
POST /api/transferenciasorigen y destino
PATCH /api/transferencias/:id/enviarorigen
PATCH /api/transferencias/:id/recibirdestino
PATCH /api/transferencias/:id/cancelarorigen
PATCH /api/solicitudes/:id/estado (con idAlmacenDespacho)bodega de despacho

Si la bodega no está permitida → 403 con un mensaje que indica la bodega y cómo resolverlo («No tienes permiso para despachar en "Bodega Norte". Solicita al administrador que te asigne esa bodega.»).


🖥️ UI​

En la página Almacenes, cada fila tiene un botón nuevo (Usuarios): abre un diálogo con el listado de usuarios y una casilla por usuario. Alternar la casilla concede o revoca el acceso a esa bodega sin tocar las demás.

  • El Administrador aparece marcado como no restringible.
  • Se explica en el propio diálogo la regla de compatibilidad.
  • Accesible por teclado y con estado de carga (WCAG AA).

🔑 Archivos clave​

Backend (ccf-almacen-api)

  • database/migrations/016_create_usuarios_almacenes_table.sql
  • src/domains/usuarios/permisos-almacen.service.ts — PermisosAlmacenService (puedeOperar, asegurarPuedeOperar, asignación)
  • src/domains/usuarios/entities/usuario-almacen.entity.ts
  • src/domains/usuarios/usuarios.controller.ts — 4 endpoints de asignación
  • src/domains/almacenes/almacenes.controller.ts — GET /:id/usuarios
  • src/domains/transferencias/transferencias.service.ts y src/domains/solicitudes/solicitudes.service.ts — aplicación del permiso

Frontend (ccf-almacen-web)

  • src/api/permisos-almacen.ts
  • src/pages/almacenes.tsx — botón y diálogo «Usuarios con acceso»

Spec: .opencode/skills/ideas/data/docs/superpowers/specs/INV-002-fase-4-permisos-por-bodega.md


✅ Verificación​

tsc --noEmit, build y lint en 0 en ccf-almacen-api y ccf-almacen-web.


🏁 INV-002 completo​

FaseContenidoEstado
1Multi-almacén real (stock por bodega)✅
2Transferencias entre almacenes (dos fases)✅
3Despacho multicriterio y auto-selección✅
4Roles y permisos por bodega✅

Pendientes menores fuera del alcance: recepción parcial, trazabilidad por lote en transferencias y reportes avanzados por bodega.