INV-002 Fase 4 — Roles y permisos por bodega
Ú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étodo | Ruta | Descripción |
|---|---|---|
GET | /api/usuarios/:id/almacenes | Bodegas asignadas al usuario |
PUT | /api/usuarios/:id/almacenes | Reemplaza el conjunto ({ idAlmacenes: number[] }) |
POST | /api/usuarios/:id/almacenes | Asigna una ({ idAlmacen }) |
DELETE | /api/usuarios/:id/almacenes/:idAlmacen | Quita una |
GET | /api/almacenes/:id/usuarios | Usuarios 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/DELETEgranulares en lugar dePUT, para poder alternar el acceso a una bodega sin borrar las demás asignaciones del usuario.
🛡️ Dónde se aplica
| Operación | Bodega validada |
|---|---|
POST /api/transferencias | origen y destino |
PATCH /api/transferencias/:id/enviar | origen |
PATCH /api/transferencias/:id/recibir | destino |
PATCH /api/transferencias/:id/cancelar | origen |
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.sqlsrc/domains/usuarios/permisos-almacen.service.ts—PermisosAlmacenService(puedeOperar,asegurarPuedeOperar, asignación)src/domains/usuarios/entities/usuario-almacen.entity.tssrc/domains/usuarios/usuarios.controller.ts— 4 endpoints de asignaciónsrc/domains/almacenes/almacenes.controller.ts—GET /:id/usuariossrc/domains/transferencias/transferencias.service.tsysrc/domains/solicitudes/solicitudes.service.ts— aplicación del permiso
Frontend (ccf-almacen-web)
src/api/permisos-almacen.tssrc/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
| Fase | Contenido | Estado |
|---|---|---|
| 1 | Multi-almacén real (stock por bodega) | ✅ |
| 2 | Transferencias entre almacenes (dos fases) | ✅ |
| 3 | Despacho multicriterio y auto-selección | ✅ |
| 4 | Roles y permisos por bodega | ✅ |
Pendientes menores fuera del alcance: recepción parcial, trazabilidad por lote en transferencias y reportes avanzados por bodega.
