Saltar al contenido principal

Ubicaciones de Almacén — Sistema de ubicaciones físicas (zona/pasillo/estante/nivel)

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

Implementación de la mejora INV-001 (prioridad Alto) para organizar el almacén físico en una jerarquía de ubicaciones y asociar cada producto a su ubicación física exacta.


📋 Alcance​

Jerarquía de ubicaciones:

Zona → Pasillo → Estante → Nivel

Cada nivel se administra de forma independiente y el nivel es la unidad de ubicación física asignada al producto.


🔧 Backend (ccf-almacen-api)​

Nuevas tablas (migración 004_create_ubicaciones_tables.sql)​

  • zonas (id_zona, nombre único, descripcion, activo).
  • pasillos (id_pasillo, id_zona FK → zonas, nombre único por zona, descripcion, activo).
  • estantes (id_estante, id_pasillo FK → pasillos, nombre único por pasillo, descripcion, activo).
  • niveles (id_nivel, id_estante FK → estantes, nombre único por estante, descripcion, activo).

Todas las FK usan ON DELETE RESTRICT y se agregan índices de filtrado por padre, secuencias id por tabla y COMMENT sobre tablas y columnas (regla 13). Únicas colectivas por (padre, nombre) garantizan integridad.

Relación a productos (migración 005_add_nivel_fk_to_productos.sql)​

  • ALTER TABLE productos ADD COLUMN id_nivel INTEGER + FK fk_productos_nivel (ON DELETE RESTRICT) + índice idx_productos_id_nivel.

Nuevo dominio src/domains/ubicaciones/​

  • Entidades: zona.entity, pasillo.entity, estante.entity, nivel.entity (relaciones ManyToOne/OneToMany).
  • DTOs: create/update por nivel (validación class-validator).
  • ubicaciones.service.ts: CRUD por nivel + listados filtrados por padre y bloqueo de borrado cuando existen hijos.
  • 4 controladores REST: @Controller('api/zonas'), .../pasillos, .../estantes, .../niveles.

Cambios en productos​

  • producto.entity.ts: columna id_nivel + relación nivel (ManyToOne → Nivel).
  • create-producto.dto / update-producto.dto: idNivel opcional (IsOptional, IsNumber, IsPositive).
  • productos.module.ts: registra Nivel en forFeature y app.module.ts: registra las 4 entidades en forRoot(entities: [...]).
  • productos.service.ts: las consultas incluyen ahora nivel, nivel.estante, nivel.estante.pasillo, nivel.estante.pasillo.zona.

Permisos​

Los CRUD de ubicaciones requieren roles Admin / Almacenista (@Roles).


💻 Frontend (ccf-almacen-web)​

  • Modelo IZona | IPasillo | IEstante | INivel y helper formatearRutaNivel en src/models/ubicacion.entity.ts.
  • Cliente API en src/api/ubicacion.ts (CRUD + filtros por padre).
  • product.entity.ts (frontend): idNivel / nivel + método obtenerUbicacion().
  • Formulario de producto: nueva sección Ubicación en el Almacén con selects en cascada (zona → pasillo → estante → nivel) y idNivel en el schema zod; el nivel se precarga al editar y se persiste en creación/edición.
  • Lista de productos: nueva columna Ubicación con la ruta formateada.
  • Detalle de producto: bloque Ubicación con la ruta completa.
  • Pantalla de gestión components/ubicaciones/ubicaciones-management.tsx: navegación jerárquica lateral + CRUD por nivel.
  • Menú lateral: ítem Ubicaciones.

📚 Documentación (ccf-almacen-wiki)​

  • Nuevo manual Ubicaciones Físicas de Almacén (manuales/inventarios/ubicaciones.md), registrado en el índice De usuario.
  • Actualizado el backlog de mejoras (mejoras-propuestas-almacen.md) marcando INV-001 como implementada.

🧪 Verificación​

  • Backend: npx tsc --noEmit sin errores.
  • Frontend: npx tsc --noEmit sin errores.
  • Las migraciones siguen el patrón idempotente y respetan la convención de nombres del framework.