Sistema de Gestión de Almacén (WHMS)

El módulo WHMS proporciona gestión de almacén event-sourced con un registro inmutable de colocaciones. El estado actual siempre se deriva del historial de eventos — nunca se almacena directamente.

Almacén 3D Interactivo

Explore el almacén en 3D — orbite, haga zoom y haga clic en cualquier slot para inspeccionar su contenido, utilización de zona y actividad reciente.

Visualización de Escaneo LiDAR

Los sensores LiDAR proporcionan mapeo espacial con precisión milimétrica. Certexi procesa nubes de puntos en tiempo real para verificar la ocupación de slots.

Arquitectura

Principios de Diseño

Registro Inmutable de Eventos

Los eventos son solo-adición — sin actualizaciones, sin eliminaciones. Cada colocación, remoción y verificación se registra como una nueva fila. El estado actual se deriva de reproducir los eventos.

Coordenadas Locales del Almacén

El sistema usa coordenadas relativas al plano de planta (x, y) en lugar de GPS. Esto funciona en interiores, offline, y sobrevive actualizaciones del plano de planta ya que el slot_id estable es la referencia principal.

Diseño con Evidencia Primero

Cada colocación requiere evidencia:

• Prueba de escaneo — Código de barras/QR de slot + activo
• Prueba fotográfica — Foto con marca de tiempo en la colocación
• Enlace CCTV — Clip opcional de cámara cercana
• Datos de báscula — Verificación de peso opcional

Tipos de Eventos

Modelo de Datos

Slots (Datos Maestros)

Ubicaciones de almacenamiento físico con geocercas poligonales:

Assets

Artículos que pueden ser colocados en slots:

Eventos de Colocación (Inmutables)

Cada evento registra: event_type, slot_id, asset_barcode, operator, timestamp, photo_url, scale_weight_kg, evidence_hash (SHA-256), y opcionalmente cctv_clip_url, work_order_ref y verification_notes.

Derivación del Estado Actual

Dado que el registro es inmutable, el estado actual se computa:

async function getSlotOccupancy(slotId: number) {
  const events = await queryEvents({
    slot_id: slotId,
    orderBy: 'timestamp',
    order: 'DESC',
  });

  const lastPlacement = events.find(
    (e) => e.event_type === 'PLACED' || e.event_type === 'REMOVED'
  );

  if (!lastPlacement || lastPlacement.event_type === 'REMOVED') {
    return { isOccupied: false, assetBarcode: null };
  }

  const isVerified = events.some(
    (e) => e.event_type === 'VERIFIED' && e.timestamp > lastPlacement.timestamp
  );

  return {
    isOccupied: true,
    assetBarcode: lastPlacement.asset_barcode,
    isVerified,
  };
}

Endpoints de API

Eventos

• POST /api/whms/events — Crear un evento de colocación
• GET /api/whms/events?slot_id=X&limit=50 — Consultar historial de eventos

Slots

• GET /api/whms/slots — Listar todos los slots
• GET /api/whms/slots/:id — Obtener slot con estado de ocupación computado
• POST /api/whms/slots — Crear un slot
• PUT /api/whms/slots/:id — Actualizar metadatos del slot

Assets

• GET /api/whms/assets — Listar todos los activos
• GET /api/whms/assets/:barcode/location — Obtener ubicación actual del activo

Dashboard

• GET /api/whms/dashboard/utilization — Porcentajes de utilización por zona

Editor de Planos de Planta

El editor de distribución usa Konva.js para dibujo de polígonos:

1. Subir una imagen de plano de planta
2. Dibujar polígonos para definir los límites de slots
3. Asignar IDs de slot, zonas y restricciones
4. Codificación de color por zona para claridad visual

Inventario de Componentes

El módulo WHMS está implementado a través de los siguientes componentes. Use estas rutas al importar o extender comportamiento.

Distribución y mapa

Escáner y colocación

Zonas y slots

Dashboard y utilización

Gamificación (opcional)

3D y paneles

Patrones de UI (sandboxes)

Los siguientes sandboxes ilustran los bloques de construcción de UI usados en las pantallas del WHMS. Los componentes reales usan las mismas primitivas (Card, Badge, Button, Progress, Tabs) más mapa/3D y datos de API.

Tarjeta de estado de slot

Estado de ocupación y verificación de un solo slot en vistas de lista o cuadrícula:

<Card className="max-w-xs">
  <CardHeader className="pb-2 flex flex-row items-center justify-between">
    <CardTitle className="text-sm font-medium">A-01-03</CardTitle>
    <Badge variant="secondary">Preparación</Badge>
  </CardHeader>
  <CardContent className="space-y-2">
    <p className="text-xs text-muted-foreground">Ocupado</p>
    <p className="text-sm font-mono">PLT-2024-00042</p>
    <div className="flex gap-2">
      <Badge variant="outline">Verificado</Badge>
      <Button size="sm" variant="ghost">Ver</Button>
    </div>
  </CardContent>
</Card>

Fila de utilización de zona

Una fila del widget de utilización (nombre de zona + barra de capacidad):

<div className="space-y-3 max-w-sm">
  <div className="flex justify-between text-sm">
    <span>Zona A — Almacenamiento</span>
    <span className="text-muted-foreground">72%</span>
  </div>
  <Progress value={72} className="h-2" />
  <div className="flex justify-between text-sm">
    <span>Zona B — Preparación</span>
    <span className="text-muted-foreground">24 / 32 slots</span>
  </div>
  <Progress value={75} className="h-2" />
</div>

Paso del flujo de colocación

Un paso individual en el asistente de colocación (escanear → foto → confirmar):

<Card className="max-w-sm">
  <CardHeader>
    <CardTitle className="text-base">Paso 2: Foto</CardTitle>
    <CardDescription>Capturar prueba de colocación en el slot</CardDescription>
  </CardHeader>
  <CardContent className="space-y-4">
    <div className="rounded-lg border border-dashed p-8 text-center text-sm text-muted-foreground">
      Vista previa de cámara o placeholder
    </div>
    <div className="flex gap-2">
      <Button className="flex-1">Capturar</Button>
      <Button variant="outline">Omitir</Button>
    </div>
  </CardContent>
</Card>

Pestañas de zona (vista detallada)

Pestañas usadas en detalle de zona (Slots, CCTV, Analítica, Incidentes):

<Tabs defaultValue="slots" className="max-w-md">
  <TabsList className="grid w-full grid-cols-4">
    <TabsTrigger value="slots">Slots</TabsTrigger>
    <TabsTrigger value="cctv">CCTV</TabsTrigger>
    <TabsTrigger value="analytics">Analítica</TabsTrigger>
    <TabsTrigger value="incidents">Incidentes</TabsTrigger>
  </TabsList>
  <TabsContent value="slots" className="p-4 border rounded-b-md">
    <p className="text-sm text-muted-foreground">Lista de slots con ocupación y acciones.</p>
  </TabsContent>
  <TabsContent value="cctv" className="p-4 border rounded-b-md">
    <p className="text-sm text-muted-foreground">Feeds de cámaras para esta zona.</p>
  </TabsContent>
  <TabsContent value="analytics" className="p-4 border rounded-b-md">
    <p className="text-sm text-muted-foreground">Gráficos y utilización.</p>
  </TabsContent>
  <TabsContent value="incidents" className="p-4 border rounded-b-md">
    <p className="text-sm text-muted-foreground">Incidentes y disputas.</p>
  </TabsContent>
</Tabs>

Elemento del feed de operaciones

Una línea en el feed de operaciones en vivo (eventos de colocación/remoción):

<div className="flex items-center gap-3 rounded-lg border p-3 max-w-md">
  <Badge>PLACED</Badge>
  <div className="flex-1 min-w-0">
    <p className="text-sm font-medium truncate">A-02-01 ← PLT-2024-00011</p>
    <p className="text-xs text-muted-foreground">Op. García · hace 2 min</p>
  </div>
  <Button size="sm" variant="ghost">Detalles</Button>
</div>

Relacionado

• Visión General de la Arquitectura
• Visualización de Mapas
• Módulo de Vigilancia
• Referencia de API REST
• Integración de Nextcloud Tables