INV-002 Fase 2 — Transferencias entre almacenes
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
| Objeto | Descripción |
|---|---|
transferencias | Cabecera: código, almacenes, estado, usuarios y fechas de cada hito |
detalle_transferencia | Líneas (producto + cantidad), ON DELETE CASCADE |
seq_transferencias_codigo | Secuencia 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 unaDataSource.transaction, bloquea la transferencia conpessimistic_write(evita envíos/recepciones concurrentes) y aplica el stock línea a línea conStockAlmacenService.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.tsstock-almacen.service.ts— nuevo método de lecturaobtenerDisponible(no crea filas, a diferencia deobtenerOCrear), usado en la validación al crear.app.module.ts— módulo y entidades registrados.
Endpoints
| Método | Ruta | Roles |
|---|---|---|
POST | /api/transferencias | Admin, Almacenista, Auxiliar inventario |
GET | /api/transferencias | Autenticado |
GET | /api/transferencias/:id | Autenticado |
PATCH | /api/transferencias/:id/enviar | Admin, Almacenista |
PATCH | /api/transferencias/:id/recibir | Admin, Almacenista |
PATCH | /api/transferencias/:id/cancelar | Admin, 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.tssidebar-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
