Subsistema de Impresión Auto-Compra POS + ti_printer_plugin · dossier completo

01Resumen ejecutivo

Por qué necesita fixes en las dos capas

Un fix sólo en el plugin no es suficiente: aunque el plugin ahora tenga timeout real en ReadStatusUsb y devuelva todos los bytes leídos, la app sigue tratando "bytes aceptados por el endpoint USB" como "ticket impreso" (Causa D). Un fix sólo en la app tampoco alcanza: aunque la app haga confirmación post-envío, si el plugin no tiene timeout, una lectura USB colgada deja la confirmación esperando indefinidamente.

Los fixes son complementarios — los del plugin dan las herramientas, los de la app las usan correctamente. Esta es la motivación de tenerlos juntos en un solo documento.

02Cadena causal del incidente

Reconstrucción de la secuencia entre la falla física (cable USB) y los síntomas en la app y en el hardware de la impresora, anclando cada paso a la causa raíz que lo origina. El timing es aproximado pero el orden de eventos refleja el código actual.

Causas raíz

Cada causa es independiente y produce su propio síntoma observable; combinadas amplifican el daño. Las cuatro son P0.

03Arquitectura integral · ambos componentes

Diagrama de las 8 capas que atraviesa un byte desde el evento de UI en la app de self-checkout hasta el cabezal térmico de la impresora. Las primeras 4 viven en el código de la app (auto-compra/lib/), las siguientes 4 en el plugin (ti_printer_plugin/). La línea horizontal marca el límite entre ambos repos.

Los símbolos PLG-XX referencian hallazgos del plugin (sección 06). Los APP-XX referencian fixes de la app (sección 10). El color indica severidad: rojo P0, ámbar P1, verde P2.

04Plugin · stack y zonas afectadas

Mapa del recorrido de un byte desde que se construye el ticket en Dart hasta que llega al cabezal térmico, con los IDs de hallazgo de esta auditoría posicionados donde efectivamente viven en el código.

05Plugin · conteo por severidad

Criterio: crítico = afecta correctitud, puede colgar la app o corromper el ticket en escenarios reales; latente = falla sólo en casos borde (texto vacío, payloads grandes, datos no-ASCII); smell = funciona pero confunde a quien lo lea o derrocha bytes / recursos.

06Plugin · hallazgos detallados

22 hallazgos en total. Cada uno con archivo, línea y un fragmento antes / después. Los fragmentos están reducidos a lo mínimo necesario para mostrar la diferencia; la versión completa de cada archivo parcheado va en la sección siguiente.

TiPrinterPlugin()
  : hSerial_(INVALID_HANDLE_VALUE) {}

TiPrinterPlugin()
  : hSerial_(INVALID_HANDLE_VALUE),
    hUsb_(INVALID_HANDLE_VALUE) {}

if (bytes_read > 0) {
  return { static_cast<uint8_t>(response[0]) };
}

std::vector<uint8_t> result;
if (bytes_read > 0) {
  result.assign(response, response + bytes_read);
}
return result;

// 1) Abrir overlapped
hUsb_ = CreateFile(..., FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED, NULL);

// 2) ReadStatusUsb con timeout real
OVERLAPPED overlapped = {};
overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

BOOL ok = ReadFile(hUsb_, response, sizeof(response), &bytes_read, &overlapped);
if (!ok && GetLastError() == ERROR_IO_PENDING) {
  DWORD wait = WaitForSingleObject(overlapped.hEvent, 500);
  if (wait != WAIT_OBJECT_0) {
    CancelIoEx(hUsb_, &overlapped);  // timeout → cancelo la pending I/O
    ...
  }
}

bytes += cQrHeader.codeUnits +
  [textBytes.length + 3, 0x00, 0x31, 0x50, 0x30];

final int storeLen = textBytes.length + 3;
final int pL = storeLen & 0xFF;
final int pH = (storeLen >> 8) & 0xFF;
bytes += cQrHeader.codeUnits +
  [pL, pH, 0x31, 0x50, 0x30];

List<int> textBytes = latin1.encode(text);

final List<int> textBytes = utf8.encode(text);

bytes += Uint8List.fromList(...);

beep(n: n - 9, duration: duration);  // retorno descartado
return bytes;

bytes += Uint8List.fromList(...);

if (n > 9) {
  bytes += beep(n: n - 9, duration: duration);
}
return bytes;

if (isNextRow) {
  row(nextRow);  // se calcula y se tira
}

if (isNextRow) {
  bytes += row(nextRow);
}

List _getLexemes(String text) {
  ...
  bool curLexemeChinese = _isChinese(text[0]);
  ...
}

List _getLexemes(String text) {
  ...
  if (text.isEmpty) {
    return <dynamic>[lexemes, isLexemeChinese];
  }
  bool curLexemeChinese = _isChinese(text[0]);
  ...
}

final dynamic maxInput = 256 << (bytesNb * 8) - 1;

final dynamic maxInput = (256 << (bytesNb * 8)) - 1;

if (realCharactersNb > maxCharactersNb) {
  final Uint8List encodedToPrintNextRow =
      encodedToPrint.sublist(maxCharactersNb);
  encodedToPrint = encodedToPrint.sublist(0, maxCharactersNb);
  isNextRow = true;

  nextRow.add(PosColumn(
    textEncoded: encodedToPrintNextRow,
    width: cols[i].width,
    styles: cols[i].styles));

  bytes += _text(encodedToPrint, ...);
}

dstW ??= (dst.width < src.width)
    ? dstW = dst.width
    : src.width;

dstW ??= (dst.width < src.width)
    ? dst.width
    : src.width;

while (remaining > 0) {
  ...
  BOOL ok = WriteFile(hUsb_, ptr, remaining, &bytes_written, &overlapped);
  ...
  if (bytes_written == 0) return false;
  ptr += bytes_written;
  remaining -= bytes_written;
}

std::wstring target(
  device_instance_id.begin(),
  device_instance_id.end());

int sizeNeeded = MultiByteToWideChar(
  CP_UTF8, 0,
  device_instance_id.c_str(), -1,
  NULL, 0);
std::vector<wchar_t> buf(sizeNeeded);
MultiByteToWideChar(CP_UTF8, 0,
  device_instance_id.c_str(), -1,
  buf.data(), sizeNeeded);
std::wstring target(buf.data());

07Plugin · archivos parcheados

Cada archivo lleva los IDs de hallazgo aplicados como comentario // FIX #N in-line. Reemplazo directo del archivo original — no son diffs incrementales.

08App · mapa de bugs por capa

Las 6 capas que atraviesa un byte desde el evento de UI hasta el cabezal térmico, con los IDs de fix ubicados donde efectivamente viven en el código de la app. Los fixes del plugin nativo (sección 07) son externos a este árbol.

09App · plan de remediación

Orden recomendado de ejecución. El orden combina: impacto en el síntoma observable, independencia (puede mergearse solo) y esfuerzo. Cada fix es atómico y se valida contra los pasos de la sección 06.

1. Habilitar closeUsbPort() y closeSerialPort() Causa A · descomentar la llamada al plugin en _safeClose*Port, garantizar cierre antes de cada open, alinear logs con la realidad. Pequeño y desbloquea recuperación sin reiniciar.
   P0 #A1 + #A2
2. Short-circuit en connect() cuando es el mismo device Mi #A4 · si _currentConfig?.devicePath == config.devicePath, retornar true sin re-abrir. Hacerlo en el mismo PR de #1 porque viven en la misma función.
   P0 #A4
3. SerialPrinterService.sendRawBytes debe usar sendCommandToSerial Mi #A3 · hoy llama a sendCommandToUsb por error. Si tu flota tiene aunque sea una térmica por RS-232, es bloqueante. Si todas son USB, podés bajar a P1.
   P0 #A3
4. Detección de modelo + lectura de papel en T20IIIL Causa C · matchear por VID/PID en detectModel (o pedirlo a la UI). Replicar la lectura de paperResponse del RPT008 al TM-T20IIIL. Eliminar el hasPaper:true forzado.
   P0 Causa C
5. Confirmar estado tras enviar Causa D · al final del envío, releer DLE EOT y emitir PrintStatus.success sólo con isOnline && hasPaper && !hasError. Si no, PrintStatus.error.
   P0 Causa D
6. Idempotencia por voucher Causa B · tag único por voucher, registro de "intentos enviados / confirmados". El reconnect no debe reenviar vouchers ya aceptados-y-confirmados. Sin esto, el bucle de duplicados sigue siendo posible.
   P0 Causa B
7. Timeouts en lecturas y envíos P1 ayer · envolver readStatusUsb y sendCommandToUsb con .timeout(). Tratar timeout como no-listo / error, no como éxito.
   P1 Timeouts
8. testConnection respeta conexión activa Mi #A5 · si hay conexión activa, no tocar handles — sólo verificar en la lista de devices. Sin esto, un "test" rompe la conexión real.
   P1 #A5
9. Invalidación del cache de devices en errores Mi #A8 · cuando la comunicación falla, marcar el cache de getUsbPrinters como vencido para que la próxima detección de presencia consulte fresco.
   P1 #A8
10. Logs que no mientan P2 · "Puerto USB cerrado correctamente" se loguea hoy aunque el close esté comentado. Después del fix #1 el log se vuelve verdadero; mientras tanto, ajustar texto.
    P2 #A11
11. Limpiar dead code y leaks menores P2 · spin-wait que no espera nada, clearPrintMessage inconsistente, PrinterStatusHandler sin listenWhen (no se usa), suscripción colgada en build_vale_listener.
    P2 Higiene
12. Instancia única del plugin P2 · pasar el mismo TiPrinterPlugin a USB y Serial services para que sea claro que comparten estado nativo. Cosmético.
    P2 #A9

10App · fixes detallados

Cada fix tiene contexto, ubicación exacta, código antes / después e impacto operativo. Los snippets están reducidos al diff mínimo; el archivo entero queda inalterado en lo demás.

Future<void> _safeCloseUsbPort() async {
  if (_currentConfig == null) return;

  try {
    // await _plugin.closeUsbPort();
    _log('Puerto USB cerrado correctamente');
  } on Exception catch (e) {
    _log('Error al cerrar puerto USB (ignorado): $e');
  }
}

Future<void> _safeCloseUsbPort() async {
  if (_currentConfig == null) return;

  try {
    final ok = await _plugin.closeUsbPort();
    _log('closeUsbPort -> $ok');
  } catch (e) {
    _log('Error al cerrar puerto USB (ignorado): $e');
  }
}

try {
  _log('Conectando a: ${config.devicePath}');

  // Short-circuit: si ya estamos conectados a este mismo device, OK.
  if (_currentConfig?.devicePath == config.devicePath) {
    _log('Ya conectado a este dispositivo, OK sin re-abrir');
    return true;
  }

  // Cerrar conexión previa si es distinto device
  await _safeCloseUsbPort();
  _currentConfig = null;
  _interpreter = null;

  final success = await _plugin.openUsbPort(config.devicePath!);
  _log('openUsbPort -> $success');
  // ... resto idéntico
}

try {
  // Nota: ti_printer_plugin puede no tener método
  // específico para serial
  final payload = data is Uint8List
      ? data
      : Uint8List.fromList(data);
  final success = await _plugin.sendCommandToUsb(payload);
  return success ?? false;
}

try {
  final payload = data is Uint8List
      ? data
      : Uint8List.fromList(data);
  final success = await _plugin.sendCommandToSerial(payload);
  return success ?? false;
}

static PrinterModel? detectModel(String? devicePath, String? displayName) {
  if (devicePath == null && displayName == null) return null;

  final searchStr = '${devicePath ?? ''} ${displayName ?? ''}'.toLowerCase();

  // Match por VID/PID (Windows USB InstanceID o /sys/.../idVendor)
  // Epson TM-T20III* → VID_04B8 PID_0E28 (familia)
  if (searchStr.contains('vid_04b8')) {
    if (searchStr.contains('pid_0202')) return PrinterModel.tmT88V;
    if (searchStr.contains('pid_0e28')) return PrinterModel.tmT20IIIL;
    // Otros TM Epson — extender según hardware real
  }
  // 3nstar RPT008 — VID_0FE6 PID_811E (verificar con tu hardware)
  if (searchStr.contains('vid_0fe6') && searchStr.contains('pid_811e')) {
    return PrinterModel.rpt008;
  }

  // Matchers por nombre (mantener compat)
  if (searchStr.contains('rpt008') || searchStr.contains('3nstar')) {
    return PrinterModel.rpt008;
  }
  // ... resto idéntico

  return null;
}

PrinterStatus interpret(
  Uint8List onlineResponse,
  Uint8List paperResponse,
  Uint8List offlineResponse,
) {
  // ... interpret online + offline como hoy ...

  // FIX 4b: leer DLE EOT 4 en lugar de devolver withLimitedSensors()
  bool hasPaper = true;
  bool paperNearEnd = false;

  if (paperResponse.isNotEmpty) {
    final b = paperResponse[0];
    paperNearEnd = (b & 0x20) != 0;
    final paperEnd = (b & 0x40) != 0;
    hasPaper = !paperEnd;
  } else {
    // Sin respuesta: marcar como no-listo, NO como hasPaper=true
    hasPaper = false;
  }

  return PrinterStatus(
    isOnline: isOnline,
    hasPaper: hasPaper,
    paperNearEnd: paperNearEnd,
    isCoverOpen: isCoverOpen,
    hasError: hasError,
    rawOnline: onlineResponse,
    rawPaper: paperResponse,
    rawOffline: offlineResponse,
    model: PrinterModel.tmT20IIIL,
  );
}

// 4.4. Enviar datos a impresora
_log('🖨️ Print: enviando ${data.length} bytes...');
final sentOk = await _printerService.sendRawData(data);

if (!sentOk) {
  emit(state.copyWith(
    printStatus: PrintStatus.error,
    printMessage: 'No se pudo enviar el recibo a la impresora',
  ));
  return;
}

// 4.5. NUEVO: confirmar que efectivamente imprimió
// Pequeño delay para que la impresora procese antes de re-leer
await Future.delayed(const Duration(milliseconds: 300));

final postStatus = await _printerService.checkStatus();

if (postStatus.isReadyToPrint) {
  _log('✅ Print: confirmado');
  emit(state.copyWith(
    printStatus: PrintStatus.success,
    printMessage: '${event.type.name} impreso',
  ));
} else {
  _log('⚠️ Print: bytes enviados pero estado no-listo tras envío');
  emit(state.copyWith(
    printStatus: PrintStatus.error,
    printMessage: 'Posible falla: ${postStatus.errorMessage ?? "verificar impresora"}',
  ));
}

// Nuevo modelo: VoucherJob
class VoucherJob {
  final String id;          // ID único, server-side
  final VoucherType type;
  final Uint8List bytes;
  final DateTime createdAt;
  VoucherStatus status;    // pending, sent, confirmed, failed
  int attempts;
}

// En PrinterBloc:
final Map<String, VoucherJob> _voucherJobs = {};

Future<void> _onStartPrintingVouchers(...) async {
  for (final voucher in event.vouchers) {
    // Skip vouchers ya confirmados
    final existing = _voucherJobs[voucher.id];
    if (existing?.status == VoucherStatus.confirmed) {
      _log('Voucher ${voucher.id} ya confirmado, skip');
      continue;
    }

    final job = existing ?? VoucherJob(...);
    job.status = VoucherStatus.sent;
    job.attempts++;
    _voucherJobs[voucher.id] = job;

    final sentOk = await _printerService.sendRawData(job.bytes);
    if (!sentOk) { job.status = VoucherStatus.failed; continue; }

    // Aplicar FIX 05 acá: confirmar antes de marcar
    await Future.delayed(const Duration(milliseconds: 300));
    final postStatus = await _printerService.checkStatus();

    job.status = postStatus.isReadyToPrint
        ? VoucherStatus.confirmed
        : VoucherStatus.failed;
  }
}

static const _statusReadTimeout = Duration(seconds: 1);
static const _sendTimeout = Duration(seconds: 15);

// En checkStatus():
final onlineResponse = await _plugin
  .readStatusUsb(onlineCmd)
  .timeout(_statusReadTimeout, onTimeout: () => Uint8List(0));

// En sendRawData():
final success = await _plugin
  .sendCommandToUsb(payload)
  .timeout(_sendTimeout, onTimeout: () => false);

@override
Future<bool> testConnection(PrinterConnectionConfig config) async {
  if (config.type != PrinterConnectionType.usb) return false;

  // Si hay conexión activa, no tocar handles — sólo verificar en la lista
  if (_currentConfig != null) {
    try {
      final devices = await _plugin.getUsbPrinters();
      return devices.contains(config.devicePath);
    } catch (e) {
      return false;
    }
  }

  // Sin conexión activa: abrir+cerrar es seguro
  try {
    final success = await _plugin.openUsbPort(config.devicePath!);
    if (success == true) {
      await _plugin.closeUsbPort();
      return true;
    }
    return false;
  } catch (e) {
    _log('testConnection falló: $e');
    return false;
  }
}

if (onlineResponse == null || onlineResponse.isEmpty) {
  // FIX 09: invalidar cache para forzar consulta fresca
  _lastDeviceCheck = null;

  final present = await _isDevicePresent(config.devicePath!);
  if (!present) {
    // ... resto idéntico
  }
}

_log('_safeCloseUsbPort llamado (NO-OP — close real comentado)');

class PrinterServiceFactory {
  static final _plugin = TiPrinterPlugin();

  static PrinterService create(
    PrinterConnectionType type, {
    PrinterModel? model,
  }) {
    switch (type) {
      case PrinterConnectionType.usb:
        return UsbPrinterService(plugin: _plugin, printerModel: model);
      case PrinterConnectionType.serial:
        return SerialPrinterService(plugin: _plugin, printerModel: model);
      // ...
    }
  }
}

11Orden de ejecución end-to-end

Secuencia operativa para llevar el subsistema desde el estado actual hasta el estado patcheado. El plugin ya tiene sus parches aplicados (etapas 1–4). La app necesita ejecutar las etapas 5–14 en este orden, validando cada una con la sección 12 antes de avanzar.

1. Etapa 01 · Done Plugin · capa nativa Windows patcheada handle hUsb_ inicializado · USB con FILE_FLAG_OVERLAPPED · timeouts reales en read/write · loop de escritura parcial · UTF-8 ↔ UTF-16 con MultiByteToWideChar · destructor simétrico · OVERLAPPED muerto removido del serial ti_printer_plugin/windows/ti_printer_plugin.cpp PLG-01 · 02 · 03
   PLG-15 · 19 · 21 · 22
2. Etapa 02 · Done Plugin · capa nativa Linux patcheada read_status_usb devuelve todos los bytes leídos en lugar del primero ti_printer_plugin/linux/ti_printer_plugin.cc PLG-02
3. Etapa 03 · Done Plugin · generator.dart patcheado beep recursivo · oldRrow wrap · _getLexemes guard · _intLowHigh paréntesis · dead code en row · round-trip eliminado · drawImage limpio ti_printer_plugin/lib/esc_pos_utils_platform/src/generator.dart PLG-06 · 07 · 09
   PLG-10 · 11 · 12 · 13
4. Etapa 04 · Done Plugin · qrcode.dart patcheado pL/pH calculados con split de 16 bits — soporta payloads > 252 bytes · utf8.encode en lugar de latin1.encode ti_printer_plugin/lib/esc_pos_utils_platform/src/qrcode.dart PLG-04 · 05
5. Etapa 05 · P0 App · habilitar cierre real del puerto USB Descomentar _plugin.closeUsbPort() en _safeCloseUsbPort. Esto desbloquea el resto del trabajo: sin esto, los fixes posteriores no pueden recuperarse de errores transitorios. lib/services/printer/usb_printer_service.dart:343–352 APP-01 · Causa A
6. Etapa 06 · P0 App · short-circuit en connect() para mismo device En el mismo PR que la etapa 05. Evita el ERROR_SHARING_VIOLATION al reconectar a una impresora ya conectada. lib/services/printer/usb_printer_service.dart:132–144 APP-02 · #A4
7. Etapa 07 · P0 App · serial usa sendCommandToSerial Si tu flota tiene aunque sea una terminal RS-232, hoy no imprime. Descomentar también el closeSerialPort. lib/services/printer/serial_printer_service.dart:230–235 + 292–303 APP-03 · #A3
8. Etapa 08 · P0 App · interpreter T20IIIL aprende a leer el papel Replicar la lectura de DLE EOT 4 del RPT008 al T20IIIL. Eliminar hasPaper:true forzado. Matchear modelo por VID/PID en el factory. lib/models/printer/tmt20iiil_status_interpreter.dart + status_interpreter_factory.dart APP-04 · Causa C
9. Etapa 09 · P0 App · confirmar estado tras enviar Releer DLE EOT después del send. Emitir PrintStatus.success sólo con confirmación. Aplicar en print único y en el loop de vouchers. lib/viewmodels/printer/printer_bloc.dart:1407–1430 + 1690–1720 APP-05 · Causa D
10. Etapa 10 · P0 App · idempotencia por voucher Tag único por voucher · registro de attempts y status · skip de vouchers ya confirmed en reintentos. Requiere coordinar IDs con el backend. lib/viewmodels/printer/printer_bloc.dart:1646–1730 APP-06 · Causa B
11. Etapa 11 · P1 App · timeouts en lecturas y envíos Envolver readStatusUsb y sendCommandToUsb con .timeout() del lado Dart. Defensa en profundidad sobre los timeouts del plugin (etapa 01). lib/services/printer/usb_printer_service.dart APP-07
12. Etapa 12 · P1 App · testConnection respeta conexión activa Si hay _currentConfig, no tocar handles — sólo verificar en la lista. lib/services/printer/usb_printer_service.dart:301–318 + serial:246–268 APP-08 · #A5
13. Etapa 13 · P1 App · invalidación de cache de devices en fallas Cuando comm falla, marcar el cache de getUsbPrinters como vencido para que la próxima detección de presencia consulte fresco. lib/services/printer/usb_printer_service.dart:354–376 APP-09 · #A8
14. Etapa 14 · P2 App · higiene Logs que no mienten · spin-wait fake · clearPrintMessage inconsistente · listener leak · withLimitedSensors deprecation · instancia única del plugin. Varios archivos en lib/services/printer/ y lib/viewmodels/printer/ APP-10 · 11 · 12

Estimado: etapa 05 = 30 minutos · etapas 06–07 = 1–2 horas c/u · etapa 08 = medio día (requiere verificación con hardware real de cada modelo) · etapa 09 = 1 día (refactor + tests) · etapa 10 = 2–3 días (diseño de modelo + persistencia + coordinación con backend) · etapas 11–14 = 1 día total.

12Verificación end-to-end

Pruebas de campo + tests unitarios para validar cada P0. El proyecto está en Strict TDD — cada fix arranca con un test que falla, después se implementa, después se verifica el verde.

Para los tests del BLoC, mockear PrinterService via MockPrinterService que ya existe en test/. Para los del interpreter, usar bytes raw fabricados en el test.