@fiado/type-kit 3.275.0 → 3.277.0

package/src/retailOrg/dtos/responses/StoreKpiResponse.ts

@@ -0,0 +1,36 @@
+import type { GoalAmounts } from '../GoalAmounts';
+
+/**
+ * Volumen vendido en el periodo, según el data lake.
+ *
+ * 🔴 `soldCents` NO es `amountCents` de la venta. Es `COALESCE(equipmentPriceCents, amountCents)` —
+ * volumen **colocado**, por DEC-032. En una venta a crédito `amountCents` es solo el enganche: un
+ * equipo de $5,000 financiado aportaría $1,300 y el vendedor cobraría comisión sobre eso.
+ */
+export interface SoldAggregate {
+    pieces: number;
+    soldCents: number;
+}
+
+/**
+ * Respuesta de `GET /backoffice/stores/{storeId}/kpis` — el drawer de una tienda.
+ *
+ * 🔴 **`null`, nunca `0`.** Un `0` dice *«no vendió»*; un `null` dice *«no sé todavía»*, y la UI lo
+ * pinta `—`. Un 0 % de meta a media tarde manda a alguien a corregir algo que nadie fijó.
+ *
+ * `sellersActive` es la excepción: sale del padrón (`RetailUser_GT`), siempre se puede contar, y `0`
+ * ahí SÍ es un dato — una tienda sin vendedores asignados.
+ */
+export interface StoreKpiResponse {
+    storeId: string;
+    name: string;
+    zoneId: string | null;
+    /** Vendedores ACTIVE con esta tienda como `homeStoreId`. `0` es válido. */
+    sellersActive: number;
+    /** `null` si no se fijó meta para el periodo. */
+    goal: GoalAmounts | null;
+    /** `null` si el lake no contestó (o si está apagado por flag). NUNCA ceros. */
+    sold: SoldAggregate | null;
+    /** Avance sobre la meta mensual, 1 decimal. `null` si falta cualquiera de los dos. */
+    goalPct: number | null;
+}

package/src/retailOrg/dtos/validation/PrivateSellerListResponse.ts

@@ -0,0 +1,32 @@
+import type { RetailUserStatusEnum } from '../../enums/RetailUserStatusEnum';
+
+/**
+ * Shape mínimo de un vendedor para el motor de comisiones (F3b): a quién pagarle, de qué tienda es y
+ * en qué tier va.
+ *
+ * **Sin PII** — nada de teléfono ni `cognitoSub`. `displayName` es el rótulo de conveniencia con el
+ * que el motor arma su reporte de devengo; no es identidad (la identidad vive en RBAC).
+ *
+ * `commissionTier` no es adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada vendedor
+ * según el plan de comisiones vigente.
+ */
+export interface PrivateSellerDto {
+    sellerId: string;
+    displayName: string | null;
+    homeStoreId: string | null;
+    commissionTier: string;
+    status: RetailUserStatusEnum;
+}
+
+/**
+ * Respuesta de `GET /private/sellers?retailerId=…` — el padrón de una cadena, para máquinas.
+ *
+ * ⚠️ `status` viene en cada fila a propósito. Un vendedor dado de baja a mitad de periodo **sí tiene
+ * comisión** por lo que vendió antes, así que el filtro `?status=` es una conveniencia y el motor de
+ * comisiones probablemente tenga que pedir TODOS. Pedir solo activos y perder a alguien que renunció
+ * el día 20 sería un error caro.
+ */
+export interface PrivateSellerListResponse {
+    retailerId: string;
+    sellers: PrivateSellerDto[];
+}

package/src/retailOrg/enums/GoalTargetTypeEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * A quién se le fija una meta de venta del periodo (SureKeep F3, Portal Admin VentasLuga).
+ *
+ * Es parte de la SORT KEY de `RetailGoal_GT` (`GOAL#<periodId>#<targetType>#<targetId>`), así que
+ * los valores son contrato de datos, no solo de API: cambiar un literal deja huérfanas las filas ya
+ * escritas. Solo hay dos targets y no se prevén más — la meta de una zona sale de sumar sus tiendas.
+ */
+export enum GoalTargetTypeEnum {
+    STORE = 'STORE',
+    SELLER = 'SELLER',
+}

package/src/retailOrg/index.ts

@@ -5,9 +5,12 @@ export * from './enums/StoreStatusEnum';
 export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
+// F3 — Portal Admin VentasLuga (metas de venta del periodo)
+export * from './enums/GoalTargetTypeEnum';
 
 // Entity DTOs
 export * from './dtos/GeoLocation';
+export * from './dtos/GoalAmounts';
 export * from './dtos/Retailer';
 export * from './dtos/Zone';
 export * from './dtos/Store';
@@ -18,6 +21,7 @@ export * from './dtos/validation/RetailerValidationDto';
 export * from './dtos/validation/StoreValidationDto';
 export * from './dtos/validation/RetailUserValidationDto';
 export * from './dtos/validation/CollectorValidationDto';
+export * from './dtos/validation/PrivateSellerListResponse';
 
 // Paginación genérica
 export * from './dtos/PaginatedResult';
@@ -39,6 +43,16 @@ export * from './dtos/requests/ProvisionRetailUserRequest';
 export * from './dtos/requests/UpdateRetailUserRequest';
 export * from './dtos/requests/ChangeRetailUserStatusRequest';
 export * from './dtos/requests/TransferRetailUserRequest';
+// F3 — metas y KPIs del Portal Admin VL
+export * from './dtos/requests/GoalListQuery';
+export * from './dtos/requests/GoalUpsertRequest';
+export * from './dtos/requests/GoalPathParams';
+export * from './dtos/requests/KpiQuery';
+export * from './dtos/requests/PrivateSellerListQuery';
 
 // Response DTOs
 export * from './dtos/responses/RetailerHierarchyResponse';
+export * from './dtos/responses/GoalListResponse';
+export * from './dtos/responses/GoalUpsertResponse';
+export * from './dtos/responses/StoreKpiResponse';
+export * from './dtos/responses/SellerKpiResponse';