feat: [TESIS-103] add stock transfers between warehouses

[TomasMartin2004]

🔗 Ticket de Jira

TESIS-103 — bloquea a TESIS-62

⚠️ Base en TESIS-102-product-category-and-primary-warehouse (PR #58), no en master: las dos cards tocan ProductListSerializer. Cuando mergee el #58, GitHub reapunta este PR a master solo.

---

📝 Descripción

Construye el dominio que TESIS-62 estaba esperando. El tab "In Transit" y el "+N Incoming" del Master Catalog nunca fueron una columna faltante: no había forma de decir que unas unidades salieron de un depósito y todavía no llegaron a otro. stocks responde "cuántas unidades hay en este depósito" y no puede sostener unidades que no están en ninguno.

Un solo número derivado, no dos

A nivel producto, in transit e incoming son la misma cifra: unas unidades en vuelo están a la vez viajando y llegando a algún lado. Se separan sólo mirando por depósito, y la fila del catálogo es por producto. Así que la API expone in_transit_quantity una vez y alimenta las dos cosas: el filtro del tab y el badge.

Fuera de alcance

Órdenes de compra a proveedor. TESIS-62 dice "productos en movimiento entre nodos" — movimiento interno, no abastecimiento externo. Es otro dominio y otra card.

Sin estado borrador, a propósito

Una transferencia creada y no despachada deja las unidades en el origen, así que no aporta nada a los dos números que este modelo existe para producir, y sumaría un estado que nadie consulta. Crear una transferencia es despacharla: las unidades salen del origen en ese momento, entran al destino al recibirla y vuelven al origen al cancelarla.

Las unidades en vuelo no cuentan en total_stock: no están disponibles en ningún nodo, que es exactamente el motivo de exponerlas aparte.

---

🧠 Las tres decisiones que no se ven en el diff

1. Subconsulta escalar y no un segundo left_joins. with_total_stock ya hace join con stocks y agrupa por products.id. Un segundo join a otra tabla hija daría producto cartesiano entre las dos y multiplicaría el SUM de stock. Hay un spec que despacha dos transferencias del mismo producto y verifica que total_stock sigue bien, y otro que fija que la subconsulta agrega 0 queries por fila.

2. AdjustWarehouseStock no toma el advisory lock. Lo toma quien la invoca, y no es un olvido: la lectura del saldo tiene que estar dentro del mismo lock que la escritura de la fila de transferencia. Tomarlo adentro lo cerraría antes de tiempo y dejaría abierta justo la ventana que el lock existe para cerrar (ADR-009).

3. El chequeo de "sigue en vuelo" va adentro del lock. Si estuviera afuera, dos requests simultáneos sobre la misma transferencia lo pasarían los dos y las unidades entrarían al destino dos veces. Hay un spec que intenta liquidarla dos veces y verifica que el destino queda en 4, no en 8.

---

🛠️ Cambios realizados

• Migración create_stock_transfers: company_id, product_id, origin_warehouse_id, destination_warehouse_id, quantity, status, dispatched_at (NOT NULL) y settled_at. Índice (company_id, status, product_id), que es exactamente como consulta el listado.
• Tres CHECK constraints: quantity > 0, vocabulario de status, y origen ≠ destino. Con specs que prueban que update_all no los puede saltear — mismo criterio que stocks.quantity.
• FKs en RESTRICT, no cascade: una transferencia registra unidades reales ya descontadas de un origen; borrar el producto o un depósito las dejaría huérfanas sin rastro. Mismo razonamiento que order_items → products.
• StockTransfer (CompanyScoped) con enum validate: true, validación cross-company del producto y los dos depósitos, y scope in_flight.
• POROs Catalog::DispatchTransfer y Catalog::SettleTransfer (recibir y cancelar comparten todo salvo a qué depósito vuelven las unidades), más Catalog::AdjustWarehouseStock e InsufficientStockError.
• Product: in_transit_quantity con la misma mecánica que total_stock — alias del SELECT si la fila vino del scope, suma por asociación si no.
• Endpoints: GET/POST /api/v1/stock-transfers, POST .../:id/receive, POST .../:id/cancel, con policy y filtros por status y product_id.
• docs/guidelines/architecture.md: nota en §6 explicando por qué las unidades en vuelo viven aparte de stocks.

---

🧪 Cómo probar

1. bin/rails db:migrate
2. Crear stock en dos depósitos y despachar:
   POST /api/v1/stock-transfers con { "stock_transfer": { "product_id": …, "origin_warehouse_id": …, "destination_warehouse_id": …, "quantity": 4 } }
3. GET /api/v1/products → esa fila trae in_transit_quantity: 4, y total_stock bajó 4.
4. POST /api/v1/stock-transfers/:id/receive → el destino sube 4, in_transit_quantity vuelve a 0 y total_stock se recupera.
5. Repetir el receive → 409.
6. Despachar más unidades de las que tiene el origen → 422, y no queda ninguna fila escrita.

---

📸 Evidencia visual

N/A (backend).

Validación reproducida local:

• bundle exec rspec → 514 examples, 0 failures (39 nuevos)
• bundle exec rubocop --force-exclusion → 137 archivos, sin ofensas
• bin/brakeman -q → No warnings found
• Sembrado y comprobado por runner: NOR-002 reporta in_transit_quantity: 5 con total_stock: 20

---

⚠️ Impacto y consideraciones

• Breaking changes: no. Suma una tabla, endpoints nuevos y un campo al serializer de productos.
• total_stock no cambia de significado, pero sí de valor para un producto con transferencias en vuelo: esas unidades dejan de contarse. Es el comportamiento buscado y está cubierto por specs.
• Sync saliente: las tres transiciones escriben stocks.quantity, así que disparan el after_commit de Stock y el stock actualizado se propaga a los canales sin código extra.
• bin/rails db:seed sigue abortando en una corrida limpia, pero la causa es previa a esta branch: el bloque de TESIS-40 usa ml_integration sin asignarla nunca. El PR feat: [TESIS-45] add shipments and shipment_events data model #56 lo arregla y todavía no mergeó, así que deliberadamente no dupliqué el fix acá para no generar conflicto.
• Sin cambios de entorno.