@zaamx/netme-inventory

Sistema de inventarios construido como plugin de Medusa 2.14.2.

Este plugin nace a partir de netme-plugin-base y sigue las mismas convenciones que el resto de plugins netme-* del monorepo (ver netme-pos).

Documentación

• docs/ — guía completa (modelo de datos, roles, ajustes, transferencias, API/admin, operación).
• ARCHITECTURE.md — diseño y decisiones (por qué).

Compatibilidad

Compatible con @medusajs/medusa 2.14.2.

Estructura

src/
  admin/        Personalizaciones del dashboard de admin (widgets, páginas, i18n)
  api/          Rutas API (admin/ y store/)
  jobs/         Scheduled jobs
  links/        Module links
  modules/      Módulos del plugin (modelos, servicios)
  providers/    Providers
  subscribers/  Event subscribers
  workflows/    Workflows

Desarrollo

dev.sh publica el plugin localmente, lo añade al core (mlm-medusa), limpia la caché de Vite y arranca medusa plugin:develop.

yarn dev        # equivalente a: bash dev.sh

Build

yarn build      # medusa plugin:build

Activación en el core (mlm-medusa)

Las migraciones de los módulos del plugin se ejecutan desde el core (tocan su base de datos), no desde el plugin.

1. Registrar el plugin en mlm-medusa/medusa-config.ts (array plugins):

   { resolve: "@zaamx/netme-inventory", options: {} }

   (o usar dev.sh, que publica y hace medusa plugin:add).

2. Correr migraciones desde el core — el plugin trae su migración generada con el CLI (src/modules/wms/migrations/, versionada en el repo):

   cd /ruta/al/core/mlm-medusa
   npx medusa db:migrate

   Crea las 6 tablas: wms_adjustment_ticket, wms_adjustment_line, wms_audit_log, wms_stock_transfer, wms_stock_transfer_item, wms_inventory_level_config.

   • Las secuencias de folios (wms_*_seq → ADJ-/R-/LBL-) y el trigger de inmutabilidad del audit log se aseguran de forma idempotente en un loader del módulo al arrancar (no son DML, el CLI no los genera).

   Regenerar migraciones tras cambiar modelos (necesita una DB Postgres alcanzable para iniciar MikroORM; la generación es read-only):

   cd /ruta/al/plugin/netme-inventory
   DB_HOST=127.0.0.1 DB_PORT=54322 DB_USERNAME=postgres DB_PASSWORD=postgres \
     npx medusa plugin:db:generate

3. Marcar usuarios WMS por User.metadata (solución in-house tipo netme-pos): is_wms_user: true, wms_role (operator | movements_admin | checker | super_admin) y wms_stock_location_ids: ["sloc_..."]. Para probar el flujo Maker-Checker se necesitan dos usuarios distintos asignados al mismo almacén (un operator/maker y un checker).

Fase 1 disponible — Ajustes de inventario

• Admin: Ajustes WMS (sidebar) → crear ajuste (Maker) y aprobar/aplicar (Checker).
• API: GET/POST /admin/wms/adjustments, GET /admin/wms/adjustments/:id, POST /admin/wms/adjustments/:id/resolve, GET /admin/wms/options.
• Al aprobar, el stock se aplica al InventoryLevel nativo del almacén vía adjustInventoryLevelsStep (LOCKING + compensación). Toda transición queda en wms_audit_log. La regla de oro (no auto-aprobación) se fuerza en el workflow.

Fase 2 disponible — Roles in-house (Permisos WMS)

Solución in-house sobre User.metadata (clon de pos-permissions, namespace wms_*). No requiere migración (solo metadata + UI); basta republicar el plugin.

• Admin: Permisos WMS (sidebar) → lista de usuarios + editor por usuario.
• Claves: is_wms_user, wms_role (operator/movements_admin/checker/super_admin), wms_stock_location_ids (membresía a sloc_*), wms_default_stock_location_id, wms_capabilities (mapa resuelto por rol).
• API: GET /admin/wms/users (con ?wms_only=true), GET/POST /admin/wms/wms-permissions/:id, GET /admin/wms/options.
• Reglas: Operador y Checker requieren ≥1 almacén; Admin de Movimientos y Super Admin son globales. validateWmsRoleStep (Fase 1) ya consume estas claves.

Fase 3 disponible — Transferencias + Camión Virtual

Ciclo completo con stock siempre localizado y Maker-Checker. No requiere migración (tablas creadas en Fase 0); basta republicar el plugin.

• Admin: Transferencias WMS (lista + detalle con acciones por estado) y Aprobaciones WMS (bandeja del Checker, urgentes primero).
• Ciclo: REQUESTED → PENDING_EXIT_APPROVAL → IN_TRANSIT → PENDING_ENTRY_APPROVAL → COMPLETED|DISCREPANCY + CANCELLED y retorno de camión.
• Camión Virtual por movimiento: al aprobar salida se crea una StockLocation IN_TRANSIT propia (metadata, sin Sales Channel), el stock va origen→camión; al cerrar entrada va camión→destino y la sloc se borra. Job wms-sweep-truck-locations (cron horario) limpia camiones huérfanos.
• Discrepancia (recibido ≠ enviado): el stock ya queda reflejado en el cierre y se genera un WMSAdjustmentTicket documental (source=DISCREPANCIA); no se resuelve por el flujo de ajuste manual (guard en loadAdjustmentStep).
• API: GET/POST /admin/wms/transfers, GET /admin/wms/transfers/:id, POST /admin/wms/transfers/:id/{prepare-exit|approve-exit|receive|close-entry|cancel|confirm-return}.

Publicación

publish.sh sube la versión (patch por defecto), publica en npm y lo instala en el core con reintentos mientras el registry propaga la nueva versión.

bash publish.sh           # patch
bash publish.sh minor     # minor
bash publish.sh major     # major