王明 / Food-Labeling-Management-Platform

  import { blePairRequiresWriteNoResponse } from '../bleWriteModeRules'
  import {
    clearPrinter,
    ensureBleUartNotifyIfNeeded,
    getBluetoothConnection,
    getCurrentPrinterDriverKey,
    getPrinterType,
    getStoredUposPrintOptions,
    isNativeBaseClassicBluetoothTransport,
    sendToPrinter,
    setBluetoothConnection,
    setBuiltinPrinter,
  } from '../printerConnection'
  // @ts-ignore - js bridge module (app-plus only)
  import classicBluetooth from '../bluetoothTool.js'
  import { rasterizeImageData, rasterizeImageForPrinter } from '../imageRaster'
  import { buildEscPosImageData, buildEscPosTemplateData } from '../protocols/escPosBuilder'
  import { buildTscImageData, buildTscTemplateData } from '../protocols/tscProtocol'
  import type { LabelPrintJobPayload } from '../../labelPreview/buildLabelPrintPayload'
  import {
    connectNativeFastPrinter as connectNativeFastPrinterPlugin,
    disconnectNativeFastPrinter as disconnectNativeFastPrinterPlugin,
    isNativeFastPrinterAvailable,
    printNativeFastFromLabelPrintJob,
    printNativeFastTemplate as printNativeFastTemplatePlugin,
  } from '../nativeFastPrinter'
  import {
    getLabelPrintRasterLayout,
    renderLabelPreviewCanvasImageDataForPrint,
    renderLabelPreviewCanvasToTempPathForPrint,
  } from '../../labelPreview/renderLabelPreviewCanvas'
  import { storedValueLooksLikeImagePath } from '../../resolveMediaUrl'
  import { printRunDiag } from '../printRunDiagnostics'
  import { adaptSystemLabelTemplate } from '../systemTemplateAdapter'
  import { hydrateSystemTemplateImagesForPrint } from '../hydrateTemplateImagesForPrint'
  import { TEST_PRINT_SYSTEM_TEMPLATE, TEST_PRINT_TEMPLATE_DATA } from '../templates/testPrintTemplate'
  import { describePrinterCandidate, getPrinterDriverByKey, resolvePrinterDriver } from './driverRegistry'
  import type {
    CurrentPrinterSummary,
    LabelPrintPayload,
    LabelTemplateData,
    RawImageDataSource,
    PrintImageOptions,
    PrinterCandidate,
    PrinterDriver,
    StructuredLabelTemplate,
    SystemLabelTemplate,
  } from '../types/printer'
  
  type LastImagePrintDebug = {
    protocol: string
    rasterWidth: number
    rasterHeight: number
    blackPixels: number
    totalPixels: number
    blackRatio: number
    commandBytes: number
    updatedAt: number
  }
  
  let lastImagePrintDebug: LastImagePrintDebug | null = null
  
  export function getLastImagePrintDebug (): LastImagePrintDebug | null {
    return lastImagePrintDebug
  }
  
  function getPrinterTypeDisplayName (type: '' | 'bluetooth' | 'builtin'): string {
    if (type === 'bluetooth') return 'Bluetooth'
    if (type === 'builtin') return 'Built-in'
    return ''
  }
  
  function connectClassicBluetooth (device: PrinterCandidate, driver: PrinterDriver): Promise<void> {
    return new Promise((resolve, reject) => {
      // #ifdef APP-PLUS
      /**
       * 一体机 / Virtual BT / d320fax：在已集成 native-fast-printer（安卓基座 AAR）时优先走佳博 SDK 连接；
       * 不再强制仅用 JS 经典蓝牙，否则光栅大包易超时，且与「走基座」需求不符。
       * gp-d320fx、ESC 等仍走通用 socket。
       */
      const shouldUseGenericClassicOnly =
        driver.key === 'gp-d320fx' ||
        driver.key === 'generic-tsc' ||
        driver.protocol === 'esc'
  
      const connectClassicSocketFallback = () => {
        try {
          if (!classicBluetooth || typeof classicBluetooth.connDevice !== 'function') {
            reject(new Error('Classic Bluetooth fallback is not available.'))
            return
          }
          classicBluetooth.connDevice(device.deviceId, (ok: boolean) => {
            if (ok) {
              setBluetoothConnection({
                deviceId: device.deviceId,
                deviceName: device.name || 'Bluetooth Printer',
                deviceType: 'classic',
                transportMode: 'generic',
                driverKey: driver.key,
                mtu: driver.preferredBleMtu || 20,
              })
              /**
               * connDevice 回调 ok 可能早于 socket/outputStream 就绪；
               * 若立刻测试打印，会出现 state=idle、outputReady=false。
               */
              const start = Date.now()
              const poll = () => {
                const st = typeof classicBluetooth.getDebugState === 'function'
                  ? classicBluetooth.getDebugState()
                  : null
                const ready = !!st?.outputReady && (!!st?.socketConnected || String(st?.connectionState || '').toLowerCase() === 'connected')
                if (ready) {
                  resolve()
                  return
                }
                if (Date.now() - start > 2500) {
                  reject(new Error('Classic Bluetooth connection is not ready'))
                  return
                }
                setTimeout(poll, 120)
              }
              poll()
              return
            }
            const message = typeof classicBluetooth.getLastError === 'function'
              ? classicBluetooth.getLastError()
              : ''
            reject(new Error(message || 'Classic Bluetooth connection failed.'))
          })
        } catch (error: any) {
          reject(error instanceof Error ? error : new Error(String(error || 'Classic Bluetooth connection failed.')))
        }
      }
  
      if (!shouldUseGenericClassicOnly && isNativeFastPrinterAvailable()) {
        connectNativeFastPrinterPlugin({
          deviceId: device.deviceId,
          deviceName: device.name || 'Bluetooth Printer',
        }).then(() => {
          setBluetoothConnection({
            deviceId: device.deviceId,
            deviceName: device.name || 'Bluetooth Printer',
            deviceType: 'classic',
            transportMode: 'native-plugin',
            driverKey: driver.key,
            mtu: driver.preferredBleMtu || 20,
          })
          resolve()
        }).catch((error: any) => {
          if (driver.key === 'd320fax') {
            connectClassicSocketFallback()
            return
          }
          reject(error instanceof Error ? error : new Error(String(error || 'Classic Bluetooth connection failed.')))
        })
        return
      }
      if (driver.key === 'd320fax' || shouldUseGenericClassicOnly) {
        connectClassicSocketFallback()
        return
      }
      reject(new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.'))
      // #endif
      // #ifndef APP-PLUS
      reject(new Error('Classic Bluetooth requires the app.'))
      // #endif
    })
  }
  
  /**
   * 优先带响应 write（与 uni 默认写入方式一致）；仅当没有 write 再用 writeNoResponse（需在下发时传 writeType）。
   * 若系统 GATT 只声明 write、未声明 writeNoResponse，却强行 writeNoResponse，会报 property not support (10007)。
   */
  function hasBleWriteProperty (item: any): boolean {
    const w = item.properties?.write
    return w === true || w === 'true'
  }
  
  function hasBleWriteNoResponseProperty (item: any): boolean {
    const p = item.properties || {}
    return (
      p.writeNoResponse === true ||
      p.writeNoResponse === 'true' ||
      p.writeWithoutResponse === true ||
      p.writeWithoutResponse === 'true'
    )
  }
  
  /**
   * 无 writeNoResponse 属性则绝不走 Command 写。
   * Nordic 白名单在「同时声明 write + writeNoResponse」时优先无响应写（佳博等实测）；否则有 write 时优先带响应。
   */
  function pickBleWriteUsesNoResponse (serviceId: string, item: any): boolean {
    const hw = hasBleWriteProperty(item)
    const hn = hasBleWriteNoResponseProperty(item)
    if (!hn) return false
    if (!hw) return true
    return blePairRequiresWriteNoResponse(serviceId, String(item.uuid || ''))
  }
  
  function findBleWriteCharacteristic (deviceId: string): Promise<{
    serviceId: string
    characteristicId: string
    bleWriteUsesNoResponse: boolean
  } | null> {
    return new Promise((resolve) => {
      uni.getBLEDeviceServices({
        deviceId,
        success: (serviceRes) => {
          const services = serviceRes.services || []
          const next = (index: number) => {
            if (index >= services.length) {
              resolve(null)
              return
            }
            const serviceId = services[index].uuid
            uni.getBLEDeviceCharacteristics({
              deviceId,
              serviceId,
              success: (charRes) => {
                const chars = charRes.characteristics || []
                const writable = (item: any) => hasBleWriteProperty(item) || hasBleWriteNoResponseProperty(item)
                for (const item of chars) {
                  const cid = String(item.uuid || '')
                  if (blePairRequiresWriteNoResponse(serviceId, cid) && writable(item)) {
                    resolve({
                      serviceId,
                      characteristicId: cid,
                      bleWriteUsesNoResponse: pickBleWriteUsesNoResponse(serviceId, item),
                    })
                    return
                  }
                }
                const withResp = chars.find(hasBleWriteProperty)
                const noResp = chars.find(hasBleWriteNoResponseProperty)
                const target = withResp || noResp
                if (target) {
                  resolve({
                    serviceId,
                    characteristicId: String(target.uuid || ''),
                    bleWriteUsesNoResponse: pickBleWriteUsesNoResponse(serviceId, target),
                  })
                  return
                }
                next(index + 1)
              },
              fail: () => next(index + 1),
            })
          }
          next(0)
        },
        fail: () => resolve(null),
      })
    })
  }
  
  function requestBleMtu (deviceId: string, preferredMtu: number): Promise<number> {
    return new Promise((resolve) => {
      const targetMtu = Math.max(20, Math.min(512, Math.round(preferredMtu || 20)))
      if (targetMtu <= 20 || typeof (uni as any).setBLEMTU !== 'function') {
        resolve(20)
        return
      }
      let settled = false
      const done = (value: number) => {
        if (settled) return
        settled = true
        clearTimeout(timer)
        resolve(Math.max(20, Math.round(value || 20)))
      }
      const timer = setTimeout(() => done(20), 3000)
      ;(uni as any).setBLEMTU({
        deviceId,
        mtu: targetMtu,
        success: (res: any) => done(Number(res?.mtu) || targetMtu),
        fail: () => done(20),
      })
    })
  }
  
  function connectBlePrinter (device: PrinterCandidate, driver: PrinterDriver): Promise<void> {
    const finalizeExistingBleConnection = async () => {
      const write = await findBleWriteCharacteristic(device.deviceId)
      if (!write) {
        throw new Error('No writable characteristic found. This device may not support printing.')
      }
      await ensureBleUartNotifyIfNeeded(device.deviceId, write.serviceId, write.characteristicId)
      const negotiatedMtu = await requestBleMtu(device.deviceId, driver.preferredBleMtu || 20)
      setBluetoothConnection({
        deviceId: device.deviceId,
        deviceName: device.name || 'Bluetooth Printer',
        serviceId: write.serviceId,
        characteristicId: write.characteristicId,
        deviceType: 'ble',
        mtu: negotiatedMtu,
        driverKey: driver.key,
        bleWriteUsesNoResponse: write.bleWriteUsesNoResponse,
      })
    }
  
    return new Promise((resolve, reject) => {
      uni.createBLEConnection({
        deviceId: device.deviceId,
        timeout: 10000,
        success: async () => {
          try {
            await finalizeExistingBleConnection()
            resolve()
          } catch (e: any) {
            reject(e)
          }
        },
        fail: (err: any) => {
          if (err?.errCode === -1) {
            finalizeExistingBleConnection().then(() => resolve()).catch(reject)
          } else {
            reject(new Error(err?.errMsg || 'BLE connection failed.'))
          }
        },
      })
    })
  }
  
  export async function connectBluetoothPrinter (device: PrinterCandidate): Promise<PrinterDriver> {
    const driver = resolvePrinterDriver(device)
    if (driver.key === 'gp-d320fx') {
      try {
        await connectBlePrinter(device, driver)
      } catch (_) {
        await connectClassicBluetooth(device, driver)
      }
      return driver
    }
    const resolvedType = driver.resolveConnectionType(device)
    if (resolvedType === 'classic') {
      await connectClassicBluetooth(device, driver)
    } else {
      await connectBlePrinter(device, driver)
    }
    return driver
  }
  
  export function useBuiltinPrinter (driverKey = 'generic-tsc') {
    setBuiltinPrinter(driverKey)
  }
  
  export function getCurrentPrinterDriver (): PrinterDriver {
    const type = getPrinterType()
    const storedKey = getCurrentPrinterDriverKey()
    if (storedKey) return getPrinterDriverByKey(storedKey)
    if (type === 'bluetooth') {
      const connection = getBluetoothConnection()
      if (connection) {
        return resolvePrinterDriver({
          deviceId: connection.deviceId,
          name: connection.deviceName,
          type: connection.deviceType,
        })
      }
    }
    if (type === 'builtin') {
      return getPrinterDriverByKey('generic-tsc')
    }
    return getPrinterDriverByKey('generic-tsc')
  }
  
  export function getCurrentPrinterSummary (): CurrentPrinterSummary {
    const type = getPrinterType()
    const driver = getCurrentPrinterDriver()
    if (type === 'builtin') {
      return {
        type,
        displayName: getPrinterTypeDisplayName(type),
        deviceId: 'builtin',
        driverKey: driver.key,
        driverName: driver.displayName,
        protocol: driver.protocol,
        deviceType: '',
      }
    }
    if (type === 'bluetooth') {
      const connection = getBluetoothConnection()
      if (connection) {
        return {
          type,
          displayName: getPrinterTypeDisplayName(type),
          deviceId: connection.deviceId,
          driverKey: driver.key,
          driverName: driver.displayName,
          protocol: driver.protocol,
          deviceType: connection.deviceType,
        }
      }
    }
    return {
      type: '',
      displayName: '',
      deviceId: '',
      driverKey: driver.key,
      driverName: driver.displayName,
      protocol: driver.protocol,
      deviceType: '',
    }
  }
  
  /**
   * 内置 UPOS 的 `printNormal` 按「原始字节」打出；多数一体机机芯为 ESC/POS 通道，下发 TSPL 会被当成普通字符印在纸上（与预览 JSON 不符）。
   * 内置一律不走原生 TSPL printTemplate，改走预览同源 Canvas → PNG → ESC 光栅（resolveRasterPrintDriver 映射 generic-esc）。
   */
  function canUseBuiltinNativeFastTemplatePrint (): boolean {
    return false
  }
  
  function canUseNativeFastTemplatePrint (driver: PrinterDriver): boolean {
    if (driver.protocol !== 'tsc' || !isNativeFastPrinterAvailable()) return false
    if (isNativeBaseClassicBluetoothTransport()) return true
    return canUseBuiltinNativeFastTemplatePrint()
  }
  
  function templateHasQrDataForCommandPrint (template: SystemLabelTemplate): boolean {
    const elements = template.elements || []
    for (const el of elements) {
      const type = String(el.type || '').toUpperCase()
      if (type !== 'QRCODE') continue
      const cfg = (el.config || {}) as Record<string, unknown>
      const raw = String(
        cfg.data ?? cfg.Data ?? cfg.value ?? cfg.Value ?? cfg.src ?? cfg.Src ?? cfg.url ?? cfg.Url ?? '',
      ).trim()
      if (!raw) continue
      if (storedValueLooksLikeImagePath(raw)) continue
      return true
    }
    return false
  }
  
  function templateHasUnsupportedElementsForCommandPrint (template: SystemLabelTemplate): boolean {
    const elements = template.elements || []
    for (const el of elements) {
      const type = String(el.type || '').toUpperCase()
      if (type.startsWith('TEXT_')) continue
      if (
        type === 'WEIGHT'
        || type === 'DATE'
        || type === 'TIME'
        || type === 'DURATION'
        || type === 'NUTRITION'
        || type === 'QRCODE'
        || type === 'BARCODE'
        || type === 'IMAGE'
        || type === 'BLANK'
      ) {
        continue
      }
      return true
    }
    return false
  }
  
  /** 预览/业务侧：是否可走 native-fast-printer 的 printTemplate（templateJson + dataJson） */
  export function canPrintCurrentLabelViaNativeFastJob (): boolean {
    return canUseNativeFastTemplatePrint(getCurrentPrinterDriver())
  }
  
  /**
   * 整页标签光栅是否一律走 canvasGetImageData（纯 JS 二值化），而不用「PNG → Bitmap.getPixels → readJavaIntArrayValue」。
   * 内置 UPOS 一体机在部分 Uni 基座上 int[] 桥接读数恒为 0 → black=0、长时间重试/超时；所有 **打印机类型选内置** 的机型统一走本路径。
   * 若以后需按 Android 型号再细分，只改此函数即可。
   */
  export function shouldRasterPrintViaCanvasImageData (): boolean {
    return getPrinterType() === 'builtin'
  }
  
  /**
   * 将 buildLabelPrintJobPayload / getLastLabelPrintJobPayload 同构数据送入原生 printTemplate；
   * 与 JSON.stringify(payload.template) + JSON.stringify(payload.printInputJson) 一致。
   */
  export async function printLabelPrintJobPayloadForCurrentPrinter (
    payload: LabelPrintJobPayload,
    options: { printQty?: number } = {},
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const connection = getBluetoothConnection()
    if (
      driver.protocol === 'tsc'
      && connection?.deviceType === 'classic'
      && connection?.transportMode === 'native-plugin'
      && !isNativeFastPrinterAvailable()
    ) {
      throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
    }
    if (!canUseNativeFastTemplatePrint(driver)) {
      throw new Error('Native fast template print is not available for the current printer.')
    }
    const printQty = Math.max(1, options.printQty ?? payload.meta?.printQuantity ?? 1)
    if (canUseBuiltinNativeFastTemplatePrint()) {
      const upos = getStoredUposPrintOptions()
      await printNativeFastFromLabelPrintJob({
        deviceId: 'builtin-upos',
        deviceName: 'Built-in',
        payload,
        dpi: driver.imageDpi || 203,
        printQty,
        outputTransport: 'upos',
        uposPrefer: upos.prefer,
        uposSerialPath: upos.serialPath || '',
        uposBaudrate: upos.baudrate,
      })
      if (onProgress) onProgress(100)
      return driver
    }
    const nativeConnection = getNativeClassicConnection()
    if (!nativeConnection) {
      throw new Error('Native classic Bluetooth connection is not ready.')
    }
    await printNativeFastFromLabelPrintJob({
      deviceId: nativeConnection.deviceId,
      deviceName: nativeConnection.deviceName,
      payload,
      dpi: driver.imageDpi || 203,
      printQty,
    })
    if (onProgress) onProgress(100)
    return driver
  }
  
  function getNativeClassicConnection () {
    const connection = getBluetoothConnection()
    if (!connection || connection.deviceType !== 'classic' || connection.transportMode !== 'native-plugin') return null
    return connection
  }
  
  /**
   * 连接自检用测试页；**不要**在此处调用 `postUsAppLabelPrint` / 接口 9（仅预览页业务打印落库）。
   */
  export async function testPrintCurrentPrinter (onProgress?: (percent: number) => void): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const connection = getBluetoothConnection()
    if (
      driver.protocol === 'tsc'
      && connection?.deviceType === 'classic'
      && connection?.transportMode === 'native-plugin'
      && !isNativeFastPrinterAvailable()
    ) {
      throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
    }
    if (canUseNativeFastTemplatePrint(driver)) {
      if (canUseBuiltinNativeFastTemplatePrint()) {
        const upos = getStoredUposPrintOptions()
        await printNativeFastTemplatePlugin({
          deviceId: 'builtin-upos',
          deviceName: 'Built-in',
          template: TEST_PRINT_SYSTEM_TEMPLATE,
          data: TEST_PRINT_TEMPLATE_DATA,
          dpi: driver.imageDpi || 203,
          printQty: 1,
          outputTransport: 'upos',
          uposPrefer: upos.prefer,
          uposSerialPath: upos.serialPath || '',
          uposBaudrate: upos.baudrate,
        })
        if (onProgress) onProgress(100)
        return driver
      }
      const nativeConnection = getNativeClassicConnection()
      if (nativeConnection) {
        await printNativeFastTemplatePlugin({
          deviceId: nativeConnection.deviceId,
          deviceName: nativeConnection.deviceName,
          template: TEST_PRINT_SYSTEM_TEMPLATE,
          data: TEST_PRINT_TEMPLATE_DATA,
          dpi: driver.imageDpi || 203,
          printQty: 1,
        })
        if (onProgress) onProgress(100)
        return driver
      }
    }
  
    // d320fax 在部分安卓设备上经 sendToPrinter Promise 链会无回调卡住；测试页走经典蓝牙直发更稳定。
    if (driver.key === 'd320fax' && connection?.deviceType === 'classic') {
      // #ifdef APP-PLUS
      try {
        const payload = driver.buildTestPrintData().map((byte) => {
          const v = byte & 0xff
          return v >= 128 ? v - 256 : v
        })
        if (onProgress) onProgress(10)
        /**
         * 部分设备会出现“连接状态看似为 connected，但实际输出流不可写”的假连接。
         * 测试打印前强制重连一次 classic socket，确保 btOutStream 新鲜可用。
         */
        await new Promise<void>((resolve, reject) => {
          if (typeof classicBluetooth?.connDevice !== 'function') {
            reject(new Error('D320FAX_CLASSIC_CONN_API_MISSING'))
            return
          }
          let done = false
          const timer = setTimeout(() => {
            if (done) return
            done = true
            reject(new Error('D320FAX_CLASSIC_RECONNECT_TIMEOUT'))
          }, 8000)
          try {
            classicBluetooth.connDevice(connection.deviceId, (ok: boolean) => {
              if (done) return
              done = true
              clearTimeout(timer)
              if (ok) resolve()
              else reject(new Error(classicBluetooth.getLastError?.() || 'D320FAX_CLASSIC_RECONNECT_FAILED'))
            })
          } catch (e: any) {
            if (done) return
            done = true
            clearTimeout(timer)
            reject(e instanceof Error ? e : new Error(String(e || 'D320FAX_CLASSIC_RECONNECT_EXCEPTION')))
          }
        })
        if (typeof classicBluetooth?.ensureConnection === 'function') {
          classicBluetooth.ensureConnection(connection.deviceId)
        }
        if (onProgress) onProgress(30)
        const ok = await new Promise<boolean>((resolve) => {
          let done = false
          const timer = setTimeout(() => {
            if (done) return
            done = true
            resolve(false)
          }, 10000)
          try {
            if (typeof classicBluetooth?.sendByteDataAsync === 'function') {
              const started = classicBluetooth.sendByteDataAsync(payload, (sendOk: boolean) => {
                if (done) return
                done = true
                clearTimeout(timer)
                resolve(!!sendOk)
              })
              if (started === false) {
                done = true
                clearTimeout(timer)
                resolve(false)
              }
              return
            }
            done = true
            clearTimeout(timer)
            resolve(false)
          } catch {
            done = true
            clearTimeout(timer)
            resolve(false)
          }
        })
        if (!ok) {
          const err = typeof classicBluetooth?.getLastError === 'function'
            ? classicBluetooth.getLastError()
            : ''
          const debug = typeof classicBluetooth?.getDebugState === 'function'
            ? classicBluetooth.getDebugState()
            : null
          const details = [
            `device=${connection.deviceId}`,
            `state=${String(debug?.connectionState || '-')}`,
            `connected=${String(!!debug?.socketConnected)}`,
            `outputReady=${String(!!debug?.outputReady)}`,
            `sendMode=${String(debug?.lastSendMode || '-')}`,
            err ? `lastError=${err}` : '',
          ].filter(Boolean).join('\n')
          throw new Error(`D320FAX_CLASSIC_SEND_TIMEOUT_OR_FAILED\n${details}`)
        }
        if (onProgress) onProgress(100)
        return driver
      } catch (e: any) {
        throw (e instanceof Error ? e : new Error(String(e || 'D320FAX_CLASSIC_SEND_EXCEPTION')))
      }
      // #endif
    }
  
    /** 内置 UPOS 同业务打印：勿发 TSC 自检页（会被当文本打出） */
    if (getPrinterType() === 'builtin') {
      await sendToPrinter(getPrinterDriverByKey('generic-esc').buildTestPrintData(), onProgress)
      return driver
    }
  
    await sendToPrinter(driver.buildTestPrintData(), onProgress)
    return driver
  }
  
  export async function printLabelForCurrentPrinter (
    payload: LabelPrintPayload,
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    await sendToPrinter(driver.buildLabelData(payload), onProgress)
    return driver
  }
  
  /**
   * 界面仍可存 generic-tsc；内置 UPOS 实际需 ESC/POS 位图，故整页光栅强制 generic-esc（与预览像素一致，避免 TSPL 当文本打出）。
   */
  export function resolveRasterPrintDriver (driver: PrinterDriver): PrinterDriver {
    if (getPrinterType() === 'builtin' && driver.protocol === 'tsc') {
      return getPrinterDriverByKey('generic-esc')
    }
    return driver
  }
  
  export async function printImageForCurrentPrinter (
    imageSource: string,
    options: PrintImageOptions = {},
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const rasterDriver = resolveRasterPrintDriver(driver)
    const printerType = getPrinterType()
    const startedAt = Date.now()
    const withStageTimeout = async <T>(promise: Promise<T>, ms: number, stage: string): Promise<T> => {
      return await new Promise<T>((resolve, reject) => {
        let settled = false
        const timer = setTimeout(() => {
          if (settled) return
          settled = true
          reject(new Error(`PRINT_STAGE_TIMEOUT:${stage}:${ms}`))
        }, ms)
        promise.then(
          (v) => {
            if (settled) return
            settled = true
            clearTimeout(timer)
            resolve(v)
          },
          (e) => {
            if (settled) return
            settled = true
            clearTimeout(timer)
            reject(e)
          }
        )
      })
    }
    console.warn(
      '[print-image] start'
      + ' printerType=' + String(printerType || '-')
      + ' driver=' + String(driver.key || '-')
      + ' rasterDriver=' + String(rasterDriver.key || '-')
      + ' source=' + String(imageSource ? 'ok' : 'empty')
    )
    printRunDiag('printImage_start', {
      printerType,
      driver: driver.key,
      rasterDriver: rasterDriver.key,
      rasterProtocol: rasterDriver.protocol,
    })
    if (onProgress) onProgress(2)
    const rasterOptions: PrintImageOptions = { ...options }
    if (onProgress) {
      const prevRasterCb = options.onRasterizeProgress
      rasterOptions.onRasterizeProgress = (sub) => {
        try {
          prevRasterCb?.(sub)
        } catch (_) {}
        onProgress(2 + Math.round((Math.min(100, Math.max(0, sub)) / 100) * 16))
      }
    }
    const rasterStart = Date.now()
    let raster = rasterDriver.protocol === 'esc'
      ? await rasterizeImageForPrinter(imageSource, rasterDriver, rasterOptions)
      : await withStageTimeout(
        rasterizeImageForPrinter(imageSource, rasterDriver, rasterOptions),
        120000,
        'rasterize'
      )
    console.warn(
      '[print-image] rasterize done'
      + ' ms=' + String(Date.now() - rasterStart)
      + ' width=' + String(raster.width)
      + ' height=' + String(raster.height)
    )
    printRunDiag('printImage_rasterize_done', {
      ms: Date.now() - rasterStart,
      w: raster.width,
      h: raster.height,
    })
    const calcBlackStats = (r: { width: number; height: number; pixels: number[] }) => {
      const totalPixels = Math.max(1, r.width * r.height)
      let blackPixels = 0
      for (let i = 0; i < r.pixels.length; i++) {
        if (r.pixels[i]) blackPixels++
      }
      const blackRatio = blackPixels / totalPixels
      return { totalPixels, blackPixels, blackRatio }
    }
  
    let { totalPixels, blackPixels, blackRatio } = calcBlackStats(raster)
  
    if (blackRatio <= 0) {
      printRunDiag('printImage_raster_retry_black0', {
        blackPixels,
        totalPixels,
        firstPassMs: Date.now() - rasterStart,
      })
      // 某些复杂模板在特定阈值/清顶行下会被二值化成“全白”。
      // 为了避免继续抛错，这里做一次失败后重光栅兜底：逐步降低 threshold，并在必要时不再清顶行。
      const tried: string[] = []
      const baseClearTop = options.clearTopRasterRows
  
      const thresholdCandidates = [150, 130, 110, 90]
      const clearTopCandidates: Array<number | undefined> = [
        baseClearTop,
        0, // 兜底：避免把内容切掉（printSystemTemplateForCurrentPrinter 里默认 clearTopRasterRows=1）
      ].filter((v, i, arr) => v !== undefined || arr.indexOf(undefined) === i)
  
      const rasterAttempts = async () => {
        for (const clearTop of clearTopCandidates) {
          for (const threshold of thresholdCandidates) {
            tried.push(`clearTop=${String(clearTop)};threshold=${threshold}`)
            /** 重试光栅勿再回调 onRasterizeProgress，否则会从 2% 重新映射，UI 像「15% 突然掉回 5%」 */
            const nextRaster = await rasterizeImageForPrinter(
              imageSource,
              rasterDriver,
              {
                ...rasterOptions,
                threshold,
                ...(typeof clearTop === 'number' ? { clearTopRasterRows: clearTop } : {}),
                onRasterizeProgress: undefined,
              },
            )
            const stats = calcBlackStats(nextRaster)
            console.warn(
              '[print-image] raster retry stats'
              + ` clearTop=${String(clearTop)}`
              + ` threshold=${threshold}`
              + ` black=${stats.blackPixels}/${stats.totalPixels}`
              + ` ratio=${stats.blackRatio.toFixed(4)}`
            )
            if (stats.blackRatio > 0) {
              raster = nextRaster
              totalPixels = stats.totalPixels
              blackPixels = stats.blackPixels
              blackRatio = stats.blackRatio
              return true
            }
          }
        }
        return false
      }
  
      const ok = await rasterAttempts()
      if (!ok) {
        throw new Error(
          `RASTER_EMPTY_IMAGE:protocol=${String(driver.protocol || '-')};size=${raster.width}x${raster.height};pixels=${blackPixels}/${totalPixels};tried=${tried.join('|')}`
        )
      }
    }
  
    let data: number[] = []
    if (rasterDriver.protocol === 'esc') {
      data = buildEscPosImageData(raster, options)
    } else {
      data = buildTscImageData(raster, options, rasterDriver.imageDpi || 203)
    }
    lastImagePrintDebug = {
      protocol: String(rasterDriver.protocol || '-'),
      rasterWidth: raster.width,
      rasterHeight: raster.height,
      blackPixels,
      totalPixels,
      blackRatio,
      commandBytes: data.length,
      updatedAt: Date.now(),
    }
    console.warn(
      '[print-image] raster-stats'
      + ' logicalDriver=' + String(driver.key || '-')
      + ' protocol=' + String(lastImagePrintDebug.protocol)
      + ' size=' + String(raster.width) + 'x' + String(raster.height)
      + ' black=' + String(blackPixels) + '/' + String(totalPixels)
      + ' ratio=' + String(blackRatio.toFixed(4))
      + ' bytes=' + String(data.length)
    )
    console.warn(
      '[print-image] build bytes done'
      + ' protocol=' + String(rasterDriver.protocol || '-')
      + ' bytes=' + String(data.length)
      + ' elapsed=' + String(Date.now() - startedAt)
    )
    printRunDiag('printImage_commands_built', {
      protocol: rasterDriver.protocol,
      commandBytes: data.length,
      elapsedMs: Date.now() - startedAt,
    })
  
    if (onProgress) onProgress(22)
    const sendStart = Date.now()
    let sendVisualProgress = 22
    let lastExternalProgressAt = Date.now()
    const reportSendProgress = (p: number) => {
      if (!onProgress) return
      const u = Math.min(100, Math.max(0, Math.round(p)))
      const mapped = 22 + Math.round((u / 100) * 78)
      if (mapped > sendVisualProgress) {
        sendVisualProgress = mapped
        onProgress(mapped)
      } else {
        lastExternalProgressAt = Date.now()
      }
    }
    const sendProgressKeepAlive = onProgress
      ? setInterval(() => {
          // 内置/部分传输链路不会持续回调进度，UI 会停在 22%；这里做轻量保活推进。
          if (Date.now() - lastExternalProgressAt < 1200) return
          if (sendVisualProgress >= 96) return
          sendVisualProgress += sendVisualProgress < 80 ? 2 : 1
          onProgress(sendVisualProgress)
        }, 800)
      : null
    printRunDiag('printImage_send_start', { bytes: data.length })
    if (rasterDriver.protocol === 'esc') {
      try {
        await sendToPrinter(data, (p) => {
          lastExternalProgressAt = Date.now()
          reportSendProgress(p)
          if (p === 0 || p === 50 || p === 100) {
            printRunDiag('printImage_send_progress', { p })
          }
        })
      } finally {
        if (sendProgressKeepAlive) clearInterval(sendProgressKeepAlive)
      }
    } else {
      try {
        await withStageTimeout(
          sendToPrinter(data, (p) => {
            lastExternalProgressAt = Date.now()
            reportSendProgress(p)
            if (p === 0 || p === 50 || p === 100) {
              printRunDiag('printImage_send_progress', { p })
            }
          }),
          180000,
          'sendToPrinter'
        )
      } finally {
        if (sendProgressKeepAlive) clearInterval(sendProgressKeepAlive)
      }
    }
    console.warn(
      '[print-image] send done'
      + ' ms=' + String(Date.now() - sendStart)
      + ' total=' + String(Date.now() - startedAt)
    )
    printRunDiag('printImage_send_done', {
      sendMs: Date.now() - sendStart,
      totalMs: Date.now() - startedAt,
    })
    if (onProgress) onProgress(100)
    return driver
  }
  
  export async function printImageDataForCurrentPrinter (
    imageData: RawImageDataSource,
    options: PrintImageOptions = {},
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const rasterDriver = resolveRasterPrintDriver(driver)
    const raster = rasterizeImageData(imageData, options)
    if (onProgress) onProgress(5)
    const data = rasterDriver.protocol === 'esc'
      ? buildEscPosImageData(raster, options)
      : buildTscImageData(raster, options, rasterDriver.imageDpi || 203)
    await sendToPrinter(data, onProgress)
    return driver
  }
  
  export async function printTemplateForCurrentPrinter (
    template: StructuredLabelTemplate,
    data: LabelTemplateData = {},
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const bytes = driver.protocol === 'esc'
      ? buildEscPosTemplateData(template, data)
      : buildTscTemplateData(template, data)
    await sendToPrinter(bytes, onProgress)
    return driver
  }
  
  /** 与预览页「整页光栅」分支一致：用同一套 canvas 绘制再下发位图（/picture/、中文、￥ 与屏幕一致） */
  export type SystemTemplatePrintCanvasRasterOptions = {
    canvasId: string
    componentInstance: any
    /** 绘制前把隐藏 canvas 的 width/height（像素）设为 layout.outW/outH，并 await nextTick */
    applyLayout?: (layout: {
      cw: number
      ch: number
      outW: number
      outH: number
      scale: number
    }) => void | Promise<void>
  }
  
  export async function printSystemTemplateForCurrentPrinter (
    template: SystemLabelTemplate,
    data: LabelTemplateData = {},
    options: {
      printQty?: number
      canvasRaster?: SystemTemplatePrintCanvasRasterOptions
    } = {},
    onProgress?: (percent: number) => void
  ): Promise<PrinterDriver> {
    const driver = getCurrentPrinterDriver()
    const rasterDriver = resolveRasterPrintDriver(driver)
    const canvasRaster = options.canvasRaster
    const bypassCanvasRasterForQr =
      !!canvasRaster
      && templateHasQrDataForCommandPrint(template)
      && !templateHasUnsupportedElementsForCommandPrint(template)
  
    if (canvasRaster && !bypassCanvasRasterForQr) {
      if (onProgress) onProgress(1)
      const maxDots =
        rasterDriver.imageMaxWidthDots || (rasterDriver.protocol === 'esc' ? 384 : 576)
      const layout = getLabelPrintRasterLayout(template, maxDots, rasterDriver.imageDpi || 203)
      if (onProgress) onProgress(4)
      if (canvasRaster.applyLayout) {
        await canvasRaster.applyLayout(layout)
      }
      if (onProgress) onProgress(7)
      await new Promise<void>((r) => setTimeout(r, 50))
      if (onProgress) onProgress(9)
      const printOpts: PrintImageOptions = {
        printQty: options.printQty || 1,
        clearTopRasterRows: 1,
        targetWidthDots: layout.outW,
        targetHeightDots: layout.outH,
      }
      const mapRasterProgress = onProgress
        ? (p: number) => {
            onProgress(12 + Math.round((Math.min(100, Math.max(0, p)) / 100) * 88))
          }
        : undefined
      /** 内置一体机：统一 canvas 取像素，避免 Bitmap int[] 桥接假 0 */
      if (shouldRasterPrintViaCanvasImageData()) {
        try {
          const imageData = await renderLabelPreviewCanvasImageDataForPrint(
            canvasRaster.canvasId,
            canvasRaster.componentInstance,
            template,
            layout,
          )
          if (onProgress) onProgress(12)
          await printImageDataForCurrentPrinter(imageData, printOpts, mapRasterProgress)
          return driver
        } catch (e) {
          console.warn('[print] builtin canvasGetImageData failed, fallback PNG→Bitmap raster', e)
        }
      }
      const tmpPath = await renderLabelPreviewCanvasToTempPathForPrint(
        canvasRaster.canvasId,
        canvasRaster.componentInstance,
        template,
        layout,
      )
      if (onProgress) onProgress(12)
      await printImageForCurrentPrinter(tmpPath, printOpts, mapRasterProgress)
      return driver
    }
  
    const connection = getBluetoothConnection()
    /**
     * d320fax + classic 历史上存在卡顿风险，这里对图片 hydration 增加总超时兜底：
     * - 成功：使用本地化后的图片路径，提高 IMAGE/QRCODE 出图概率
     * - 超时/失败：自动回退原模板，保证仍可继续出纸
     */
    if (onProgress) onProgress(1)
    const preferStableForD320faxClassic = driver.key === 'd320fax' && connection?.deviceType === 'classic'
    let templateReady = template
    if (preferStableForD320faxClassic) {
      try {
        if (onProgress) onProgress(3)
        templateReady = await Promise.race<SystemLabelTemplate>([
          hydrateSystemTemplateImagesForPrint(template),
          new Promise<SystemLabelTemplate>((resolve) => setTimeout(() => resolve(template), 8000)),
        ])
      } catch {
        templateReady = template
      }
    } else {
      if (onProgress) onProgress(3)
      templateReady = await hydrateSystemTemplateImagesForPrint(template)
    }
    if (onProgress) onProgress(12)
  
    if (
      driver.protocol === 'tsc'
      && connection?.deviceType === 'classic'
      && connection?.transportMode === 'native-plugin'
      && !isNativeFastPrinterAvailable()
    ) {
      throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
    }
    if (canUseNativeFastTemplatePrint(driver)) {
      if (canUseBuiltinNativeFastTemplatePrint()) {
        const upos = getStoredUposPrintOptions()
        await printNativeFastTemplatePlugin({
          deviceId: 'builtin-upos',
          deviceName: 'Built-in',
          template: templateReady,
          data,
          dpi: driver.imageDpi || 203,
          printQty: options.printQty || 1,
          outputTransport: 'upos',
          uposPrefer: upos.prefer,
          uposSerialPath: upos.serialPath || '',
          uposBaudrate: upos.baudrate,
        })
        if (onProgress) onProgress(100)
        return driver
      }
      const nativeConnection = getNativeClassicConnection()
      if (nativeConnection) {
        await printNativeFastTemplatePlugin({
          deviceId: nativeConnection.deviceId,
          deviceName: nativeConnection.deviceName,
          template: templateReady,
          data,
          dpi: driver.imageDpi || 203,
          printQty: options.printQty || 1,
        })
        if (onProgress) onProgress(100)
        return driver
      }
    }
  
    if (onProgress) onProgress(14)
    const structuredTemplate = adaptSystemLabelTemplate(templateReady, data, {
      dpi: driver.imageDpi || 203,
      printQty: options.printQty || 1,
      disableBitmapText: driver.key === 'gp-d320fx' || driver.key === 'd320fax',
      /**
       * d320fax 内置字库对货币符号兼容差，TEXT_PRICE 容易整段丢失。
       * 仅恢复“货币文本位图”兜底（非全量位图文本），兼顾稳定性与 ￥ 展示。
       */
      allowCurrencyBitmapWhenDisabled: true,
    })
    if (onProgress) onProgress(16)
    const bytes = driver.protocol === 'esc'
      ? buildEscPosTemplateData(structuredTemplate)
      : buildTscTemplateData(structuredTemplate)
    if (onProgress) onProgress(18)
    await sendToPrinter(bytes, (p) => {
      if (!onProgress) return
      const u = Math.min(100, Math.max(0, Math.round(p)))
      onProgress(18 + Math.round((u / 100) * 82))
    })
    if (onProgress) onProgress(100)
    return driver
  }
  
  export function describeDiscoveredPrinter (device: PrinterCandidate) {
    return describePrinterCandidate(device)
  }
  
  export function disconnectCurrentPrinter (): Promise<void> {
    return new Promise((resolve) => {
      const type = getPrinterType()
      const connection = getBluetoothConnection()
  
      if (type === 'bluetooth' && connection?.deviceType === 'classic') {
        // #ifdef APP-PLUS
        if (connection.transportMode === 'native-plugin' && isNativeFastPrinterAvailable()) {
          disconnectNativeFastPrinterPlugin().catch((e: any) => {
            console.error('Disconnect native fast printer failed', e)
          }).finally(() => {
            clearPrinter()
            resolve()
          })
          return
        }
        try {
          const classic = classicBluetooth
          if (classic && classic.disConnDevice) classic.disConnDevice()
        } catch (e) {
          console.error('Disconnect classic bluetooth failed', e)
        }
        // #endif
        clearPrinter()
        resolve()
        return
      }
  
      clearPrinter()
      if (type === 'bluetooth' && connection?.deviceId) {
        uni.closeBLEConnection({
          deviceId: connection.deviceId,
          complete: () => resolve(),
        })
        return
      }
      resolve()
    })
  }