Saltar a contenido

ADR-007 — Base del beneficio (base_amount)

Status: accepted (liberado en BeneficiosCenter v1.6.0, 2026-11-16). Dos puntos siguen pendientes de confirmación del cliente: ver Preguntas de negocio abiertas.

Contexto

Hasta v1.5.0 el beneficio se calcula siempre sobre el total del pago QR. Hay promociones de medio de pago que apuntan a un medio que el POS no tiene: el descuento corresponde solo a una parte del ticket (lo acumulado que cumple la promoción). El POS conoce esa parte; BeneficiosCenter no. Hay que informarla sin romper a ningún integrador existente.

Flujo extremo a extremo: el POS envía base_amount (nivel superior de /trxpago) solo cuando hay promoción base, con base = mínimo entre lo acumulado y el total. El GatewayQR lo reenvía al resolver como transaction.base_amount, emite discount.base_amount al autorizador TECSO y audita el eco benefits_data.base_amount. El detalle del circuito está en Base del beneficio (base_amount).

Alternativas

  • Piso y techo de la base. (A) Rechazar con 400 una base negativa o mayor al total. (B) Recortar a [0, amount] (elegida).
  • monto_minimo. (A) Seguir comparando contra el total. (B) Comparar contra la base efectiva (elegida).
  • Base efectiva 0. (A) Ofrecer el beneficio con descuento 0.00 (sin caso especial). (B) Descartar con MotivoDescarte.BASE_CERO (elegida).
  • Auditoría. (A) Columna nueva en consulta_beneficio. (B) Columna nueva consulta.base_efectivo. (C) Dentro del JSON de la consulta, sin migración (elegida).
  • Eco del autorizador. (A) Rechazar el pago si el eco difiere. (B) Auditar y emitir WARN, sin fallar nunca (elegida).
  • Compatibilidad. (A) Campo obligatorio. (B) Campo opcional; ausente = total (elegida).

Decisión

  • Recorte, no rechazo. Base efectiva = min(max(base_amount, 0), amount), calculada una vez en BenefitResolver.resolve. Un valor inválido nunca bloquea el cobro (fail-safe); el recorte colapsa a la matemática histórica cuando la base es igual o mayor al total.
  • Mínimo sobre la base. monto_minimo se compara contra la base efectiva: el mínimo de la promoción se refiere a lo que se descuenta, no al ticket completo.
  • BASE_CERO en lugar de descuento cero. Con base_amount informado y base efectiva 0, el beneficio se descarta con BASE_CERO en lugar de ofrecer uno de 0.00. Solo cuenta una base informada: con base ausente el comportamiento no cambia, aunque el descuento redondee a 0. Esto reemplaza lo que proponía el diseño inicial ("sin caso especial") y gobierna la implementación.
  • Auditoría en el JSON. Sin columna ni migración Flyway: la base cruda queda en consulta.request_json (la clave no figura si el request no la trajo) y la base efectiva por beneficio en consulta.response_json (baseAmount, null si no se informó). Coincide con el grano del total, que tampoco tiene columna propia; consulta_beneficio es de grano por beneficio y repetiría un valor por consulta. Si más adelante hace falta consultarla por SQL, el paso aditivo es una columna nullable consulta.base_efectivo; no está hecho.
  • Respuesta. Cada beneficio devuelve baseAmount (efectiva) o null si el request no la informó, para que el gateway emita a TECSO la base que realmente produjo el descuento sin recalcular el recorte. En el request el nombre de wire es base_amount (@JsonProperty), porque el resolver no usa estrategia snake_case.
  • Eco de TECSO. El GatewayQR lo lee solo para auditoría y conciliación: una diferencia con la base enviada genera WARN y un eco ausente no afecta el procesamiento.
  • Compatibilidad. Campo opcional, sin default impuesto por el gateway. Sin base_amount la salida es la anterior, salvo baseAmount: null.

Consecuencias

  • Cero migraciones y ningún cambio para integradores que no envían la base.
  • El POS decide la base y el servidor la limita: ni un dato incorrecto produce un descuento mayor al total.
  • La base queda auditada en el JSON de cada consulta.
  • La base no es consultable por SQL sin parsear JSON (diferido, ver arriba).
  • Una base errónea enviada por el POS no se detecta en el servidor; solo se limita al rango válido.
  • Los artefactos SDD originales (spec y diseño) divergían de la implementación final; este ADR y la sección 5.5 del SPEC documentan la versión implementada.

Preguntas de negocio abiertas

Pendientes de confirmación del cliente (DINO); la implementación actual es la postura vigente, no una decisión cerrada:

  • Mínimo evaluado contra la base y no contra el total.
  • Descarte BASE_CERO (sin beneficio) frente a ofrecer un descuento de 0.00.

Plan de implementación

  • BeneficiosCenter v1.6.0: TransactionDto, ResolutionRequest, BenefitResolver, ResolvedBenefit, BenefitDto, MotivoDescarte.BASE_CERO.
  • GatewayQR v20261116: persistencia de base_amount, reenvío al resolver, discount.base_amount hacia TECSO y auditoría del eco.
  • POS DINO 20261116F: emisión de base_amount en /trxpago.
  • Verificación de campo (2026-11-16): base 2750 → descuento 275.00 (10 % de la base); control sin base → 450.00.

Verificación

  • Resolver: descuento sobre la base, recorte, mínimo sobre la base, BASE_CERO, compatibilidad y auditoría en JSON (AC-68..AC-74; BenefitResolverTest, ResolverHotPathTest). Cumplido.
  • Integración GatewayQR / TECSO cubierta por tests (AC-75, en el repositorio de GatewayQR). Cumplido.
  • Confirmación del cliente sobre mínimo sobre la base y BASE_CERO: pendiente.