采心教育家教媒合平台 - 技術整合與邊緣架構規劃書 (Integration Architecture)

本規劃書旨在融合兩個補教管理系統（MdFarhan681/etuitionbd 與 AzimKrishna/Tuition-Management-System）的核心優勢，並將整體技術棧統一為 TypeScript 全端 + Cloudflare 邊緣架構，全面落地「采心教育」官方 LINE 外派家教媒合、動態學費試算、三種收款分流、外派車馬費補貼與請假補課管制體系。

1. 兩大專案的優勢互補與采心教育新定位

2. 采心教育全新核心業務機制技術落實

2.1 動態學費試算計算機 (Pricing Calculator Widget)

• 前端內建即時動態響應計算模組，依據使用者選擇之：
  1. 班級人數規模（一對一、一對二、一對三、一對四）
  2. 學制年級（學齡前幼稚園 7001200、國小 8001400、升私中 900、國中 1000~1600、私校/會考班 1200、高中 1200）
  3. 授課地點與車馬費（到府 0~300 元/堂，線上 0 元）
  4. 每週上課堂數與總時數
• 自動依據「每月超過 40 小時享有陪讀優惠」演算法進行折讓展示，提供家長清晰透明的月預估費用。

2.2 三種收款與分帳設定技術架構 (Three-Way Financial Settlement)

系統於資料層與結算引擎中清楚劃分三種金流流向：

1. 家長收款 (Parent Bill)：
   • 包含：授課鐘點費總額 + 實體到府車馬費總額 - 滿 40h 陪讀優惠折讓。
   • 於每月 5 日前轉帳或現金繳納，回報帳號末五碼。
2. 媒合中心收款 (Platform / Center Fee)：
   • 采心教育媒合中心所留存之服務費（提供師資嚴選把關、教學進度監控、安心試上調校與補課協調保障）。
3. 給老師的錢 (Teacher Payout)：
   • 老師實得課酬（依審核核定之時薪 × 核實時數）+ 100% 外派交通車馬費實額。

• 結算時三者緊密校驗：$\text{家長收款} = \text{媒合中心收款} + \text{給老師的錢}$，並於管理後台與正式收據中分項羅列。

2.3 外派車馬費補貼機制 (Travel Allowance Integration)

• 針對新竹各地區（市區、竹北高鐵、關埔特區、竹東、香山等）彈性設定每堂課車馬費。
• 老師打卡簽到時自動帶入該課程之車馬費，並於課酬試算中獨立呈現，確保外派師資權益。

2.4 官方 LINE 請假與補課管制機制 (Leave & Make-up Engine)

• 實施業務防呆邏輯：
  • 每月事假上限 1 次、病假上限 1 次。
  • 事假申請日距離上課日需 $\ge 3$ 天；病假需 $\ge 1$ 天；臨時病假強制上傳看診收據證明照片。
  • 補課排定必須在原上課月份之次月底前完成，且時間確定後系統鎖定不允許變更。

2.5 後台智慧排課行事曆與通勤地理防撞演算法 (Transit & Conflict Engine)

為因應無定點辦公室、全外派到府教學的痛點，系統內建時空雙維度排程校驗：

1. 時間重疊防撞演算法：
   • 針對同一老師的課堂紀錄，檢驗公式：$\max(Start_A, Start_B) < \min(End_A, End_B)$。
   • 若成立則觸發紅色衝突標記（CONFLICT_OVERLAP），提示管理者時間撞期。
2. 跨區地理通勤緩衝演算法 (Geographic Transit Buffer)：
   • 比對相鄰兩堂課：$\Delta T = Start_{next} - End_{prev}$。
   • 若 $\Delta T < 45 \text{ mins}$ 且 $Area_{prev} \ne Area_{next}$（例如新竹市東區 vs 竹北高鐵區/香山區），系統觸發黃色過遠預警（WARNING_TRANSIT_DISTANCE）。
   • 前端行事曆以直觀顏色標籤標示，使主任在為家長安排試教或例行課堂時，能即時掌握老師交通可行性，避免延誤或疲於奔波。

3. 統一技術棧選型 (Cloudflare Edge & Unified TypeScript Stack)

┌────────────────────────────────────────────────────────────────────────┐
│                        采心教育邊緣技術架構棧                            │
├────────────────────────────────────────────────────────────────────────┤
│  前端視圖    │ 溫馨奶油杏色風格 SPA (純原生極速渲染 / 官方 LINE 治癒元素)│
│  邊緣運算層  │ Cloudflare Pages Functions / Workers (V8 Edge Runtime) │
│  資料存取    │ Drizzle ORM (輕量極速、零冷啟動、強型別 SQL)             │
│  關聯資料庫  │ Cloudflare D1 (Serverless SQLite, 5GB 免費、永不休眠)   │
│  檔案與證件  │ Cloudflare R2 (良民證、看診證明、證書存儲、0 元流量費)    │
│  快取與狀態  │ Cloudflare KV (動態費率快取、Rate Limiting)             │
│  部署與管理  │ Wrangler CLI (本地一鍵直推、完全不依賴 GitHub)          │
└────────────────────────────────────────────────────────────────────────┘

4. 系統安全與資料防護標準

1. 參數化邊緣資料庫防線：全面淘汰原生 SQL 拼接，所有操作經由 Drizzle ORM 參數化預編譯，杜絕 SQL Injection。
2. 水平越權防護 (IDOR)：家長僅能調閱自己名下子女之進度與假單，老師僅能查看授課之課堂與個人薪酬，主任擁有全域管理權。
3. 病假與證件防護：病假看診證明、良民證等機敏照片存放於 Cloudflare R2 私有貯體，不開放公開爬蟲。
4. 收據防偽與安全列印：家長學費收據與老師課酬收據採用安全 DOM 節點渲染，支援瀏覽器原生列印 (window.print()) 與電子查驗。

5. 程式設計規範與共用函式治理 (Coding Rules & DRY Standards)

為防範系統在日後迭代與維護過程中發生「各角色各自重複寫一套」、「修改時漏改」或「邏輯不一致」的嚴重隱患，系統嚴格要求：

1. 功能重合度高時，必須共用同一函式 (Shared Function Enforcement)：
   • 管理人員排課行事曆與老師個人行事曆，全面共用底層行事曆渲染引擎函式。
   • 透過角色上下文參數（role: 'admin' | 'teacher'）與過濾選項（teacherId、viewMode: 'day' | 'week' | 'month'）進行動態渲染，禁止各自分叉寫獨立日曆渲染。
2. 單一真實來源 (Single Source of Truth)：
   • 價格矩陣、三方分帳演算法、通勤過遠門檻（如 40 分鐘且跨區）、補課時限等核心規則，統一集中於服務層或單一模組，全系統呼叫，杜絕寫死多處。
3. 介面統一與無縫切換：
   • 凡共用之元件，所有狀態切換（當日/當週/當月、日期前後翻頁）由單一控制器驅動，保證多角色操作手感與體驗高度一致。