@fiado/type-kit 3.273.0 → 3.275.0

package/bin/datalakeQuery/dtos/ReportRequestDto.d.ts

@@ -37,6 +37,32 @@ export interface MetricSpecDto {
     /** Con `COUNT` se acepta `{ column: '*' }`. */
     column: ColumnRefDto;
     fn: MetricFnEnum;
+    /**
+     * Columnas de respaldo, en orden: el backend emite `FN(COALESCE(col, r1, r2…))`.
+     *
+     * ## Cuándo lo necesitas
+     *
+     * Cuando el valor que quieres sumar vive en más de una columna según la fila. En
+     * `retail_sale`, por ejemplo, el monto está en `amountcents` o en `equipmentpricecents` — no
+     * hay una columna `soldcents`.
+     *
+     * **No se puede resolver del lado del caller.** `SUM(COALESCE(a,b))` NO se reconstruye desde
+     * `SUM(a)` y `SUM(b)`: el COALESCE es por fila, así que si unas traen `a` y otras solo `b`,
+     * cualquier combinación da un número distinto. O lo hace el motor, o el dato sale mal.
+     *
+     * ## Por qué es un campo del request y no una columna del lake
+     *
+     * Una columna calculada en la tabla Iceberg **congelaría la regla de negocio dentro del
+     * pipeline de datos**, que es de otro equipo: cambiarla obligaría a redesplegar el pipeline y a
+     * rellenar el histórico, y la definición quedaría lejos de la decisión que la gobierna.
+     *
+     * Así el mecanismo es genérico y **qué columnas encadenar lo decide el dominio dueño de la
+     * regla**, en su propio código.
+     *
+     * ⚠️ Cada respaldo se valida contra el schema vivo de Glue igual que cualquier otra columna.
+     * No admite `COUNT(*)`.
+     */
+    coalesceWith?: ColumnRefDto[];
     /** Alias de salida. Si no viene, se deriva de la función y la columna. */
     alias?: string;
 }

package/bin/retailWizard/dtos/SaleException.d.ts

@@ -32,6 +32,8 @@ export interface SaleException {
     requestedAt: string;
     /** OBLIGATORIA. Es lo que hace auditable la excepción. */
     justification: string;
+    /** Qué pidió el solicitante, en sus palabras. `null` si no lo detalló. */
+    requestedAction: string | null;
     /**
      * 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.

package/bin/retailWizard/dtos/requests/CreateSaleExceptionRequest.d.ts

@@ -22,6 +22,25 @@ export declare class CreateSaleExceptionRequest {
     /** Obligatorio cuando NO hay `saleId`; si hay venta, se toma el de la venta. */
     storeId?: string;
     justification: string;
+    /**
+     * Quién PIDIÓ la excepción, cuando no es quien la registra.
+     *
+     * El botón «Levantar excepción» vive en la pantalla del Admin VL, pero el mockup muestra
+     * `solicitante: V-05` con «Vendedor solicita corrección»: el vendedor avisa por fuera y el Admin
+     * la anota. Sin este campo, la columna «Solicitante» diría SIEMPRE «Admin VL» y se perdería el
+     * dato de quién originó el caso — que es justo lo que la bandeja viene a auditar.
+     *
+     * Ausente → se usa el actor del token (el Admin la levantó por su cuenta).
+     */
+    requestedBy?: string;
+    /**
+     * Qué hay que hacer, en palabras del humano. Ej.: «cambiar SKU de P-002 a P-005».
+     *
+     * Convive con `payload` y NO lo reemplaza: el texto libre es para que la persona explique, el
+     * `payload` tipado es para que algún día el sistema pueda aplicar el cambio solo. Hoy quien
+     * aplica es un humano leyendo esto.
+     */
+    requestedAction?: string;
     /** Impacto económico con signo, en centavos. Negativo si la excepción resta (descuento). */
     impactCents?: number;
     payload?: SaleExceptionPayloadInput;

package/bin/retailWizard/dtos/requests/CreateSaleExceptionRequest.js

@@ -81,6 +81,20 @@ __decorate([
     (0, class_validator_1.MaxLength)(1000),
     __metadata("design:type", String)
 ], CreateSaleExceptionRequest.prototype, "justification", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(64),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "requestedBy", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(500),
+    __metadata("design:type", String)
+], CreateSaleExceptionRequest.prototype, "requestedAction", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.273.0",
+  "version": "3.275.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/datalakeQuery/dtos/ReportRequestDto.ts

@@ -41,6 +41,32 @@ export interface MetricSpecDto {
     /** Con `COUNT` se acepta `{ column: '*' }`. */
     column: ColumnRefDto;
     fn: MetricFnEnum;
+    /**
+     * Columnas de respaldo, en orden: el backend emite `FN(COALESCE(col, r1, r2…))`.
+     *
+     * ## Cuándo lo necesitas
+     *
+     * Cuando el valor que quieres sumar vive en más de una columna según la fila. En
+     * `retail_sale`, por ejemplo, el monto está en `amountcents` o en `equipmentpricecents` — no
+     * hay una columna `soldcents`.
+     *
+     * **No se puede resolver del lado del caller.** `SUM(COALESCE(a,b))` NO se reconstruye desde
+     * `SUM(a)` y `SUM(b)`: el COALESCE es por fila, así que si unas traen `a` y otras solo `b`,
+     * cualquier combinación da un número distinto. O lo hace el motor, o el dato sale mal.
+     *
+     * ## Por qué es un campo del request y no una columna del lake
+     *
+     * Una columna calculada en la tabla Iceberg **congelaría la regla de negocio dentro del
+     * pipeline de datos**, que es de otro equipo: cambiarla obligaría a redesplegar el pipeline y a
+     * rellenar el histórico, y la definición quedaría lejos de la decisión que la gobierna.
+     *
+     * Así el mecanismo es genérico y **qué columnas encadenar lo decide el dominio dueño de la
+     * regla**, en su propio código.
+     *
+     * ⚠️ Cada respaldo se valida contra el schema vivo de Glue igual que cualquier otra columna.
+     * No admite `COUNT(*)`.
+     */
+    coalesceWith?: ColumnRefDto[];
     /** Alias de salida. Si no viene, se deriva de la función y la columna. */
     alias?: string;
 }

package/src/retailWizard/dtos/SaleException.ts

@@ -33,6 +33,8 @@ export interface SaleException {
     requestedAt: string;
     /** OBLIGATORIA. Es lo que hace auditable la excepción. */
     justification: string;
+    /** Qué pidió el solicitante, en sus palabras. `null` si no lo detalló. */
+    requestedAction: string | null;
     /**
      * 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.

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

@@ -70,6 +70,35 @@ export class CreateSaleExceptionRequest {
     @MaxLength(1000)
     justification!: string;
 
+    /**
+     * Quién PIDIÓ la excepción, cuando no es quien la registra.
+     *
+     * El botón «Levantar excepción» vive en la pantalla del Admin VL, pero el mockup muestra
+     * `solicitante: V-05` con «Vendedor solicita corrección»: el vendedor avisa por fuera y el Admin
+     * la anota. Sin este campo, la columna «Solicitante» diría SIEMPRE «Admin VL» y se perdería el
+     * dato de quién originó el caso — que es justo lo que la bandeja viene a auditar.
+     *
+     * Ausente → se usa el actor del token (el Admin la levantó por su cuenta).
+     */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    requestedBy?: string;
+
+    /**
+     * Qué hay que hacer, en palabras del humano. Ej.: «cambiar SKU de P-002 a P-005».
+     *
+     * Convive con `payload` y NO lo reemplaza: el texto libre es para que la persona explique, el
+     * `payload` tipado es para que algún día el sistema pueda aplicar el cambio solo. Hoy quien
+     * aplica es un humano leyendo esto.
+     */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @MaxLength(500)
+    requestedAction?: string;
+
     /** Impacto económico con signo, en centavos. Negativo si la excepción resta (descuento). */
     @Expose()
     @IsOptional()