package com.unibuy.smartdevice.tools;

import java.io.IOException;

/**
 * 現金收銀機（MDB232 轉換盒）傳輸層共用介面。
 *
 * <p>目標機台的收銀轉換盒可透過三種方式接線：USB、Com Port 3、ttyS9。
 * 前者由 {@link SimpleCashAcceptorHandler}（USB 笨管道）實作，後兩者由
 * {@link SerialCashAcceptorHandler}（串口 Modbus，可傳入 /dev 埠路徑）實作。
 * 消費端一律透過此介面操作，由 {@link CashAcceptorFactory} 依使用者在系統設定頁
 * 選擇的連線方式決定實體。</p>
 *
 * <p>方法簽章刻意與既有 USB handler 完全一致，讓 CashPayDialogGeneral /
 * CashPayoutManager 幾乎零改動即可切換底層傳輸。</p>
 */
public interface ICashAcceptorHandler {

    /** 連線並初始化裝置。成功時回傳 {@code "成功連接到 USB 轉接器！"}（沿用既有成功字串比對）。 */
    String connect();

    /** 送出（已 hex 解碼的）MDB 指令位元組，回傳實際寫入長度，失敗回傳負值。 */
    int writeData(byte[] data);

    /** 讀取一筆裝置回應。 */
    byte[] readData() throws IOException;

    /** 啟動背景讀取執行緒，讀到的事件經 {@link MdbEventListener} 回拋。 */
    void startReading();

    /** 停止背景讀取執行緒。 */
    void stopReading();

    /** 關閉連線並釋放資源。 */
    void close();

    /** 設定除錯訊息監聽器（供現金機設定測試頁顯示連線/初始化/投退幣診斷）。可傳 null 關閉。 */
    void setDebugListener(DebugLogListener listener);
}
