Saltar a contenido

Glosario del dominio

Los términos que aparecen una y otra vez en el código y en esta documentación. Si entrás nuevo, leé esto antes de la referencia técnica: muchas confusiones son sólo vocabulario.

Conceptos del negocio

Término Qué es
Autoservicio / autopago El modelo donde el propio cliente del comercio escanea, paga y se lleva su ticket, sin cajero. Es lo que opera la terminal.
Terminal La máquina física de autoservicio (corre TiprePOS en desktop). Tiene un codTerminal y un uuid propios. También se le dice POS.
Ticket La compra en curso: el carrito con sus ítems, totales, impuestos y estado. En el backend se persiste como Trx.
Artículo Un producto del catálogo, identificado por EAN (código de barras) y sucursal. Tiene precio, impuesto, si es pesable, si es envase, etc.
EAN El código de barras estándar del producto. La terminal escanea un EAN y el backend resuelve el artículo.
Promo / promoción Un descuento o beneficio que el módulo promos calcula sobre el ticket. Ver Promociones.
Envase Producto retornable (botella, cajón) con depósito. Se gestiona en el módulo envases. Ver Envases y vales.
Vale Comprobante de un envase devuelto (o crédito retornable), con nroVale y codVale. Auditado con Hibernate Envers.
Itemización La separación entre ítems (lo que el cliente ve) y movimientos (las anotaciones contables que componen el total). Ver El agregado Ticket.
Núcleo impositivo Un monto con su descomposición fiscal adentro (NucleoImpositivoDto, en shared): neto, IVA, impuestos internos. No es un número suelto. Ver Núcleo impositivo.
EAN pesable / random-price Código de barras que trae el peso o el precio embebidos (productos de balanza). Ver Decodificación de EAN.
DUN Código de venta por bulto (más de 13 dígitos).

Estados del ticket (Trx)

El backend modela el ciclo de vida del ticket con estos estados:

Estado Significa
OPEN Ticket abierto, el cliente está agregando ítems.
PAGADO El pago se aprobó.
VOUCHERPENDING Pagado pero el comprobante fiscal todavía no se emitió/confirmó. Estado de borde con la fiscalización.
CLOSE Ticket cerrado y completo.
CANCELED_USER Cancelado por el cliente.
CANCELED_INACTIVITY Cancelado automáticamente por inactividad (la terminal tiene timers).
ERROR Terminó en error.

Medios y procesadores de pago

Término Qué es
QR (MercadoPago) Pago donde la terminal muestra un QR que el cliente escanea con su app. Timeout en la terminal: ~210 s.
Point Smart Terminal física de MercadoPago (pinpad) donde el cliente inserta/apoya la tarjeta. Timeout: ~90 s. Tiene su propia máquina de estados de orden.
ApiCard Integración de pago con tarjeta vía un daemon local (por defecto localhost:50001), no por el backend.
Intent (intención de pago) El primer paso del pago: se crea la intención (payment-intent / createIntent) antes de ejecutar/cobrar.
PaymentAttempt Un intento de cobro. El paymentAttemptId se genera una vez por intención y se reusa en reintentos para evitar el doble cobro (idempotencia).

Estados de orden de Point Smart

Estado Significa
created Orden creada, la terminal física todavía no la tomó.
at_terminal La terminal tiene la orden, esperando que el comprador interactúe.
processed Aprobada y acreditada.
failed Rechazada.
action_required Incierto (~40 s): hay que revisar la terminal.
expired Pasaron más de ~15 min sin completarse.
canceled Cancelada por la API o la terminal.
refunded Reembolsada.

Tipos de promoción

Término Qué es
COMBO Promo que exige comprar productos de varios grupos (ej. "2 de A + 1 de B").
CANTIDAD Promo que se activa por cantidad mínima de unidades (ej. "llevando 3").
MAYORISTA Escala de precio por volumen de un EAN.
BULTO Venta especial por bulto (identificado por DUN).
Acumulativa Si una promo puede apilarse con otras sobre la misma línea (SI) o si gana solo la mejor (NO).
MODO ITEMS / MODO PAGO (MDP) Si la promo se calcula al armar el carrito (ITEMS) o al elegir medio de pago (MDP).

Facturación fiscal (AFIP)

Término Qué es
Comprobante El documento fiscal: Factura A/B/C, nota de crédito o débito. Ver Facturación fiscal.
CAE Código de Autorización Electrónico que AFIP otorga por comprobante, online, por SOAP.
CAEA Código de Autorización Electrónico Anticipado: AFIP lo otorga por adelantado para una quincena. Permite facturar con AFIP caído.
Condición IVA La categoría fiscal del comprador (Responsable Inscripto, Consumidor Final, Monotributo…). Determina la letra del comprobante.
Punto de venta (nroPVFiscal) El número de punto de venta fiscal del POS ante AFIP.
Reconciliador El job (PaymentReconciliador) que resuelve los pagos INDETERMINADO sin depender del POS. Ver El ciclo de pago y fiscalización.
Indeterminado El estado de un pago cuando la red cortó entre "cobré" y "recibí la confirmación": no se sabe si se cobró.
REQUIERE_REVISION Un pago que agotó los reintentos del reconciliador y necesita intervención humana.

Conceptos técnicos

Término Qué es
Monolito modular Un solo deployable dividido internamente en módulos con fronteras verificadas. Acá: Spring Modulith.
Spring Modulith El framework que define los módulos (@ApplicationModule) y verifica los boundaries en el build.
Módulo Una unidad del backend (tickets, catalogo, pagos, promos, envases, shared) con API pública e internals privados.
Guardrail El test ModularityTests.verify() que rompe el build si se viola una frontera o aparece un ciclo.
Kernel OPEN Un módulo (shared) marcado como abierto: cualquiera puede depender de él.
Estrella acíclica La topología interna: sólo tickets llama, el resto son hojas, sin ciclos.
Strangler (migración) Estrategia de migrar de a un módulo por vez, manteniendo lo viejo hasta el corte.
Schema-por-módulo Cada módulo tiene su propio schema/DataSource; nada de foreign keys cruzadas.
BLoC El patrón de manejo de estado de la terminal Flutter (flutter_bloc): eventos → estados.
Isar La base de datos local de la terminal (auto_compra_db), donde se persiste la configuración.
Cockpit / monitoring El panel de operación y el módulo backend (monitoring) que lo alimenta.
Heartbeat El ping periódico de cada terminal que el backend usa para saber qué POS están online (ventana ~90 s).
Parque de POS El conjunto de terminales: las configuradas en la tabla pos ∪ las que pingearon.