AutoBanking
出帳管控與自動對帳

1. 現況架構與風險缺口

1.1 現行撥款流程

紅色 = 人工操作，無系統防護的步驟

// 現行狀態：EgopayApprM.status
const STATUS = {
  PENDING:  0,   // 待執行
  SUCCESS:  1,   // 成功（人工點確認）
  FAILED:   2,   // 失敗
};
// 問題：0→1 之間沒有中間狀態，無法區分「還沒匯」和「已匯未確認」

1.2 風險點（具體 code path）

1.3 現有基礎設施

2. 目標架構

紫色 = HQ 後端, 藍色 = Extension, 綠色 = DB, 橘色 = 配對引擎

2.1 改造後撥款流程

綠色 = 系統自動，人員只需執行「放行」這一步

2.2 階段依賴

Phase 1：完整網銀明細

資料基礎層。Extension 上傳入帳+出帳所有交易，HQ 完整儲存，餘額連貫性驗證。

1-A. Extension 端變更

交易上傳（9 家銀行 content script）

// 現行：只上傳入帳
if (tx.in > 0) records.push(tx);

// 改為：全部上傳，加 direction 標記
tx.direction = tx.in > 0 ? 'in' : 'out';
records.push(tx);

去重邏輯調整（background.js）

// 現行去重 key（48h 滾動窗口）
const dedupKey = `${date}_${time}_${account}_${amount}`;

// 改為：入帳/出帳分開去重
const dedupKey = `${date}_${time}_${account}_${direction}_${direction === 'in' ? amount_in : amount_out}`;

1-B. HQ 端變更

AutoBankingC 處理出帳

// AutoBankingC::receive_esun_bank()
// 現行：出帳跳過
if (!$record['in']) continue;

// 改為：出帳也寫入 bank_transactions
if ($record['direction'] === 'out') {
    BankTransaction::create([
        'bank'     => $bank,
        'out'      => $record['out'],
        'account'  => $record['account'],
        'balance'  => $record['balance'],
        'accounting_datetime' => $record['datetime'],
    ]);
    continue; // 不進 payment 配對
}

DB Schema 變更

-- bank_transactions 新增索引
ALTER TABLE bank_transactions
  ADD INDEX idx_bank_out_acctime (bank, out, accounting_datetime);

餘額連貫性驗證

// 驗證邏輯（同帳戶按時間排序）
// prev.balance + curr.in - curr.out == curr.balance
// 不連貫 → 標記 balance_gap 警告（不硬擋）

1-C. 交易上傳 Sequence

Phase 2：撥款狀態控管

控管層。撥款單五階段狀態追蹤 + 三道防重複閘門 + 出帳↔撥款自動配對。

2-A. 狀態機設計

// Extension 端 ticket 狀態（chrome.storage.local）
const TICKET_STATE = {
  UNFILLED:   'unfilled',    // 初始 → 5min 後 needs_speed → 15min 後 overdue
  FILLED:     'filled',      // FillForm 填入後
  RELEASING:  'releasing',   // 放行確認頁偵測到
  RELEASED:   'released',    // 放行結果頁偵測到成功
  CONFIRMED:  'confirmed',   // 出帳 bank_tx 配對成功
};

// HQ 端 EgopayApprM.status
const HQ_STATUS = {
  PENDING:    0,   // 待執行
  SUCCESS:    1,   // 成功
  FAILED:     2,   // 失敗
  FILLING:    3,   // 匯款中（新增）
};

2-B. 防重複匯款三道閘門

2-C. FillForm → Confirm 完整 Sequence

2-D. 放行偵測（各銀行 content script）

2-E. 出帳 ↔ 撥款配對邏輯

// background.js: matchOutRecordsToTickets()
// 每 5 秒 StateCheck 觸發

for (const ticket of releasedTickets) {
  const match = outRecords.find(tx =>
    tx.account === ticket.targetAccount &&
    Math.abs(tx.out - ticket.amount) <= 30 &&  // 容許匯費差額
    withinMinutes(tx.datetime, ticket.releaseTime, 30)
  );

  if (match) {
    updateTicketState(ticket.id, 'confirmed');
    // → 呼叫 HQ API 同步 status 3→1
  }
}

2-F. 新增 HQ API

Phase 3：撥款自動對帳

自動化層。出帳配對成功後，自動回填所有人工欄位。

3-A. 自動回填邏輯

// ApprC::confirm() 被呼叫時，自動回填

$bankTx = BankTransaction::find($bank_tx_id);

$ticket->transaction_time = $bankTx->accounting_datetime;
$ticket->bank             = $bankTx->bank;
$ticket->fee              = $bankTx->out - $appr->amount;
$ticket->operator_id      = auth()->id();  // 獨立 HQ 帳號

$appr->status = 1;
$appr->bank_transaction_id = $bankTx->id;  // 建立連結
$appr->save();
$ticket->save();

3-B. 自動化前後對照

3-C. DB Schema 變更

-- egopay_apprs 新增欄位：連結出帳記錄
ALTER TABLE egopay_apprs
  ADD COLUMN bank_transaction_id BIGINT UNSIGNED NULL AFTER status,
  ADD INDEX idx_bank_tx (bank_transaction_id);

Phase 4：異常單系統

偵測層。基於完整入帳+出帳資料，自動偵測異常交易。

4-A. 異常偵測引擎規格

4-B. 重複匯款處置流程

// 偵測到重複匯款後的處置選項
enum DuplicateResolution {
  REFUND_BANK,        // 匯回原帳號
  SELL_ORDER_REFUND,  // 賣單還款（客戶多賣一次幣）
  BUY_ORDER_REFUND,   // 買單還款 + 開新賣單撮合
}

4-C. 查詢工具強化

• 預撥查詢支援 id 和分站單號
• 固定帳號查詢加入開單時間和繳費時間篩選
• 用銀行帳號反查分站、會員
• 異常單加入其他損失、其他收入分類

5. 實施總覽

5-A. 全階段影響矩陣

5-B. 風險與緩解