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 nuevaconsulta.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 enBenefitResolver.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_minimose compara contra la base efectiva: el mínimo de la promoción se refiere a lo que se descuenta, no al ticket completo. BASE_CEROen lugar de descuento cero. Conbase_amountinformado y base efectiva 0, el beneficio se descarta conBASE_CEROen 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 enconsulta.response_json(baseAmount,nullsi no se informó). Coincide con el grano del total, que tampoco tiene columna propia;consulta_beneficioes 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 nullableconsulta.base_efectivo; no está hecho. - Respuesta. Cada beneficio devuelve
baseAmount(efectiva) onullsi 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 esbase_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_amountla salida es la anterior, salvobaseAmount: 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_amounthacia TECSO y auditoría del eco. - POS DINO 20261116F: emisión de
base_amounten/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.