Saltar a contenido

POS TiprePOS (Flutter)

Referencia técnica de la terminal de autoservicio: stack, arranque, routing, BLoCs, servicios y persistencia. Vive en el repo TiprePOS. Esta es la vista general; el detalle de cada subsistema está en sus páginas:

La terminal de autoservicio arrancando

La terminal real (build de Windows) en su pantalla de conexión, con el branding de un comercio (SUPER MAMI / DINO) aplicado por el theming por comercio y los badges de identidad de la terminal (AUTOCOMPRA, DINO99999, versión de config).

Stack

Pieza Valor
Lenguaje Dart >=3.0.0 <4.0.0
Framework Flutter >=3.35.6
Estado bloc + flutter_bloc
Navegación go_router
Persistencia local isar_community (DB auto_compra_db)
Red http (REST a /autocompras/v1)
Conectividad connectivity_plus
Desktop window_manager (la terminal corre en escritorio)
Impresión ti_printer_plugin + servicios propios (USB/BT/Red/Serial)

Arranque

La secuencia de init vive en lib/main.dart y lib/auto_compra_app.dart:

  1. main() corre dentro de runZonedGuarded() (captura global de errores). Inicializa AppLogger, abre Isar (auto_compra_db), recupera pagos in-flight pendientes (PendingPaymentService, fix INT-002) y configura WindowManagerService para desktop (incluye manejo de sesiones RDP con fullscreen forzado).
  2. AutoCompraApp crea servicios, repositorios y BLoCs, e inyecta todo con un MultiBlocProvider.
  3. Init secuencial de BLoCs (_initializeBlocsSequentially): LoadConnectionConfiguration → LoadTerminalConfiguration → RegisterTerminal (si hay conexión) → StartNetworkMonitoring.

Routing (go_router)

Configurado en lib/routing/app_router_builder.dart, con refreshListenable: AppStateNotifier (reactivo al estado global) y una lógica de redirect que hace de gate:

graph TD
    START["/"] -->|sin connection config| CONF["/configuration"]
    START -->|sin registro de terminal| REG["/register"]
    START -->|config + registro OK| HOME["/home"]

Rutas principales:

Path Pantalla Notas
/ Initialize / Splash Decide el destino.
/configuration ConfigurationPage Server, puerto, SSL, código de terminal.
/register RegisterPage Registra la terminal contra el backend.
/home HomePage Portal central.
/scan ScanPage Escaneo de productos / carrito.
/envases EnvasesPage Envases y vales.
/mediosPago MediosPagoPage Selector de medio de pago.
/pagoQR PagoQRPage Pago QR (timeout ~210 s).
/pagoPointSmart PagoPointSmartPage Point Smart (timeout ~90 s).
/pagoTarjeta PagoTarjetaPage Tarjeta vía ApiCard.
/planPago PlanPagoPage Cuotas.
/resultPayment ResultPaymentPage Resultado del cobro.
/settings SettingsPage Parámetros de UI.
/managementTicket ManagementTicketPage Historial de tickets.
/managementVale ManagementValePage Gestión de vales.
/managementPrinter ManagementPrinterPage Config de impresora.
/error ErrorPage Manejo de errores.

Las rutas protegidas no son accesibles sin completar configuración + registro.

BLoCs principales

Bajo lib/viewmodels/:

BLoC Responsabilidad
ConfigurationBloc Carga/persistencia de config de conexión y de terminal.
BackendClientBloc Centro de la comunicación REST: despacha mutaciones (SendMessage) y hace el polling de /status con Timer adaptativo (60 s / 15 s).
TicketBloc Estado del carrito (ítems, selección, scroll, scan pendiente).
PrinterBloc Impresora: conexión (USB/BT/Red/Serial), monitoreo, reintentos con backoff, impresión.
ApicardBloc Pago con tarjeta (daemon ApiCard local).
NetworkBloc Conectividad del device.
PaymentMeansBloc / PaymentMethodBloc / PaymentInstallmentBloc Medios de pago disponibles, medio elegido y planes de cuotas.
EnvaseBloc / ValeBloc Envases y vales.
TicketManagementBloc / ValeManagementBloc Historial y administración.
InactividadBloc Timer de inactividad (cancela el ticket por inactividad).
SupervisorBloc Modo supervisor.

Servicios

Bajo lib/services/:

Servicio Responsabilidad
HttpCliente Wrapper HTTP que inyecta X-Cod-Terminal, X-Terminal-Uuid, X-Device-Health. Traduce SocketException/TimeoutException/HandshakeException a fallas de dominio.
TicketService Mutaciones REST de ticket (open/agregar/remove/close/changeStatus/validate).
MercadopagoService createIntent / executePayment para QR y Point Smart.
ApicardService Identificación/autorización/anulación contra el daemon ApiCard.
ConfigurationService Config local y remota; genera el UUID del device; propaga identidad al HttpCliente.
IsarServiceImpl Persistencia local (auto_compra_db).
PendingPaymentService Recupera pagos in-flight al arrancar (fix INT-002).
PrinterService (+ implementaciones USB/BT/Network/Serial) Impresión.

Persistencia (Isar)

Base auto_compra_db. Ubicación por plataforma: en Linux usa /opt/autocompra/current/ o el directorio de documentos; en Windows/macOS/Android/iOS, el directorio de documentos de la app.

Entidades (en lib/models/isar/):

  • IsarConfig — contenedor que agrupa config de ticket, POS, impresora, timeouts, devices, bolsas, ingreso manual.
  • IsarConnectionConfig — codTerminal, server, port, ssl, uuid, y (fix TPOS-016) apicardServer/Port/Ssl.
  • IsarTerminalConfig — codSucursal, codNegocio, codComercio, nroPos, nroPVFiscal, etc.
  • IsarPendingPayment — pagos in-flight (fix INT-002): paymentAttemptId, idProcessorPayment, status, createdAt.

Comunicación con el backend

REST sobre /autocompras/v1 (lib/core/api/api_paths.dart). El detalle de mutaciones, polling de salud, resiliencia y la migración desde STOMP está en Comunicación POS ↔ Backend.