@fiado/type-kit 3.262.0 → 3.265.0

package/src/retailCatalog/dtos/responses/InventoryLensResponse.ts

@@ -0,0 +1,123 @@
+import type { InventoryLensFilterEnum } from '../../enums/InventoryLensFilterEnum';
+import type { InventoryLensUnavailableReasonEnum } from '../../enums/InventoryLensUnavailableReasonEnum';
+import type { InventoryTransferReasonEnum } from '../../enums/InventoryTransferReasonEnum';
+
+/**
+ * Los contadores que la pantalla «Inventario» del Admin VL pinta arriba, siempre — los cuatro viajan
+ * con cualquier `filter`, porque las tarjetas no cambian al cambiar de tab.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ **No hay contador de `gap`.** El mockup pinta cinco tarjetas, pero la quinta compara contra las
+ * ventas de LUGA (INT6) y no se puede calcular. Se omite en vez de mandar un cero mentiroso.
+ */
+export interface InventoryLensCounters {
+    /** Unidades `AVAILABLE` del retailer, sumadas sobre todas las tiendas. */
+    totalStock: number;
+    /** SKUs distintos del catálogo del retailer — el subtítulo de la tarjeta de stock. */
+    distinctSkus: number;
+    /** Pares (SKU, tienda) en stock crítico. */
+    critical: number;
+    /** Pares (SKU, tienda) sin rotación o recién llegados sin venta. */
+    stale: number;
+    /** Traspasos sugeridos entre tiendas. */
+    transfers: number;
+}
+
+/**
+ * Una fila de los tabs `critical` y `stale`: un SKU **en una tienda concreta**. El mismo SKU aparece
+ * una vez por cada tienda donde vive, porque la acción (traspasar, promocionar) es por tienda.
+ */
+export interface InventoryLensSkuItem {
+    sku: string;
+    productId: string;
+    brand: string;
+    model: string;
+    capacity: string;
+    storeId: string;
+
+    /** Unidades `AVAILABLE` de este SKU en esta tienda. */
+    stock: number;
+
+    /**
+     * Días sin vender este SKU, medidos sobre **todo el retailer** (no por tienda) — es la definición
+     * del mockup, donde la rotación es un atributo del producto.
+     *
+     * Si el SKU nunca se vendió no hay `soldAt` del que restar: se cae a los días desde el ingreso más
+     * antiguo del SKU en el retailer, que es la cota inferior honesta de «cuánto lleva sin venderse».
+     */
+    rotationDays: number;
+
+    /** Días desde que este SKU entró a ESTA tienda (el lote más reciente). */
+    daysSinceArrival: number;
+    /** Fecha ISO-8601 de ese ingreso. */
+    arrivedAt: string;
+
+    /** El lote llegó hace menos de 7 días. */
+    recentArrival: boolean;
+    /** `rotationDays > 90`. */
+    noRotation90d: boolean;
+    /** No hubo ninguna venta del SKU posterior a su ingreso a esta tienda. */
+    noSaleSinceArrival: boolean;
+    /** `0 < stock < 3`. */
+    criticalStock: boolean;
+
+    /** Unidades de este SKU vendidas hoy en esta tienda, **financiadas por SureKeep**. */
+    soldTodayUnits: number;
+
+    /** Precio de contado en centavos (`listPriceCents`, o `basePriceCents` si no hay lista). */
+    cashPriceCents: number;
+}
+
+/** Una fila del tab `transfers`: mover unidades de un SKU de una tienda con excedente a una en crítico. */
+export interface InventoryLensTransferSuggestion {
+    sku: string;
+    productId: string;
+    brand: string;
+    model: string;
+
+    /** Tienda con excedente (≥ 5 unidades del SKU). */
+    fromStoreId: string;
+    fromStoreStock: number;
+    /** Tienda en stock crítico. */
+    toStoreId: string;
+    toStoreStock: number;
+
+    /** Unidades sugeridas: `min(floor(fromStoreStock / 3), 3)`. */
+    units: number;
+    reason: InventoryTransferReasonEnum;
+}
+
+/** Fila del lente — el tipo depende del tab pedido. */
+export type InventoryLensItem = InventoryLensSkuItem | InventoryLensTransferSuggestion;
+
+/**
+ * `GET /backoffice/inventory/lens?filter=…` — la pantalla «Inventario» del Portal Admin VentasLuga.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Es una **lente, no un clon** (D11): se sirve de solo lectura sobre el inventario propio y ninguna
+ * acción de la pantalla muta nada — los botones son deep links al ERP de LUGA. El inventario lo mueve
+ * La Central, no SureKeep.
+ *
+ * `counters` viaja siempre, con cualquier `filter`. `items` trae el tab pedido.
+ */
+export interface InventoryLensResponse {
+    /** El tab que se resolvió — eco del query, para que el front no se confunda de pestaña. */
+    filter: InventoryLensFilterEnum;
+
+    counters: InventoryLensCounters;
+
+    /** Filas del tab. Vacío cuando `unavailable` es `true`. */
+    items: InventoryLensItem[];
+
+    /**
+     * `true` cuando el tab **no se puede calcular** (hoy solo `filter=gap`).
+     *
+     * ⚠️ El front DEBE distinguirlo de una lista vacía normal: `unavailable: true` significa «este
+     * comparativo necesita la integración con La Central», no «no hay gap». Pintar un cero acá sería
+     * dar por buena una medición que nunca se hizo.
+     */
+    unavailable?: boolean;
+
+    /** Por qué no se pudo. Presente solo junto a `unavailable: true`. */
+    reason?: InventoryLensUnavailableReasonEnum;
+}

package/src/retailCatalog/enums/InventoryLensFilterEnum.ts

@@ -0,0 +1,21 @@
+/**
+ * Los cuatro tabs de la pantalla «Inventario» del Portal Admin VentasLuga (B-INV).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El valor viaja como query string en `GET /backoffice/inventory/lens?filter=…`, así que son las
+ * cadenas literales del mockup, no SCREAMING_CASE.
+ *
+ * ⚠️ `GAP` está en el contrato pero **no se puede calcular**: compara las ventas de LUGA contra las
+ * que financia SureKeep, y el lado LUGA llega por La Central (INT6), cuyo spec todavía no existe.
+ * El endpoint lo acepta y responde con `unavailable: true` — ver `InventoryLensResponse`.
+ */
+export enum InventoryLensFilterEnum {
+    /** SKUs con stock por agotarse en una tienda. */
+    CRITICAL = 'critical',
+    /** SKUs sin rotación, o recién llegados que todavía no venden. */
+    STALE = 'stale',
+    /** Top vendidos en LUGA que SureKeep no financia. **No disponible** (INT6). */
+    GAP = 'gap',
+    /** Desbalance de stock del mismo SKU entre tiendas. */
+    TRANSFERS = 'transfers',
+}

package/src/retailCatalog/enums/InventoryLensUnavailableReasonEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Por qué un tab del lente de inventario no se puede calcular. SureKeep Fase 3 — pista Retail.
+ *
+ * Existe para que el front distinga **«no lo puedo calcular»** de **«calculé y dio cero»**. Un tab
+ * que no se puede servir viaja con `items: []` + `unavailable: true` + este motivo; sin él, el cero
+ * se leería como un dato bueno y la pantalla mentiría.
+ */
+export enum InventoryLensUnavailableReasonEnum {
+    /**
+     * El tab necesita las ventas de LUGA, que llegan por La Central (INT6). La integración no está
+     * especificada todavía, así que el dato no existe — no es que valga cero.
+     */
+    INT6_NOT_AVAILABLE = 'INT6_NOT_AVAILABLE',
+}

package/src/retailCatalog/enums/InventoryTransferReasonEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Motivo por el que el lente sugiere mover unidades de una tienda a otra. SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ El mockup rotula el motivo como «Stock crítico + demanda hoy», pero la **demanda** sale de las
+ * ventas de LUGA (INT6, no disponible). Acá solo se declara la mitad que sí se puede probar con
+ * datos propios: la tienda destino está en crítico y hay otra con excedente del mismo SKU.
+ */
+export enum InventoryTransferReasonEnum {
+    /** El destino tiene stock crítico y el origen tiene excedente del mismo SKU. */
+    CRITICAL_STOCK_AT_DESTINATION = 'CRITICAL_STOCK_AT_DESTINATION',
+}

package/src/retailCatalog/index.ts

@@ -4,6 +4,11 @@ export * from './enums/InventoryItemStatusEnum';
 export * from './enums/MdmProviderEnum';
 export * from './enums/MdmLockModeEnum';
 
+// F3 — lente de inventario del Portal Admin VentasLuga
+export * from './enums/InventoryLensFilterEnum';
+export * from './enums/InventoryLensUnavailableReasonEnum';
+export * from './enums/InventoryTransferReasonEnum';
+
 // Constantes del dominio
 export * from './constants/SkuPattern';
 
@@ -22,12 +27,14 @@ export * from './dtos/requests/ListProductsQuery';
 export * from './dtos/requests/RegisterInventoryRequest';
 export * from './dtos/requests/TransferInventoryRequest';
 export * from './dtos/requests/ChangeInventoryStatusRequest';
+export * from './dtos/requests/InventoryLensQuery';
 
 // Response DTOs
 export * from './dtos/responses/ProductResponse';
 export * from './dtos/responses/InventoryItemResponse';
 export * from './dtos/responses/ImportCsvFailure';
 export * from './dtos/responses/ImportCsvResult';
+export * from './dtos/responses/InventoryLensResponse';
 
 // Validation DTOs (shapes de endpoints privados)
 export * from './dtos/validation/ValidateProductResponse';

package/src/retailWizard/events/SaleCancelledV2.ts

@@ -0,0 +1,20 @@
+/**
+ * Emitido al cancelar una venta, en la MISMA `TransactWriteItems` de la cancelación.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * **La V1 NO se toca** (tiene consumers en producción). La V2 se emite además y es la que consume el
+ * motor de comisiones, que necesita el `sellerRetailUserId` para saber a QUIÉN revertirle la comisión
+ * y el `soldAt` para saber en qué CORTE se había liquidado.
+ *
+ * ⚠️ `tenantId` NO va en el payload: viaja en el sobre del outbox.
+ */
+export interface SaleCancelledV2 {
+    saleId: string;
+    /** A quién se le revierte la comisión. */
+    sellerRetailUserId: string;
+    /** Fecha de la venta ORIGINAL — identifica el corte en el que se había liquidado. */
+    soldAt: string;
+    reason: string;
+    cancelledAt: string;
+    occurredAt: string;
+}

package/src/retailWizard/events/SaleCompletedV2.ts

@@ -0,0 +1,42 @@
+import type { SaleTypeEnum } from '../enums/SaleTypeEnum';
+import type { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
+
+/**
+ * Emitido al cerrar una venta, en la MISMA `TransactWriteItems` del cierre (patrón Outbox).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * **La V1 NO se toca:** ya tiene consumers en producción (La Central, datalake). La V2 se emite
+ * ADEMÁS, en la misma transacción, y es la que consume el motor de comisiones — que necesita saber
+ * QUIÉN vendió (`sellerRetailUserId`), CÓMO se financió (`type` + `externalProvider`) y de qué MARCA
+ * era el equipo (`brand`), tres datos que la V1 no lleva.
+ *
+ * ⚠️ `tenantId` NO va en el payload: ya viaja en el sobre del outbox (`OutboxEventPublisher`).
+ * Duplicarlo abriría la puerta a que los dos discrepen.
+ *
+ * ⚠️ NO hay `lines[]`: una `RetailSale` es de UN solo producto (D16) y se comisiona la venta, no un
+ * renglón. Modelarlo como array sugeriría un carrito que el wizard no tiene.
+ */
+export interface SaleCompletedV2 {
+    saleId: string;
+    folio: string;
+    retailerId: string;
+    storeId: string;
+    /** Quién vendió — el eje del cálculo de comisión. Es lo que más falta en la V1. */
+    sellerRetailUserId: string;
+    retailCustomerId: string;
+    sku: string;
+    /** Marca del equipo, del snapshot congelado al cerrar. `null` si no se pudo resolver. */
+    brand: string | null;
+    imei: string | null;
+    /** Lo COBRADO en caja. En contado == precio del equipo; en CREDIT es SOLO el enganche. */
+    amountCents: number;
+    /** Precio de lista del equipo — la base de comisión. `null` en ventas sin el dato. */
+    equipmentPriceCents: number | null;
+    downPaymentCents: number | null;
+    creditId: string | null;
+    type: SaleTypeEnum;
+    /** Proveedor externo cuando `type = EXTERNAL_REFERRAL`; `null` en contado y crédito propio. */
+    externalProvider: ExternalProviderEnum | null;
+    soldAt: string;
+    occurredAt: string;
+}

package/src/retailWizard/index.ts

@@ -116,4 +116,6 @@ export * from './dtos/responses/BackofficeReportsResponse';
 // Contratos de eventos (PascalCase + sufijo V1)
 export * from './events/SaleCompletedV1';
 export * from './events/SaleCancelledV1';
+export * from './events/SaleCompletedV2';
+export * from './events/SaleCancelledV2';
 export * from './events/SessionExpiredV1';