采心教育 · 家教媒合與學習管理平台 - 系統架構與功能規劃書

1. 系統定位與核心目標

「采心教育家教媒合平台」（深耕新竹地區 · 學齡前至高中專業家教 · 陪伴孩子精準提升學習力）專為現代化外派家教與精緻小班媒合量身打造。系統透過 Cloudflare 全生態無伺服器邊緣架構 (Serverless Edge Architecture)，完整承接官方 LINE 核心理念與營運流程：

• 深耕新竹在地無定點模式：機構無定點實體教室，由專職主任全程嚴格把關師資，安排專業教師外派到府、社區自習小班或線上互動授課。
• 透明收費矩陣與車馬費設定：
  • 嚴格劃分「一對一」與「一對多（一對二、一對三、一對四）」學費定價。
  • 精準區分「學齡前幼稚園、國小、國小升私中、國中、私校/國三會考班、高中」等不同學制鐘點費。
  • 外派車馬費設定 (Travel Allowance)：因應外派到府教學，系統支援每堂課交通車馬費獨立配置（如新竹市區 0150 元/堂、跨區/高鐵特區 200300 元/堂）。
  • 超時陪讀優惠：家教每月授課超過 40 小時 (40h)，費用享以陪讀費用優惠計價。
• 預約試教與案件媒合中心：
  • 建議先約一次試教；由專職主任精準媒合適性老師。
  • 安心試上承諾：試上若不適合，教務主任隨時協助彈性調校或更換老師。
• 嚴選優質師資把關：
  • 師資以補教、學校與私校老師為主，教學經驗超過五年以上。
  • 整合良民證、畢業證書、經歷審核與專長認證。
• 課程規定與補課須知管理（依循官方 LINE 規範）：
  • 每月請假限制：每月僅提供 1 天事假與 1 天病假之補課機會。
  • 補課條件：事假須提前 3 天請假、病假須提前 1 天請假；當日臨時病假若無就診證明無法補課。
  • 補課時限：補課須於次月底前完成，逾期視同放棄資格；補課時間一經確定不得變動。
• 無第三方金流 · 轉帳核帳與官方收據：
  • 暫無第三方金流串接需求，每月上課前確認次月時段，於每月 5 日前完成轉帳或現金繳費（逾期未繳費時段將於 10 日起開放）。
  • 家長線上回填「轉帳帳號末五碼」，行政秘書一鍵核對並開立正式電子憑單收據。

2. 系統架構圖 (System Architecture Diagram)

flowchart TD
    subgraph PortalLayer["多角色入口視圖 (Multi-Role Portals)"]
        AdminPortal["👩‍💼 專職教務主任 / 行政秘書 工作台
(師資把關、案件媒合審核、安心換師、假單補課核定、薪酬試算)"]
        TeacherPortal["👨‍🏫 專業家教老師 工作台
(案件媒合大廳、接案意願、課堂打卡、車馬費結算、日誌回報)"]
        ParentPortal["👨‍👩‍👧 親子專區 (家長 / 學生)
(預約試教單、動態學費計算機、到府/社區需求、請假補課申請、繳款回報)"]
    end

    subgraph AuthLayer["身分認證與帳號管理 (Auth & User Center)"]
        LoginCenter["統一身分登入中心 (/api/auth/login)
支援帳號密碼登入、停權攔截與 DEMO 快速傳送門"]
        UserMgmt["使用者帳號維護中心 (/api/users/*)
支援主任、行政、老師、家長帳號治理"]
    end

    subgraph CoreBusinessLayer["采心教育六大核心模組 (Core Business Modules)"]
        M1["模組一：師資審核認證中心
(5年以上師資把關、良民證、時薪等級與車馬費基數)"]
        M2["模組二：家教媒合與試教中心
(一對一/一對多需求、到府地點、安心試教、換師調校)"]
        M3["模組三：動態學費計算與優惠試算
(學制費率矩陣、一對多級距、車馬費、滿40小時陪讀優惠)"]
        M4["模組四：課堂行動簽到打卡
(到府/社區簽到、時數核定、教學進度日誌同步)"]
        M5["模組五：課程請假與補課管制作業
(1事1病限制、提前天數檢查、次月底補課時效管制)"]
        M6["模組六：薪資自動結算與無金流轉帳確認
(鐘點費+車馬費統計、家長轉帳末五碼核帳、正式憑單)"]
    end

    subgraph EdgeStorageLayer["Cloudflare 邊緣無伺服器儲存 (Edge Serverless Layer)"]
        D1[("Cloudflare D1 (SQL 資料庫)
收費標準表、師資表、媒合案、課堂、假單、薪酬對帳")]
        R2["Cloudflare R2 (物件儲存)
良民證、教學證書、學生病假看診證明單據"]
        KV["Cloudflare KV (快取與狀態)
高頻費率快取、媒合狀態與驗證 Token"]
    end

    PortalLayer --> LoginCenter
    LoginCenter --> UserMgmt
    UserMgmt --> D1
    
    AdminPortal --> M1 & M2 & M4 & M5 & M6
    TeacherPortal --> M1 & M2 & M4 & M6
    ParentPortal --> M2 & M3 & M4 & M5 & M6

    M1 & M2 & M3 & M4 & M5 & M6 --> D1
    M1 & M5 --> R2
    M3 --> KV
      

3. 收費標準矩陣與定價規格 (Pricing & Allowance Specifications)

采心教育採公開透明的收費準則，系統實裝動態試算計算機，精確依「教學模式」、「學制年級」與「車馬費補貼」即時報價：

3.1 一對一專屬家教課程 (鐘點費)

3.2 一對多社區小班客製課程 (每小時全班鐘點費)

針對兄弟姊妹同儕或社區同好小班，提供專屬小班優惠費率：

3.3 外派車馬費設定規範 (Travel Allowance)

• 車馬費屬性：附加於每堂實體授課紀錄。
• 費率依上課地點彈性設定：
  • 新竹市區一般地點（東區/北區/鄰近清交大）：0 ~ 100 元/堂
  • 竹北高鐵特區、竹科關埔、竹東等鄰近區域：150 ~ 200 元/堂
  • 新埔、芎林、香山或偏遠社區：250 ~ 300 元/堂
  • 線上視訊課程：0 元（免車馬費）
• 費用計算：課堂總費用 = (授課時數 × 該學制鐘點費) + (堂數 × 車馬費)。

3.4 超時與陪讀優惠

• 家教每月累計超過 40 小時 (40h)：超出或全數優惠依「陪讀費率（依學制原價 8 折或專案陪讀價）」計算，回饋長期密集輔導家庭。

3.5 三種收款與分帳設定體系 (Three-Way Financial Settlement)

為釐清家長、媒合中心與家教老師三方權責與帳目，系統於課程合約與財務結算提供三種明確收款設定：

1. 家長收款 (Parent Bill / 家長應繳金額)：
   • 定義：家長應支付該課程的完整費用。
   • 計算：$(\text{授課時數} \times \text{學制班制學費鐘點}) + (\text{實體授課堂數} \times \text{車馬費}) - \text{超時優惠折讓}$。
   • 方式：每月 5 日前透過 ATM 轉帳或現金繳納至中心指定帳戶。
2. 媒合中心收款 (Center / Platform Fee / 媒合中心服務費)：
   • 定義：采心教育媒合中心所保留之營運行政、師資審核、品質把關與安心試教更換保障之服務費。
   • 比例或固定額：系統支援百分比設定（如家長學費之 15%~20%）或差額定價（家長收款與老師實領之差額）。
3. 給老師的錢 (Teacher Payout / 老師實發課酬)：
   • 定義：老師教學付出之專業時薪所得，並全額外加外派車馬費補貼。
   • 計算：$(\text{授課時數} \times \text{老師核定時薪}) + (\text{實體授課堂數} \times \text{車馬費補貼})$。
   • 撥款：每月核算後開立官方課酬收據憑單並匯款至老師受款帳戶。

• 三方關係公式：$\text{家長收款} = \text{媒合中心收款} + \text{給老師的錢}$，各方皆可在專屬介面看到透明權責數字。

3.6 管理者自訂課程類型與老師分級收費設定 (Custom Course Types & Teacher Rates)

系統賦予管理者高度營運彈性，可完全擺脫寫死限制：

1. 課程類型自訂維護中心 (Admin Course Types CRUD)：
   • 管理者可自主新增、修改、停用課程類型（例如：「奧數思維拔尖班」、「全美語外師口說」、「私立薇閣/康橋專班」、「國三會考衝刺一對一」等）。
   • 每種課程類型可定義所屬學制、人數規模、官方基準時薪、建議車馬費與中心抽成基準。
2. 各老師依類型之客製收費設定 (Per-Teacher Rate Configuration)：
   • 針對個別老師，管理者可指派其授課之各項課程類型，並分別自訂該老師在該類型的：
     • 家長鐘點收費 (Parent Rate)
     • 給老師的鐘點費 (Teacher Rate)
     • 媒合中心抽成 (Center Commission)
     • 專案車馬費 (Travel Fee)
   • 解決同一位老師在教授一般國小、進階升私中、或高中學測時，擁有完全不同的收費與抽成組合之真實商業場景。

3.7 管理者智慧排課行事曆與通勤緩衝/防撞偵測 (Smart Calendar & Geographic Transit Buffer)

由於采心教育全面外派到府與社區授課，排課與調課若未考量跨區交通時間，將造成老師遲到或疲於奔命。系統於管理後台整合視覺化智慧行事曆：

1. 多維度視覺化排程行事曆：
   • 支援依老師、依日期（週/日視圖）檢視全體外派課堂排程，即時展示授課時間、學生、科目、上課地址與車馬費。
2. 時間重疊衝突自動偵測 (Time Collision Detection)：
   • 系統即時比對課堂起訖時間，若偵測到重疊撞期，立即以紅色高亮標示「⚠️ 時間撞期衝突」，並限制排程鎖定。
3. 鄰近時間跨區地點過遠預警 (Transit Gap & Geographic Buffer Alert)：
   • 當同一位老師的前後兩堂課，間隔時間小於 40 分鐘，且上課行政區不同（例如：前一堂於新竹市東區清大，後一堂於竹北高鐵區或香山），行事曆自動標示黃色預警：「⚠️ 鄰近時間地點過遠（間隔僅 30 分鐘，跨區通勤風險）」，方便教務主任精確評估、調配課堂順序或適度加計車馬費。

3.8 統一排課行事曆引擎 (管理人員與老師共用，支援當日 / 當週 / 當月切換)

為維持系統架構高內聚與程式碼高復用性 (DRY)，管理人員與授課老師全面共用同一個底層行事曆渲染引擎函式，並依角色動態配置資料維度與互動行為：

1. 共用同一核心函式架構 (Unified Function Pipeline)：
   • 管理人員呼叫時：讀取全體老師資料（支援下拉指定特定老師或全部），並由後台演算法注入 🔴【時間撞期衝突】與 🟡【跨區趕場地點過遠】警示標籤。
   • 老師呼叫時：自動篩選個人課堂資料，並注入「📍 外派打卡」與「✏️ 填寫日誌」快捷動作。
2. 「當日 / 當週 / 當月」三視圖無縫切換：
   • 當日視圖 (Day View)：精確聚焦今日課堂、出發時間、學生年級、上課地址、外派車馬費與即時打卡狀態。
   • 當週視圖 (Week View)：週一至週日條列式課表，一覽每日本週排程與通勤動線。
   • 當月視圖 (Month View)：全月月曆網格，標註每日課堂總數、已完成堂數與請假補課時段。
3. 行事曆卡片與行動聯動：
   • 在個人行事曆內可直接點擊執行「課堂行動簽到打卡」或「填寫課後教學日誌」。
   • 即時顯示該堂課之車馬費補貼與核定時薪，隨時清楚行程與預期收益。

4. 課程規定與補課作業規範 (Official LINE Rules)

系統前台明列且後台審核落實官方四大鐵律：

1. 每月請假限制：
   • 每位學生每月僅提供「1 天事假」與「1 天病假」之補課權益。
2. 補課條件與請假預警期：
   • 事假：須提前 3 天 提出申請才能安排補課。
   • 病假：須提前 1 天 提出申請才能補課。
   • 當日臨時病假：如無法出示就醫看診證明單據（拍照上傳），視同放棄補課資格。
3. 補課時限：
   • 補課必須於「次月底前」完成上課，逾期視同自動放棄。
4. 補課時間確定後不得變動：
   • 補課時段一經雙方與主任確認即鎖定，若臨時更改或未出席，視同取消補課，恕不另行安排。

5. 無金流運作與繳費作業規範

1. 時段確認與繳費期限：
   • 家長須於繳費前與主任確認次月上課時段。
   • 每月 5 日前 須完成 ATM 轉帳或現金繳費，並於系統平台登記「轉帳帳號後五碼」或現金收訖。
   • 逾期未完成繳費將視同放棄原時段，教務主任於 每月 10 日起 將該時段釋出開放給其他家長預約。
2. 繳費回報與電子收據：
   • 家長於「繳款回報」填寫轉帳日期、金額與帳號末五碼。
   • 行政秘書核對網銀入帳後，一鍵標記為「已入帳」，系統自動開立官方正式收據憑單。

6. API 路由端點清單與功能對照表