AJAX API 端點
本文件彙整 dashboard/ 資料夾下所有 ajax_ 開頭的 PHP 檔案，這些檔案不是獨立頁面，而是提供 JSON（或 HTML 片段）回應給前端 AJAX 呼叫使用的 API 端點。
ajax_today.php
功能：取得當日各開課中班別的即時出席人數。
呼叫方式：GET ?ajax_today（由 index.php include 後偵測 GET 參數）
處理邏輯：
- 透過
ClassDates::get_opening_classdates()取得所有開課中班別 - 逐班查詢當日
enter_logs表，統計出distinctcard_id數量 - 回傳 JSON：
{code:0, data:{counts:{KIND{id}:數量}, total:{KIND{id}:總人數}, update_time:"Y/m/d H:i:s"}}
使用的 Functions：ClassDates::get_opening_classdates()、get_kind_by_suffix_classprefix()、get_all_card_by_card_kind()、get_string_by_tmpl()、now()、ajax_response()
ajax_one_day.php
功能：查詢指定班別在指定日期的全體學員刷卡紀錄（新版，含 JOIN 查詢）。
呼叫方式：GET ajax_one_day.php?kind={kind_id}&date_prefix={YYYY-MM-DD}
處理邏輯：
- 驗證
kind和date_prefix必填 - 以複雜的 SQL JOIN 查詢：
enter_card_kindLEFT JOINenter_cardsLEFT JOINenter_logs（最早/最晚刷卡時間、上課/下課需間隔 15 分鐘以上） - 每列回傳：卡號、學號、姓名、上課時間、是否補刷、是否遠端、下課時間、是否補刷、是否遠端
使用的 Functions：ajax_response()、get_card_by_card_id()、$wpdb->get_results()
ajax_one_day_old_0827.php
功能：ajax_one_day.php 的舊版實作（2022-08-27 備份），使用 UNION 子查詢。
呼叫方式：GET ajax_one_day_old_0827.php?kind={kind_id}&date_prefix={YYYY-MM-DD}
處理邏輯：
- 使用
get_all_card_by_card_kind()取得該班所有卡片 ID - SQL 以子查詢分別取 min/max
log_datetime，再以 UNION 合併 - 回傳格式同新版
使用的 Functions：get_all_card_by_card_kind()、get_card_by_card_id()、ajax_response()
ajax_one_student.php
功能：查詢指定學號學員的全部刷卡記錄明細，含上課時數計算、補刷追蹤、請假合併。
呼叫方式：GET ajax_one_student.php?student_school_no={school_no}
處理邏輯：
- 驗證
student_school_no必填 - 取得該學員的請假紀錄（
get_holiday_logs_by_school_no()），建立日期→請假時段映射 - 取得該學員所有卡片（
get_all_cards_by_school_no()），逐張查詢所有刷卡記錄 - 按日期合併，計算每日最早/最晚刷卡時間，追蹤補刷資訊（
___get_supplement_by_id()） - 依課表日期 (
ClassDates) 補齊無紀錄的日期 - 按日期排序，計算每日時數（扣除休息 1 小時），並支援自訂每日最大時數
- 統計累計上課時數與請假時數，以 JSON 回傳
使用的 Functions：get_all_cards_by_school_no()、get_all_logs()、get_holiday_logs_by_school_no()、get_student_sum_of_holidays()、get_card_kind_relationship_by_card_id()、get_kind_by_kind_id()、get_dates_diff()、now()、ClassDates::get_ary_dates_by_classprefix()、ClassDates::get_one()、ajax_response()
使用的常數：TBL_ENTER_SUPPLEMENT、TBL_ENTER_LOGS、HOLIDAY_REVIEW_RESULT_PASS
ajax_autocomplete_searchkind.php
功能：提供班別名稱的自動完成搜尋結果。
呼叫方式：GET ajax_autocomplete_searchkind.php?searchkind={keyword}
處理邏輯：
- 將搜尋關鍵字拆成單字陣列
- 遍歷所有學生班別（
get_all_kinds(true, true)），逐個檢查是否包含關鍵字的每個字 - 符合的班別轉為短名（
get_short_kind_name()），以 JSON 陣列回傳（jQuery UI Autocomplete 格式）
使用的 Functions：get_all_kinds()、get_short_kind_name()
ajax_student_rank.php
功能：取得指定班別的缺席學員排行榜 HTML 片段。
呼叫方式：GET ajax_student_rank.php?kind_id={kind_id}
處理邏輯：
- 驗證
kind_id必填 - 引入
ClassDates.php - 呼叫
render_student_rank($kind_id)取得 HTML 字串 - 直接
die()輸出
使用的 Functions：render_student_rank()（定義於 inc.php）
ajax_get_card_kinds.php
功能：依篩選條件（地區、類別、開課狀態）回傳符合的班別清單，供 ClassPicker Modal 使用。
呼叫方式：POST ajax_get_card_kinds.php
POST 參數：class_status[]（CLASS_STATUS_OPENING / CLASS_STATUS_CLOSED）、kind_area[]（北/竹/中/南/企/短/全）、kind_xlass[]（技/經/醫/製/金/售/EDGE/物/題/專/llm/genai…）
處理邏輯：
- 解析 POST 陣列，建立各維度的布林旗標
- 遍歷所有學生班別，依班別名稱判斷是否符合地區、類別條件
- 若有開課狀態篩選，查詢
ClassDates判斷開課/結業 - 三個條件全部符合的班別，以
[kind_id, short_kind_name]格式加入結果 - 以 JSON 回傳
使用的 Functions：get_all_kinds()、get_short_kind_name()、get_matched_classprefix()、ClassDates::get_ary_dates_by_classprefix()、now()、ajax_response()