Saltar al contenido principal

INV-002 Fase 2 — Transferencias entre almacenes

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

Implementación de la Fase 2 de la mejora INV-002 (Almacenes Múltiples): el traslado de stock entre dos bodegas con trazabilidad en dos fases, según la decisión Q4.


📋 Alcance​

La Fase 1 (ya entregada) permitía tener stock independiente por almacén (stock_almacen), pero no moverlo entre ellos. Esta fase habilita que el almacén de origen despache y el de destino confirme la recepción.

Estados y transiciones:

pendiente ──enviar──▶ en_transito ──recibir──▶ recibida
│
└──cancelar──▶ cancelada

🎯 Por qué dos fases​

Confundir "salió de origen" con "llegó a destino" descuadra el inventario: si se descontara y sumara en un solo paso, una mercancía perdida en el traslado quedaría contabilizada como existente. El flujo en dos fases obliga a que alguien confirme la llegada.

  • Enviar descuenta el stock del almacén de origen (movimiento salida).
  • Recibir suma el stock al almacén de destino (movimiento entrada).
  • Una transferencia en tránsito no se puede cancelar; se revierte con una transferencia inversa.

🗄️ Base de datos​

ObjetoDescripción
transferenciasCabecera: código, almacenes, estado, usuarios y fechas de cada hito
detalle_transferenciaLíneas (producto + cantidad), ON DELETE CASCADE
seq_transferencias_codigoSecuencia que genera el código legible TRF-0001

Migraciones: 014_create_transferencias_table.sql y 015_create_detalle_transferencia_table.sql.

Constraints destacados: CHECK de estados, CHECK (id_almacen_origen <> id_almacen_destino) y CHECK (cantidad > 0).


🧩 Backend (ccf-almacen-api)​

Nuevo dominio src/domains/transferencias/:

  • transferencias.service.ts — lógica transaccional. Cada transición abre una DataSource.transaction, bloquea la transferencia con pessimistic_write (evita envíos/recepciones concurrentes) y aplica el stock línea a línea con StockAlmacenService.aplicarMovimiento. Si una línea falla, se revierte todo.
  • transferencias.controller.ts — 6 endpoints; el usuario que ejecuta la acción se toma del JWT, nunca del cuerpo.
  • entities/, dto/, transferencias.module.ts
  • stock-almacen.service.ts — nuevo método de lectura obtenerDisponible (no crea filas, a diferencia de obtenerOCrear), usado en la validación al crear.
  • app.module.ts — módulo y entidades registrados.

Endpoints​

MétodoRutaRoles
POST/api/transferenciasAdmin, Almacenista, Auxiliar inventario
GET/api/transferenciasAutenticado
GET/api/transferencias/:idAutenticado
PATCH/api/transferencias/:id/enviarAdmin, Almacenista
PATCH/api/transferencias/:id/recibirAdmin, Almacenista
PATCH/api/transferencias/:id/cancelarAdmin, Almacenista

🖥️ Frontend (ccf-almacen-web)​

  • src/pages/transferencias.tsx — listado con filtros (estado y almacén), paginación, creación en diálogo con líneas dinámicas y acciones por estado con confirmación.
  • src/api/transferencias.ts, src/hooks/use-transferencias.ts, src/models/transferencia.entity.ts
  • sidebar-option.ts — nueva opción Transferencias (_id: '27').

Estados de UI: carga, vacío y error. Badge de estado con texto (no solo color) para accesibilidad.


📐 Decisiones​

Sin reserva de stock. Se evaluó reservar stock al crear (pendiente) y se descartó: obligaría a mantener un contador de "reservado" separado del stock_actual, con riesgo de descuadre y sin requisito de negocio que lo justifique. En su lugar hay validación doble (al crear, informativa; al enviar, autoritativa dentro de la transacción).


✅ Verificación​

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


📌 Pendiente (fases siguientes)​

  • Fase 3: despacho multicriterio y auto-selección de almacén.
  • Fase 4: roles/permisos por bodega.
  • Recepción parcial y trazabilidad por lote en transferencias (fuera del alcance de esta fase).

Spec: .opencode/skills/ideas/data/docs/superpowers/specs/INV-002-fase-2-transferencias.md Manual: Transferencias entre Almacenes