@fiado/type-kit 3.259.0 → 3.261.0

package/src/retailWizard/dtos/SaleException.ts

@@ -0,0 +1,55 @@
+import type { SaleExceptionTypeEnum } from '../enums/SaleExceptionTypeEnum';
+import type { SaleExceptionStatusEnum } from '../enums/SaleExceptionStatusEnum';
+import type { SaleExceptionEvent } from './SaleExceptionEvent';
+import type { SaleExceptionPayload } from './SaleExceptionPayload';
+
+/**
+ * Excepción de venta (`<T>RetailSaleException_GT`, pk `RETAILER#<retailerId>` ·
+ * sk `EXCEPTION#<createdAt>#<exceptionId>`, CERO GSIs). Bandeja del Admin VL, M6 §5.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El `status` NO va en el sort key: el sk es inmutable en DynamoDB y el estado recorre
+ * `NEW → IN_REVIEW → APPROVED → APPLIED`. Meterlo ahí obligaría a borrar y reescribir el ítem en cada
+ * transición, perdiendo atomicidad y estabilidad del `exceptionId`. El filtro por estado se hace en
+ * memoria; son eventos raros.
+ *
+ * 🔴 **Hueco declarado (DEC-034):** `CAPTURE_FIX`, `BACKDATING` y `PRICE_OVERRIDE` mutan la venta
+ * después de cerrada, y el motor de comisiones solo escucha `SaleCompleted` / `SaleCancelled`. En el
+ * primer corte las excepciones **NO re-liquidan comisión**. Se ataca en F4 con un `SaleAmendedV1`.
+ */
+export interface SaleException {
+    exceptionId: string;
+    retailerId: string;
+    storeId: string;
+    /** `null` en las excepciones generales, que no cuelgan de una venta puntual. */
+    saleId: string | null;
+    type: SaleExceptionTypeEnum;
+    status: SaleExceptionStatusEnum;
+    /** userId de quien la levantó (normalmente el vendedor). */
+    requestedBy: string;
+    /** Nombre para mostrar, congelado al alta. `null` si no se pudo resolver. */
+    requestedByName: string | null;
+    /** ISO-8601. */
+    requestedAt: string;
+    /** OBLIGATORIA. Es lo que hace auditable la excepción. */
+    justification: string;
+    /**
+     * Impacto económico en centavos, con signo: positivo si la excepción suma (devolución al cliente,
+     * reemplazo), negativo si resta (descuento autorizado). `null` cuando no aplica.
+     */
+    impactCents: number | null;
+    payload: SaleExceptionPayload;
+    /** userId del Admin VL que aprobó o rechazó. `null` mientras esté sin resolver. */
+    resolvedBy: string | null;
+    resolvedByName: string | null;
+    /** ISO-8601. `null` mientras esté sin resolver. */
+    resolvedAt: string | null;
+    /** Resolución OBLIGATORIA al aprobar o rechazar. `null` mientras esté sin resolver. */
+    resolution: string | null;
+    /** Hilo de solicitud, notas y resolución, en orden cronológico ascendente. */
+    timeline: SaleExceptionEvent[];
+    createdBy: string;
+    updatedBy: string;
+    createdAt: number;
+    updatedAt: number;
+}

package/src/retailWizard/dtos/SaleExceptionEvent.ts

@@ -0,0 +1,19 @@
+import type { SaleExceptionEventKindEnum } from '../enums/SaleExceptionEventKindEnum';
+
+/**
+ * Una entrada del timeline de una excepción: el hilo de solicitud, notas y resolución que la pantalla
+ * de Excepciones dibuja bajo la ficha. SureKeep Fase 3 — pista Retail.
+ *
+ * Va EMBEBIDO en el ítem de `RetailSaleException_GT`, no en una tabla aparte: son pocos eventos por
+ * excepción, se leen siempre junto con la ficha y nunca se consultan por su cuenta.
+ */
+export interface SaleExceptionEvent {
+    /** ISO-8601. */
+    at: string;
+    kind: SaleExceptionEventKindEnum;
+    /** userId del autor; `system` si lo escribió un proceso interno. */
+    authorId: string;
+    /** Nombre para mostrar, congelado al escribir el evento. `null` si no se pudo resolver. */
+    authorName: string | null;
+    body: string;
+}

package/src/retailWizard/dtos/SaleExceptionPayload.ts

@@ -0,0 +1,19 @@
+/**
+ * Lo que la excepción PIDE cambiar en la venta. Todos los campos son opcionales porque cada tipo usa
+ * los suyos: `CAPTURE_FIX` manda `sku`, `PRICE_OVERRIDE` manda `amountCents`, `BACKDATING` manda
+ * `soldAt`, `EXTENDED_WARRANTY` manda `imei`. `LATE_CANCEL` no manda ninguno.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Es un shape TIPADO y no un objeto libre a propósito: el payload cruza el borde HTTP y un
+ * `Record<string, unknown>` ahí deja al front sin contrato y al validador sin nada que validar.
+ */
+export interface SaleExceptionPayload {
+    /** SKU correcto (CAPTURE_FIX). */
+    sku?: string;
+    /** Monto correcto en centavos (PRICE_OVERRIDE, CAPTURE_FIX). */
+    amountCents?: number;
+    /** Fecha real de la venta, ISO-8601 (BACKDATING). */
+    soldAt?: string;
+    /** IMEI del equipo de reemplazo (EXTENDED_WARRANTY). */
+    imei?: string;
+}

package/src/retailWizard/dtos/SaleLogEntry.ts

@@ -0,0 +1,30 @@
+/** Un campo que cambió en una acción auditada. `from` ausente en un alta. */
+export interface SaleLogChange {
+    field: string;
+    from: string | null;
+    to: string | null;
+}
+
+/**
+ * Una entrada del tab «Bitácora» del drawer de una venta. Proyección de `SharedAuditTrail_GT`
+ * (`pk = ENTITY#SALE#<saleId>`, `sk = TS#<iso>#<ulid>`, orden cronológico nativo).
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * El diff viaja APLANADO en `changes` y no como los objetos `old`/`new` crudos de la tabla: la
+ * pantalla dibuja una lista de «campo: antes → después», y un objeto libre en el contrato obligaría al
+ * front a adivinar la forma. Los valores se serializan a string por eso mismo.
+ *
+ * ⚠️ `changes` NUNCA lleva PII: la tabla de auditoría solo guarda identificadores y valores
+ * operacionales (status, storeId, type…). Ver `fiado-logging`.
+ */
+export interface SaleLogEntry {
+    /** ISO-8601 del momento de la acción (sale del `sk`). */
+    at: string;
+    /** Acción auditada: `SALE_COMPLETE`, `SALE_CANCEL`, `PAYMENT_REGISTERED`… */
+    action: string;
+    /** Actor: userId del AuthContext, o `system` si la disparó un proceso interno. */
+    performedBy: string;
+    /** Motivo, cuando la acción lo exige (cancelación, excepción aplicada). */
+    reason: string | null;
+    changes: SaleLogChange[];
+}

package/src/retailWizard/dtos/SalesReportDefinition.ts

@@ -0,0 +1,21 @@
+import type { SalesReportIdEnum } from '../enums/SalesReportIdEnum';
+import type { ReportPeriodicityEnum } from '../enums/ReportPeriodicityEnum';
+import type { ReportFormatEnum } from '../enums/ReportFormatEnum';
+
+/**
+ * Un reporte del catálogo del Admin VL (M6 §5.1). Es CONFIGURACIÓN, no una fila de tabla: el catálogo
+ * de los 5 reportes vive en código y no se persiste — cambia con un deploy, no con un write.
+ * SureKeep Fase 3 — pista Retail.
+ */
+export interface SalesReportDefinition {
+    reportId: SalesReportIdEnum;
+    /** Nombre para mostrar, en español mexicano. */
+    name: string;
+    description: string;
+    periodicity: ReportPeriodicityEnum;
+    formats: ReportFormatEnum[];
+    /** Referencia al documento de negocio que lo define (ej. `M6 §5.1`). */
+    reference: string;
+    /** ISO-8601 de la última corrida conocida; `null` si nunca corrió. */
+    lastRunAt: string | null;
+}

package/src/retailWizard/dtos/SalesReportRun.ts

@@ -0,0 +1,40 @@
+import type { SalesReportIdEnum } from '../enums/SalesReportIdEnum';
+import type { ReportFormatEnum } from '../enums/ReportFormatEnum';
+import type { ReportRunStatusEnum } from '../enums/ReportRunStatusEnum';
+
+/**
+ * Una corrida de reporte (`<T>RetailReportRun_GT`, pk `RETAILER#<retailerId>` ·
+ * sk `RUN#<requestedAt>#<runId>`, CERO GSIs). Es el log de la sección 3 de la pantalla de Reportes.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * La generación es ASÍNCRONA: el `POST .../run` persiste la corrida en `QUEUED` y devuelve el `runId`;
+ * el front poletea `GET /backoffice/reports`. API Gateway corta a los 29 s y un reporte de red
+ * completa no entra en una respuesta síncrona.
+ */
+export interface SalesReportRun {
+    runId: string;
+    retailerId: string;
+    reportId: SalesReportIdEnum;
+    format: ReportFormatEnum;
+    status: ReportRunStatusEnum;
+    /** userId de quien la disparó; `system` si la lanzó el cron. */
+    requestedBy: string;
+    requestedByName: string | null;
+    /** ISO-8601. Es parte del sort key: ordena el log de corridas. */
+    requestedAt: string;
+    /** ISO-8601 del fin de la generación. `null` mientras no termine. */
+    completedAt: string | null;
+    /** Ventana de datos del reporte, ISO-8601. */
+    periodFrom: string | null;
+    periodTo: string | null;
+    /** Filas generadas. `null` mientras no termine. */
+    rowCount: number | null;
+    /** URL prefirmada de descarga. Solo con `status: READY`; `null` en cualquier otro estado. */
+    downloadUrl: string | null;
+    /** Por qué falló. Solo con `status: FAILED`. */
+    failureReason: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: number;
+    updatedAt: number;
+}

package/src/retailWizard/dtos/requests/BackofficeCancelSaleRequest.ts

@@ -0,0 +1,42 @@
+import { Expose } from 'class-transformer';
+import { IsBoolean, IsOptional, IsString, MaxLength, MinLength } from 'class-validator';
+
+/**
+ * POST /backoffice/sales/:saleId/cancel — cancelación del Admin VL. SureKeep Fase 3 — pista Retail.
+ *
+ * Es un endpoint SEPARADO de `POST /sales/:saleId/cancel` (el del vendedor), no una rama del mismo, y
+ * por eso lleva su propio DTO. Son dos reglas de negocio distintas: la del vendedor está acotada a su
+ * propia venta y a la ventana de 7 días; la del admin puede cancelar FUERA de ventana — que es justo
+ * lo que habilita la excepción `LATE_CANCEL`. Mezclarlas en un handler enredaría las dos.
+ *
+ * `outOfWindowExceptionId` es el puente entre las dos piezas: cancelar fuera de ventana exige una
+ * excepción `LATE_CANCEL` ya aprobada. Sin ella el manager rechaza, aunque el actor tenga el permiso.
+ */
+export class BackofficeCancelSaleRequest {
+    @Expose()
+    @IsString()
+    @MinLength(10)
+    @MaxLength(200)
+    reason!: string;
+
+    /**
+     * Confirmación de que el equipo se verificó físicamente en tienda. Ausente y `false` se tratan
+     * igual (fail-closed): el manager responde `412 IMEI_NOT_RETURNABLE`, que es la respuesta
+     * semánticamente correcta y no un error de forma. `@IsBoolean()` estricto — el string `"false"` se
+     * rechaza en vez de colarse como truthy.
+     */
+    @Expose()
+    @IsOptional()
+    @IsBoolean()
+    equipmentVerified?: boolean;
+
+    /**
+     * Excepción `LATE_CANCEL` aprobada que autoriza cancelar fuera de la ventana. Solo se exige cuando
+     * la venta YA está fuera de ventana; dentro de ventana se ignora.
+     */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    outOfWindowExceptionId?: string;
+}

package/src/retailWizard/dtos/requests/CreateSaleExceptionRequest.ts

@@ -0,0 +1,84 @@
+import { Expose, Type } from 'class-transformer';
+import {
+    IsEnum,
+    IsInt,
+    IsISO8601,
+    IsOptional,
+    IsString,
+    MaxLength,
+    MinLength,
+    ValidateNested,
+} from 'class-validator';
+import { SaleExceptionTypeEnum } from '../../enums/SaleExceptionTypeEnum';
+
+/** Lo que la excepción pide cambiar. Cada tipo usa los campos que le tocan; todos son opcionales. */
+export class SaleExceptionPayloadInput {
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    sku?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    amountCents?: number;
+
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    soldAt?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(20)
+    imei?: string;
+}
+
+/**
+ * POST /backoffice/exceptions — levanta una excepción sobre una venta. SureKeep Fase 3 — pista Retail.
+ *
+ * La `justification` es OBLIGATORIA y con mínimo real: es lo único que vuelve auditable la excepción,
+ * y un campo libre que acepta `"x"` no audita nada. Escribe `RetailSaleException_GT` +
+ * `SharedAuditTrail_GT` en la MISMA `TransactWriteItems`.
+ *
+ * El `retailerId` NO viaja en el request: sale del token (`scopeFromRetailer`).
+ */
+export class CreateSaleExceptionRequest {
+    @Expose()
+    @IsEnum(SaleExceptionTypeEnum)
+    type!: SaleExceptionTypeEnum;
+
+    /** `null`/ausente en las excepciones generales, que no cuelgan de una venta puntual. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    saleId?: string;
+
+    /** Obligatorio cuando NO hay `saleId`; si hay venta, se toma el de la venta. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    storeId?: string;
+
+    @Expose()
+    @IsString()
+    @MinLength(20)
+    @MaxLength(1000)
+    justification!: string;
+
+    /** Impacto económico con signo, en centavos. Negativo si la excepción resta (descuento). */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    impactCents?: number;
+
+    @Expose()
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => SaleExceptionPayloadInput)
+    payload?: SaleExceptionPayloadInput;
+}

package/src/retailWizard/dtos/requests/ResolveSaleExceptionRequest.ts

@@ -0,0 +1,25 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsString, MaxLength, MinLength } from 'class-validator';
+import { SaleExceptionDecisionEnum } from '../../enums/SaleExceptionDecisionEnum';
+
+/**
+ * POST /backoffice/exceptions/:exceptionId/resolve — aprueba o rechaza una excepción.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * La `resolution` es OBLIGATORIA en los dos veredictos, no solo al rechazar: un «aprobada» sin motivo
+ * escrito es exactamente el registro que después nadie puede defender ante una auditoría.
+ *
+ * **Idempotente** con el guard local (`IIdempotencyGuard` + `SureKeepSharedIdempotency_GT`): un doble
+ * click no puede resolver dos veces. ⚠️ El decorador `@Idempotent` NO existe en el gateway-adapter.
+ */
+export class ResolveSaleExceptionRequest {
+    @Expose()
+    @IsEnum(SaleExceptionDecisionEnum)
+    decision!: SaleExceptionDecisionEnum;
+
+    @Expose()
+    @IsString()
+    @MinLength(10)
+    @MaxLength(1000)
+    resolution!: string;
+}

package/src/retailWizard/dtos/requests/RunSalesReportRequest.ts

@@ -0,0 +1,31 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsISO8601, IsOptional } from 'class-validator';
+import { ReportFormatEnum } from '../../enums/ReportFormatEnum';
+
+/**
+ * POST /backoffice/reports/:reportId/run — encola la generación de un reporte.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * Devuelve el `SalesReportRun` en `QUEUED`, NO el archivo: la generación es asíncrona por el límite de
+ * 29 s de API Gateway. El front poletea `GET /backoffice/reports` hasta ver `READY` y ahí usa el
+ * `downloadUrl`.
+ *
+ * El `reportId` viaja en el path, no acá. El `retailerId` sale del token.
+ */
+export class RunSalesReportRequest {
+    @Expose()
+    @IsEnum(ReportFormatEnum)
+    format!: ReportFormatEnum;
+
+    /** Inicio de la ventana de datos, ISO-8601. Si falta, la resuelve la periodicidad del reporte. */
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    periodFrom?: string;
+
+    /** Fin de la ventana de datos, ISO-8601. Si falta, la resuelve la periodicidad del reporte. */
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    periodTo?: string;
+}

package/src/retailWizard/dtos/responses/BackofficeReportsResponse.ts

@@ -0,0 +1,15 @@
+import type { SalesReportDefinition } from '../SalesReportDefinition';
+import type { SalesReportRun } from '../SalesReportRun';
+
+/**
+ * GET /backoffice/reports — el catálogo de los 5 reportes de ventas MÁS el log de corridas recientes,
+ * que es exactamente lo que la pantalla dibuja en sus dos secciones. SureKeep Fase 3 — pista Retail.
+ *
+ * Van juntos en una sola respuesta y no en dos endpoints porque la pantalla siempre necesita los dos,
+ * y el catálogo son 5 ítems de configuración en código: partirlo costaría un round-trip para nada.
+ */
+export interface BackofficeReportsResponse {
+    definitions: SalesReportDefinition[];
+    /** Últimas corridas del retailer, más recientes primero. */
+    runs: SalesReportRun[];
+}

package/src/retailWizard/dtos/responses/BackofficeSalesKpisResponse.ts

@@ -0,0 +1,34 @@
+import type { SaleFinancierEnum } from '../../enums/SaleFinancierEnum';
+
+/** Un tramo del mix por financiera del Home del Admin VL. */
+export interface SalesFinancierMixEntry {
+    financier: SaleFinancierEnum;
+    count: number;
+    amountCents: number;
+}
+
+/**
+ * GET /backoffice/sales/kpis — los KPIs del Home del Admin VL. SureKeep Fase 3 — pista Retail.
+ *
+ * 🟡 **Incompleto por diseño:** el panel «Meta del día» necesita las metas por tienda, que viven en
+ * `retail-org-business` y **todavía no existen**. `goal` viaja `null` hasta entonces; todo lo demás
+ * son datos reales. El front debe tratar `null` como «sin meta configurada», no como cero.
+ *
+ * Las llaves van en inglés (el diseño no fija un payload literal acá, a diferencia de
+ * `BackofficeSalesStatsResponse`).
+ */
+export interface BackofficeSalesKpisResponse {
+    /** Monto colocado hoy, en centavos. Mide precio del equipo, no lo cobrado en caja (DEC-032). */
+    soldTodayCents: number;
+    /** Piezas vendidas hoy. */
+    unitsToday: number;
+    /** Ticket promedio de hoy, en centavos. 0 si no hubo ventas. */
+    averageTicketCents: number;
+    /** Delta porcentual del monto de hoy contra ayer. `null` si ayer no hubo ventas (no se divide por cero). */
+    deltaVsYesterdayPct: number | null;
+    /** Monto del MISMO día de la semana pasada, en centavos — el baseline honesto contra la estacionalidad. */
+    baselineSameWeekdayCents: number;
+    mix: SalesFinancierMixEntry[];
+    /** Meta del día del retailer, en centavos. `null` mientras no exista la tabla de metas. */
+    goalCents: number | null;
+}

package/src/retailWizard/dtos/responses/BackofficeSalesStatsResponse.ts

@@ -0,0 +1,26 @@
+/**
+ * GET /backoffice/sales/stats — los pills de conteo arriba de la tabla de Ventas del Admin VL.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * ⚠️ **Las llaves van en ESPAÑOL, a propósito y como única excepción del dominio.** Es el contrato
+ * literal que fija el diseño de F3 (`03_backoffice_ventasluga/lambdas/retail-wizard-business.md`) y
+ * contra el que el front ya mockeó la pantalla. Cambiarlas a inglés por consistencia rompería una
+ * pantalla ya construida sin ganar nada. Decisión de Andrés, 2026-08-03.
+ *
+ * `contado` + `credito` == `total`. `surekeep` + `externas` == `credito`: las dos particiones son
+ * completas y NO se solapan (ver `helpers/saleFinancier`).
+ */
+export interface BackofficeSalesStatsResponse {
+    /** Ventas del retailer en la ventana consultada. */
+    total: number;
+    /** Subconjunto de `total` con `soldAt` en el día de hoy. */
+    hoy: number;
+    /** `type: CASH`. */
+    contado: number;
+    /** `type: CREDIT` o `EXTERNAL_REFERRAL` — todo lo que no es contado. */
+    credito: number;
+    /** Financiadas por la SOFOM (`type: CREDIT`). */
+    surekeep: number;
+    /** Financiadas por un tercero (`EXTERNAL_REFERRAL` con proveedor). */
+    externas: number;
+}

package/src/retailWizard/enums/ReportFormatEnum.ts

@@ -0,0 +1,5 @@
+/** Formato de salida de un reporte del Admin VL. SureKeep Fase 3 — pista Retail. */
+export enum ReportFormatEnum {
+    CSV = 'CSV',
+    PDF = 'PDF',
+}

package/src/retailWizard/enums/ReportPeriodicityEnum.ts

@@ -0,0 +1,9 @@
+/**
+ * Periodicidad de un reporte del Admin VL. Los diarios y semanales corren por cron; los mensuales
+ * requieren corrida manual (M6 §5.1). SureKeep Fase 3 — pista Retail.
+ */
+export enum ReportPeriodicityEnum {
+    DAILY = 'DAILY',
+    WEEKLY = 'WEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailWizard/enums/ReportRunStatusEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado de una corrida de reporte. La generación es ASÍNCRONA: el `POST .../run` devuelve `QUEUED` y
+ * el front poletea el listado. SureKeep Fase 3 — pista Retail.
+ *
+ * Es async desde el día uno por el límite de 29 s de API Gateway: un reporte de red completa no entra
+ * en una respuesta síncrona. Mismo error que ya se corrigió en el cierre de corte de comisiones.
+ *
+ * QUEUED - Encolada, sin arrancar.
+ * RUNNING - Generándose.
+ * READY - Lista para descargar (`downloadUrl` presente).
+ * FAILED - Falló; `failureReason` explica por qué.
+ */
+export enum ReportRunStatusEnum {
+    QUEUED = 'QUEUED',
+    RUNNING = 'RUNNING',
+    READY = 'READY',
+    FAILED = 'FAILED',
+}

package/src/retailWizard/enums/SaleExceptionDecisionEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Veredicto del Admin VL al resolver una excepción. Es un enum PROPIO y no un subconjunto de
+ * `SaleExceptionStatusEnum`: el request expresa una DECISIÓN («apruébala»), no un estado destino, y
+ * mezclarlos dejaría al caller mandar `APPLIED` o `NEW` en un endpoint que no los admite.
+ * SureKeep Fase 3 — pista Retail.
+ */
+export enum SaleExceptionDecisionEnum {
+    APPROVE = 'APPROVE',
+    REJECT = 'REJECT',
+}

package/src/retailWizard/enums/SaleExceptionEventKindEnum.ts

@@ -0,0 +1,17 @@
+/**
+ * Tipo de entrada del timeline de una excepción (la conversación que la pantalla de Excepciones
+ * dibuja bajo la ficha). SureKeep Fase 3 — pista Retail.
+ *
+ * REQUEST - El alta: quién la levantó y por qué.
+ * NOTE - Nota de seguimiento (pide evidencia, deja contexto).
+ * APPROVAL - Queda aprobada.
+ * REJECTION - Queda rechazada.
+ * APPLIED - El cambio ya se aplicó al sistema.
+ */
+export enum SaleExceptionEventKindEnum {
+    REQUEST = 'REQUEST',
+    NOTE = 'NOTE',
+    APPROVAL = 'APPROVAL',
+    REJECTION = 'REJECTION',
+    APPLIED = 'APPLIED',
+}

package/src/retailWizard/enums/SaleExceptionStatusEnum.ts

@@ -0,0 +1,19 @@
+/**
+ * Estado de una excepción de venta. SureKeep Fase 3 — pista Retail.
+ *
+ * NEW - Levantada por el vendedor, sin tomar.
+ * IN_REVIEW - El Admin VL la está revisando.
+ * APPROVED - Aprobada; falta aplicar el cambio a la venta.
+ * APPLIED - Aprobada Y aplicada.
+ * REJECTED - Rechazada, con resolución obligatoria.
+ *
+ * ⚠️ El estado NO va en el sort key de `RetailSaleException_GT`: el sk es inmutable en DynamoDB y esto
+ * cambia en todo el ciclo. El filtro por estado se hace en memoria (son eventos raros).
+ */
+export enum SaleExceptionStatusEnum {
+    NEW = 'NEW',
+    IN_REVIEW = 'IN_REVIEW',
+    APPROVED = 'APPROVED',
+    APPLIED = 'APPLIED',
+    REJECTED = 'REJECTED',
+}

package/src/retailWizard/enums/SaleExceptionTypeEnum.ts

@@ -0,0 +1,19 @@
+/**
+ * Tipo de excepción de venta (bandeja del Admin VL, M6 §5). SureKeep Fase 3 — pista Retail.
+ *
+ * CAPTURE_FIX - Corrección de captura: el POS registró un modelo/SKU distinto al vendido.
+ * LATE_CANCEL - Cancelación fuera de la ventana de 7 días.
+ * BACKDATING - Venta física ejecutada antes de su captura; se pide la fecha real.
+ * PRICE_OVERRIDE - Descuento o precio fuera de lista, autorizado por el Admin VL.
+ * EXTENDED_WARRANTY - Reemplazo de equipo bajo garantía extendida contratada en la venta.
+ *
+ * ⚠️ NO existe `AUTHORIZATION_CAP` (el `autorizacion_tope` del mockup): su dato es de conciliación,
+ * que es cobranza (D1), no retail. La fila del mockup no tiene backend en F3.
+ */
+export enum SaleExceptionTypeEnum {
+    CAPTURE_FIX = 'CAPTURE_FIX',
+    LATE_CANCEL = 'LATE_CANCEL',
+    BACKDATING = 'BACKDATING',
+    PRICE_OVERRIDE = 'PRICE_OVERRIDE',
+    EXTENDED_WARRANTY = 'EXTENDED_WARRANTY',
+}

package/src/retailWizard/enums/SaleFinancierEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Financiera de la venta, DERIVADA — no es un campo de `RetailSale_GT`. Sale de `type` +
+ * `externalProvider` (ver `helpers/saleFinancier`). Existe porque las pantallas del Admin VL agrupan
+ * por financiera y el front, este lambda y el motor de comisiones tienen que derivarla IGUAL.
+ * SureKeep Fase 3 — pista Retail.
+ *
+ * NONE - Venta de contado: no hay financiera.
+ * SUREKEEP - Crédito propio de la SOFOM.
+ * PAYJOY / CREDIYA / LESPAGO / INNOVA - Derivada a un proveedor externo.
+ */
+export enum SaleFinancierEnum {
+    NONE = 'NONE',
+    SUREKEEP = 'SUREKEEP',
+    PAYJOY = 'PAYJOY',
+    CREDIYA = 'CREDIYA',
+    LESPAGO = 'LESPAGO',
+    INNOVA = 'INNOVA',
+}

package/src/retailWizard/enums/SalesReportIdEnum.ts

@@ -0,0 +1,19 @@
+/**
+ * Catálogo de reportes de ventas del Admin VL (M6 §5.1). Los ids son los del mockup — el front los usa
+ * como llave de ruta y de traducción. SureKeep Fase 3 — pista Retail.
+ *
+ * RVL_01 - Ventas por período (diaria).
+ * RVL_02 - Ventas por negocio · tienda (semanal).
+ * RVL_03 - Ventas por vendedor (semanal).
+ * RVL_04 - Ventas por producto (mensual).
+ * RVL_05 - Ventas por financiera (mensual).
+ *
+ * ⚠️ FUERA de F3: `RVL-06` (cross-border, es M5) y `RVL-07` (conciliación, backend de cobranza).
+ */
+export enum SalesReportIdEnum {
+    RVL_01 = 'RVL-01',
+    RVL_02 = 'RVL-02',
+    RVL_03 = 'RVL-03',
+    RVL_04 = 'RVL-04',
+    RVL_05 = 'RVL-05',
+}

package/src/retailWizard/helpers/saleFinancier.ts

@@ -0,0 +1,48 @@
+import { SaleTypeEnum } from '../enums/SaleTypeEnum';
+import { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
+import { SaleFinancierEnum } from '../enums/SaleFinancierEnum';
+
+/** Lo mínimo de una venta para derivar su financiera. */
+export interface SaleFinancierSource {
+    type: SaleTypeEnum;
+    externalProvider: ExternalProviderEnum | null;
+}
+
+/**
+ * Mapa explícito proveedor → financiera. Es un `Record` COMPLETO a propósito: agregar un proveedor a
+ * `ExternalProviderEnum` sin agregarlo acá es error de compilación, que es exactamente el recordatorio
+ * que queremos. Un cast desde el enum de proveedor se vería más corto y perdería esa garantía.
+ */
+const FINANCIER_BY_PROVIDER: Record<ExternalProviderEnum, SaleFinancierEnum> = {
+    [ExternalProviderEnum.PAYJOY]: SaleFinancierEnum.PAYJOY,
+    [ExternalProviderEnum.CREDIYA]: SaleFinancierEnum.CREDIYA,
+    [ExternalProviderEnum.LESPAGO]: SaleFinancierEnum.LESPAGO,
+    [ExternalProviderEnum.INNOVA]: SaleFinancierEnum.INNOVA,
+};
+
+/**
+ * Deriva la financiera de una venta. Vive acá —y no en el lambda— porque el Admin VL agrupa por
+ * financiera en tres pantallas distintas (Ventas, Reportes, Análisis) y el front tiene que llegar al
+ * MISMO número que el backend; dos implementaciones paralelas divergen al primer tipo nuevo.
+ *
+ * `EXTERNAL_REFERRAL` sin `externalProvider` cae en `NONE` en vez de reventar: hay ventas viejas sin
+ * el campo y un contador no es lugar para tirar una excepción.
+ */
+export function financierOfSale(sale: SaleFinancierSource): SaleFinancierEnum {
+    if (sale.type === SaleTypeEnum.CREDIT) return SaleFinancierEnum.SUREKEEP;
+    if (sale.type === SaleTypeEnum.EXTERNAL_REFERRAL && sale.externalProvider) {
+        return FINANCIER_BY_PROVIDER[sale.externalProvider] ?? SaleFinancierEnum.NONE;
+    }
+    return SaleFinancierEnum.NONE;
+}
+
+/** ¿La financió SureKeep? (pill «SureKeep» de los contadores del Admin VL). */
+export function isSureKeepFinanced(sale: SaleFinancierSource): boolean {
+    return financierOfSale(sale) === SaleFinancierEnum.SUREKEEP;
+}
+
+/** ¿La financió un tercero? (pill «Externas»). Contado NO cuenta: no tiene financiera. */
+export function isExternallyFinanced(sale: SaleFinancierSource): boolean {
+    const financier = financierOfSale(sale);
+    return financier !== SaleFinancierEnum.SUREKEEP && financier !== SaleFinancierEnum.NONE;
+}