[EPIC] Extraer la gestión de almacén a un paquete reutilizable (@globalemergency/warehouse-core)

[vgpastor]

Objetivo

Extraer la gestión de almacén de ResponseGrid a un producto open-source independiente — un WMS genérico (pensado para almacenes de Protección Civil, pero válido para cualquier sector) — y hacer que ResponseGrid lo reutilice como librería interna, en lugar de mantener la misma lógica dos veces.

Son dos software totalmente separados (distinta BD, servidor, auth y organizaciones; sin datos compartidos). El único punto de unión es código reutilizado vía paquetes.

---

🧭 Estado actual y próximos pasos (handoff para agentes)

Hecho: Fase 1 ✅ · Fase 2 ✅ (núcleo de dominio del WMS nuevo, dominio puro) · Fase 0 ✅ (taxonomía data-driven #380 + migración de consumidores a slug #382/#395) · Fase 0.5 persistencia ✅ (warehouse-postgres, schema wms. + repos + consumidor de validación, #383/#392).

Fase 3 (app de referencia standalone) se desarrolla directamente en OTRO repositorio, fuera de este monorepo — no se implementa aquí ni se trackea en esta épica.

Próximos pasos (issues abiertas, claimables):

• WMS OSS: decisiones transversales de producto (nombre, licencia, alcance v1, integración desacoplada) #385 — Transversales: decisiones de producto (nombre, licencia OSS, alcance v1, integración desacoplada). Condiciona Fase 4: extracción de packages/warehouse-* a repo OSS público (publish + consumo por versión) #386.
• Fase 4: extracción de packages/warehouse-* a repo OSS público (publish + consumo por versión) #386 — Fase 4: extracción de packages/warehouse-* a repo OSS público + publish. Depende de WMS OSS: decisiones transversales de producto (nombre, licencia, alcance v1, integración desacoplada) #385.

Orden sugerido: #385 → #386.

Convenciones para continuar (importante):

• Cada incremento = rama nueva desde main (git fetch origin main && git checkout -B origin/main), PR con Closes #NN, squash + auto-merge en verde. Reclamar la issue (in-progress) antes de empezar (protocolo en AGENTS.md).
• @globalemergency/warehouse-core es dominio puro: ESLint no-restricted-imports prohíbe @nestjs/*, drizzle-orm, pg y apps/*. Tenencia opaca vía ScopeId.
• Tests del paquete: se co-ubican como src/**/*.test.ts, compilan con tsc -p tsconfig.test.json a dist-test/ (git-ignored) y corren con node --test — porque el type-stripping puro no soporta enum/parameter-properties. Los gatea el step CI «Run tests — warehouse-core» (pnpm --filter '@globalemergency/warehouse-core' test). .prettierrc propio del paquete (comillas simples). Los int-tests de warehouse-postgres necesitan Postgres → job Test con servicio.
• Al genericizar consumidores del host: frontera 1:1 (API y columna DB sin cambios; el adapter traduce), como se hizo con ScopeId/emergency_id en feat(warehouse-core): extrae containers (Container) al paquete usando ScopeId #366/Extraer el módulo logistics (TransportCapacity + Shipment) a @globalemergency/warehouse-core #367.

---

Decisiones ya cerradas

• Qué viaja en el paquete: dominio + persistencia + migraciones, en capas → @globalemergency/warehouse-core (puro) + @globalemergency/warehouse-postgres (Drizzle) + @globalemergency/warehouse-nest (glue DI, opcional). Sin HTTP ni auth (los pone cada host).
• Granularidad: un solo warehouse-core con módulos internos (kernel/catalog/inventory/containers/logistics) vía subpath exports.
• Auth/permisos: fuera del paquete (cada host). En el paquete solo ports de autorización + actorId opaco.
• Tenencia: el core opera contra un ScopeId opaco (WMS → Organización/Prote; ResponseGrid → Emergencia/Centro).
• Consumo: entidades reales del paquete (cero copia); el vertical compone (referencia por id).
• Scope de paquete: @globalemergency/*. Topología final: polyrepo; paso 1 = in-monorepo (workspace:*).

Estado de partida (extraer vs construir)

Lo existente cubre ~40%. Se construye (~60%): Warehouse/Zone/Bin, StockItem, StockMovement (kardex), salidas/consumo, FEFO/caducidad activa, UoM + decimales, min/max, recuentos, concurrencia optimista, idempotencia.

Issues hijas

✅ Entregado

• feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356 — módulo kernel (SupplyLine, Category, CategoryDefinition). Mergeado + desplegado.
• feat(warehouse-core): extrae el módulo catalog (Supply + resolvers) al paquete #360 — módulo catalog (Supply, resolvers, ports de catálogo). Mergeado + desplegado.
• feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364 — paquete @globalemergency/warehouse-postgres (supplyLineColumns + mappers; drizzle-orm peerDependency). Mergeado.
• feat(warehouse-core): añade ScopeId, el id opaco de tenencia del kernel #365 — ScopeId (id opaco de tenencia) en el kernel. Mergeado.
• feat(warehouse-core): extrae containers (Container) al paquete usando ScopeId #366 — módulo containers (Container palet/caja/lote + port) genericizado a ScopeId; frontera 1:1 en el host (API y columna DB sin cambios). Mergeado.
• Extraer el módulo logistics (TransportCapacity + Shipment) a @globalemergency/warehouse-core #367 — módulo logistics (TransportCapacity, Shipment/transfer, matching, ShipmentDelivered + ports) sobre ScopeId; frontera 1:1 en el host. Mergeado. → Fase 1 completa.
• WMS core (Fase 2): módulo inventory — Warehouse + Zone #370 — módulo inventory (Warehouse + Zone) sobre ScopeId; arranca la Fase 2 (WMS core nuevo). Tests propios del paquete (node --test sobre JS compilado) gateados en CI. Mergeado.
• WMS core (Fase 2): agregado Bin (ubicación física) #372 — agregado Bin (ubicación física; root propio que referencia warehouse+zone por id) en inventory. → backbone de ubicaciones completo. Mergeado.
• WMS core (Fase 2): StockItem — existencia (producto × lote × bin × estado) #374 — agregado StockItem (existencia: producto × lote × bin × estado) + VOs Quantity (decimal + UoM) y Lot (con caducidad para FEFO); version para concurrencia optimista. → el corazón del WMS. Mergeado.
• WMS core (Fase 2): StockMovement — kardex (asiento unificado de doble pata) #376 — StockMovement (kardex: asiento inmutable de doble pata) + applyStockMovement (mover = decrementar uno/incrementar otro); idempotencia de entradas (idempotencyKey), port append-only. → libro mayor + salidas/consumo/traslados. Mergeado.
• WMS core (Fase 2): FEFO — servicio de asignación por caducidad #378 — allocateFefo (servicio de asignación por caducidad, first-expired-first-out; plan de reparto puro + shortfall). → Fase 2 completa: núcleo de dominio del WMS terminado. Mergeado.
• Fase 0: base data-driven de la taxonomía — CategorySlug + CategoryRegistry #380 — base data-driven de la taxonomía en el kernel: CategorySlug (VO), CategoryRegistry (jerarquía/prefijos data-driven), CORE_CATEGORY_SLUGS. Sin tocar consumidores. Mergeado. (Follow-up completado en Fase 0 (follow-up de #380): migrar SupplyLine + consumidores de Category enum a CategorySlug/registry #382.)
• Fase 0 (follow-up de #380): migrar SupplyLine + consumidores de Category enum a CategorySlug/registry #382 — Fase 0 (follow-up de Fase 0: base data-driven de la taxonomía — CategorySlug + CategoryRegistry #380): migración breaking de SupplyLine + consumidores de Category a slug validado — SupplyLine.category pasa a string validado con CategorySlug; el validador HTTP CategorySlugProperty sustituye a @IsEnum(Category); gen:api abre el contrato público a string; Category/CORE_CATEGORY_SLUGS quedan como semilla core. Web sin cambios (ya data-driven). Comportamiento 1:1. Mergeado (feat(supplies): abre Category de enum cerrado a slug validado (data-driven) — Fase 0 #395). → Fase 0 completa.
• Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383 — Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms., repos Drizzle de los 4 ports, migraciones namespaced, consumidor de validación standalone). Mergeado (feat(warehouse-postgres): persistencia del inventario WMS (schema wms.) — Fase 0.5 #392). → el WMS ya tiene dominio + almacenamiento.
• WMS core (Fase 2, refinamiento): recuentos — reconcileCount (conteo físico ↔ sistema → ajuste) #388 — refinamiento Fase 2: reconcileCount (recuentos — concilia conteo físico ↔ sistema y produce el StockMovement de ajuste; plan/ejecución). Dominio puro. Mergeado.
• WMS core (Fase 2): reservas — reserveStock / releaseReservation (Available ↔ Reserved) #390 — reservas: reserveStock/releaseReservation (transfer available ↔ reserved del mismo grano; el stock no sale del bin). Compañero de FEFO para el ciclo asignación→picking. Dominio puro. Mergeado.
• WMS core (Fase 2): gestión de caducidad — findExpired / expiringWithin / expiryStatusOf #393 — gestión de caducidad: findExpired/expiringWithin/expiryStatusOf/nextToExpire (visibilidad proactiva de la caducidad; compañero de FEFO). Dominio puro. Mergeado.

🔜 Abierto (claimable)

• WMS OSS: decisiones transversales de producto (nombre, licencia, alcance v1, integración desacoplada) #385 — Transversales: decisiones de producto (nombre, licencia, alcance v1, integración desacoplada).
• Fase 4: extracción de packages/warehouse-* a repo OSS público (publish + consumo por versión) #386 — Fase 4: extracción a repo OSS público + publish.

Fase 0 — Genericización in-situ

• Introducir ScopeId sobre EmergencyId como clave de partición opaca — feat(warehouse-core): añade ScopeId, el id opaco de tenencia del kernel #365 (id genérico en el kernel; mapeo EmergencyId→ScopeId en la frontera del host).
• Abrir Category de enum a slug data-driven (taxonomía configurable) — base en Fase 0: base data-driven de la taxonomía — CategorySlug + CategoryRegistry #380 (CategorySlug/CategoryRegistry/CORE_CATEGORY_SLUGS) + migración de consumidores completada (SupplyLine.category → slug validado) en Fase 0 (follow-up de #380): migrar SupplyLine + consumidores de Category enum a CategorySlug/registry #382/feat(supplies): abre Category de enum cerrado a slug validado (data-driven) — Fase 0 #395.

Fase 0.5 — Paquete precursor in-monorepo ✅

• Scaffolding warehouse-core + warehouse-postgres (workspace:*, build dual, subpaths) — feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356/feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364.
• Regla ESLint dependencia unidireccional apps/api → @globalemergency/warehouse-* — feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356/feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364.
• Migraciones namespaced + schema Postgres wms. — Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383/feat(warehouse-postgres): persistencia del inventario WMS (schema wms.) — Fase 0.5 #392.
• Consumidor de validación sin contexto ResponseGrid (int-tests con pool propio) — Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383/feat(warehouse-postgres): persistencia del inventario WMS (schema wms.) — Fase 0.5 #392.

Fase 1 — Mover lo puro extraíble al paquete ✅

• kernel: value objects de material — feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356.
• catalog: Supply, resolvers, ports — feat(warehouse-core): extrae el módulo catalog (Supply + resolvers) al paquete #360.
• persistencia compartida de la línea (supplyLineColumns) → warehouse-postgres — feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364.
• containers: Container (palet/caja/lote) sobre ScopeId — feat(warehouse-core): extrae containers (Container) al paquete usando ScopeId #366.
• logistics: TransportCapacity, Shipment/transfer sobre ScopeId — Extraer el módulo logistics (TransportCapacity + Shipment) a @globalemergency/warehouse-core #367.
• ResponseGrid consume el paquete; adapters de identity y HTTP en el host — feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356/feat(warehouse-core): extrae el módulo catalog (Supply + resolvers) al paquete #360/feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364/feat(warehouse-core): extrae containers (Container) al paquete usando ScopeId #366/Extraer el módulo logistics (TransportCapacity + Shipment) a @globalemergency/warehouse-core #367.

Fase 2 — Construir el núcleo WMS nuevo (en el paquete) ✅

• Warehouse / Zone / Bin ✓ (WMS core (Fase 2): módulo inventory — Warehouse + Zone #370 Warehouse+Zone, WMS core (Fase 2): agregado Bin (ubicación física) #372 Bin)
• StockItem (producto × lote × ubicación × estado) ✓ (WMS core (Fase 2): StockItem — existencia (producto × lote × bin × estado) #374; + Quantity/Lot)
• StockMovement — kardex ✓ (WMS core (Fase 2): StockMovement — kardex (asiento unificado de doble pata) #376; asiento unificado de doble pata + applyStockMovement)
• Salidas / consumo / decremento ✓ (WMS core (Fase 2): StockMovement — kardex (asiento unificado de doble pata) #376; issue/transfer)
• UoM + cantidades decimales ✓ (WMS core (Fase 2): StockItem — existencia (producto × lote × bin × estado) #374, VO Quantity)
• FEFO / caducidad activa ✓ (WMS core (Fase 2): FEFO — servicio de asignación por caducidad #378 allocateFefo + WMS core (Fase 2): gestión de caducidad — findExpired / expiringWithin / expiryStatusOf #393 gestión de caducidad)
• Concurrencia optimista + idempotencia de entradas ✓ (StockItem.version WMS core (Fase 2): StockItem — existencia (producto × lote × bin × estado) #374 + idempotencyKey WMS core (Fase 2): StockMovement — kardex (asiento unificado de doble pata) #376)
• Recuentos (nivel item) ✓ (WMS core (Fase 2, refinamiento): recuentos — reconcileCount (conteo físico ↔ sistema → ajuste) #388; reconcileCount)
• Reservas (available ↔ reserved) ✓ (WMS core (Fase 2): reservas — reserveStock / releaseReservation (Available ↔ Reserved) #390; reserveStock/releaseReservation)

Núcleo de dominio del WMS completo (dominio puro): ubicaciones + existencia + kardex + FEFO + recuentos (#388) + reservas (#390) + caducidad (#393), con persistencia Postgres (#383). Queda min/max (reorder) (en pausa: se está pensando algo más grande) y el recuento a nivel de bin como refinamiento futuro; lo esencial está.

Fase 3 — App de referencia standalone — fuera de este repo

• WMS OSS desplegable con auth propia. Se desarrolla directamente en otro repositorio (fuera de este monorepo); no se trackea aquí.

Fase 4 — Extracción a repo OSS — #386

• Mover packages/warehouse-* al repo público; workspace:* → versión publicada; CI/publish (depende de WMS OSS: decisiones transversales de producto (nombre, licencia, alcance v1, integración desacoplada) #385)

Transversales (decisiones abiertas) — #385

• Nombre de producto (marca) · [ ] Licencia OSS · [ ] Alcance mínimo v1 · [ ] Integración desacoplada salida↔donación (futura)

Definición de Done

Criterios base: cada sub-issue con gate CI verde y PR con Closes #NN.

Criterios específicos:

• warehouse-core + -postgres existen como paquetes, consumidos vía workspace:*, con dependencia unidireccional ESLint — feat(warehouse-core): extrae el kernel de material a @globalemergency/warehouse-core #356/feat(warehouse-core): extrae el módulo catalog (Supply + resolvers) al paquete #360/feat(warehouse-postgres): estrena el paquete de persistencia con supply-line-columns #364/feat(warehouse-core): extrae containers (Container) al paquete usando ScopeId #366/Extraer el módulo logistics (TransportCapacity + Shipment) a @globalemergency/warehouse-core #367.
• La lógica de almacén (existente) vive una sola vez en el paquete. (Fase 1 completa: kernel/catalog/persistencia-línea/containers/logistics ✓)
• El paquete es agnóstico de emergencia/Prote/identity y no importa de apps/api. (todo el dominio extraído opera contra ScopeId; HTTP/auth/ports de estado en el host)
• Consumidor de validación sin contexto ResponseGrid. (Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383/feat(warehouse-postgres): persistencia del inventario WMS (schema wms.) — Fase 0.5 #392)
• Migraciones del paquete namespaced en schema wms. (Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383/feat(warehouse-postgres): persistencia del inventario WMS (schema wms.) — Fase 0.5 #392)
• Núcleo WMS nuevo (Warehouse/Bin/StockItem/StockMovement/salidas/FEFO/UoM) construido y testeado. (Fase 2: WMS core (Fase 2): módulo inventory — Warehouse + Zone #370/WMS core (Fase 2): agregado Bin (ubicación física) #372/WMS core (Fase 2): StockItem — existencia (producto × lote × bin × estado) #374/WMS core (Fase 2): StockMovement — kardex (asiento unificado de doble pata) #376/WMS core (Fase 2): FEFO — servicio de asignación por caducidad #378; recuentos WMS core (Fase 2, refinamiento): recuentos — reconcileCount (conteo físico ↔ sistema → ajuste) #388; reservas WMS core (Fase 2): reservas — reserveStock / releaseReservation (Available ↔ Reserved) #390; caducidad WMS core (Fase 2): gestión de caducidad — findExpired / expiringWithin / expiryStatusOf #393; persistencia Fase 0.5: persistencia del inventario en warehouse-postgres (schema wms. + repos + migraciones + consumidor de validación) #383)
• (Opcional) extracción de packages/warehouse-* a repo OSS con licencia. (Fase 4: extracción de packages/warehouse-* a repo OSS público (publish + consumo por versión) #386; la app de referencia standalone se aborda en otro repo)

---

Esta épica es el punto de entrada; el detalle técnico de cada pieza va en su sub-issue.