QRCode 掃描打卡系統原理
概述
本系統透過瀏覽器鏡頭掃描學生 QRCode，解析出學生 ID 後，將打卡記錄送至後端 API 處理並存入資料庫。
相關檔案清單
核心檔案
-
前端主程式
- 檔案：
index.html - 絕對路徑：
class.aiacademy.tw/enter_logs/bb2qrcode/index.html - 說明：QRCode 掃描介面的主頁面，包含所有前端邏輯
- 檔案：
-
後端 API 處理
- 檔案：
ajax_logs2.php - 絕對路徑：
class.aiacademy.tw/enter_logs/ajax_logs2.php - 說明：接收前端打卡請求並處理資料庫操作
- 檔案：
-
後端共用函式庫
- 檔案：
inc.php - 絕對路徑：
class.aiacademy.tw/enter_logs/inc.php - 說明：提供資料庫操作、卡片驗證等共用函式
- 檔案：
前端資源檔案
-
QRCode 掃描器函式庫
- 檔案：
venders/qr-scanner-1.2.0.umd.min.js - 絕對路徑：
class.aiacademy.tw/enter_logs/bb2qrcode/venders/qr-scanner-1.2.0.umd.min.js
- 檔案：
-
QRCode 掃描器 Worker
- 檔案：
venders/qr-scanner-worker-1.2.0.min.js - 絕對路徑：
class.aiacademy.tw/enter_logs/bb2qrcode/venders/qr-scanner-worker-1.2.0.min.js
- 檔案：
-
其他前端函式庫
- Zepto.js：
class.aiacademy.tw/enter_logs/bb2qrcode/venders/zepto-1.2.0.min.js - Notyf 通知庫：
class.aiacademy.tw/enter_logs/bb2qrcode/venders/notyf-3.0.0.min.js - IndexedDB 快取庫：
class.aiacademy.tw/enter_logs/bb2qrcode/venders/runtime-memcache-2.0.0.udm.min.js
- Zepto.js：
流程說明
1. QRCode 掃描啟動
當頁面載入完成後，系統會初始化 QRCode 掃描器：
- 檔案：
index.html - 初始化位置：484-505 行
- 掃描器使用
QrScanner函式庫，持續監控視訊串流中的 QRCode
2. QRCode 偵測與解析
當掃描器偵測到 QRCode 時，會觸發回呼函式：
- 檔案：
index.html - 觸發函式：510-527 行 (
onQRCodeDetect) - 防重複機制：使用 TLRU 快取機制（434-438 行）避免短時間內重複處理相同 QRCode
從 QRCode 內容中提取學生 ID：
- 檔案：
index.html - 解析函式：552-565 行 (
getStudentIdFromQRCode) - 格式驗證：QRCode 必須符合
https://class.aiacademy.tw/student/{學生ID}格式
3. 打卡請求處理
系統會根據網路狀態採取不同策略：
3.1 連線狀態
- 檔案：
index.html - 處理函式：924-964 行 (
requestPunchingInStudentId) - 直接發送 POST 請求至後端 API
3.2 離線狀態
- 檔案：
index.html - 本地儲存：930 行（呼叫
LocalLogModule.saveLogToLocal） - 本地儲存模組：732-910 行 (
LocalLogModule) - 使用 IndexedDB 儲存打卡記錄，等待網路恢復後自動匯入（627-673 行）
4. 後端 API 處理
接收打卡請求的端點：
- 檔案：
../ajax_logs2.php（相對於bb2qrcode目錄） - API 路徑定義：727-730 行 (
_ajax_request_url)
後端處理邏輯：
- 檔案：
ajax_logs2.php - 主要處理：4-114 行
- 處理步驟：
- 驗證輸入參數（14-15 行）
- 取得卡片資訊（18 行）
- 驗證使用者身份與權限（22-47 行）
- 取得教室資訊（49-50 行）
- 建立打卡記錄（88-102 行）
- 存入資料庫（102 行，
TBL_ENTER_LOGS表） - 回傳結果（103 行）
5. 回應處理
前端接收到後端回應後：
- 檔案：
index.html - 成功處理：942-947 行
- 顯示通知訊息：567-575 行 (
showNotification) - 錯誤處理：948-954 行
資料流程
QRCode 掃描
↓
解析學生 ID (index.html:552-565)
↓
檢查快取防重複 (index.html:516-519)
↓
判斷網路狀態 (index.html:929)
├─ 連線 → 發送 POST 請求 (index.html:932-962)
│ ↓
│ ajax_logs2.php 處理 (ajax_logs2.php:4-114)
│ ↓
│ 存入資料庫 (ajax_logs2.php:102)
│ ↓
│ 回傳結果 (ajax_logs2.php:103)
│ ↓
│ 顯示成功訊息 (index.html:942-947)
│
└─ 離線 → 存入 IndexedDB (index.html:767-831)
↓
等待網路恢復 (index.html:667-673)
↓
自動匯入雲端 (index.html:627-665)
重要參數
前端設定
ROOM_ID: 教室 ID，定義於index.html:423CLASS_AIACADEMY_TW_BASE_URL: API 基礎路徑，定義於index.html:428
POST 資料格式
card_id: 學生 ID（從 QRCode 解析）room_id: 教室 IDbye: 打卡類型（‘F’ 表示進入）
錯誤處理
- 不支援的 QRCode 格式：顯示錯誤通知 (index.html:523)
- 網路錯誤：自動儲存至本地，待恢復後匯入 (index.html:952-954)
- 後端驗證失敗：回傳錯誤碼，前端顯示錯誤訊息 (index.html:948-950)
離線支援機制
系統支援離線打卡功能：
- 本地儲存：使用 IndexedDB 儲存打卡記錄
- 自動匯入：每 30 秒檢查一次本地記錄並嘗試匯入 (index.html:671)
- 手動匯入：管理介面提供手動匯入按鈕 (index.html:627-665)