采心教育 · 家教媒合與學習管理平台 - 資料庫結構設計規格書 (Database Schema Specification)

本文件依據采心教育官方 LINE 資訊、系統架構規劃書 (docs/system-architecture.md) 與 Cloudflare D1 邊緣分散式資料庫規格進行完整設計。系統核心具備無定點外派到府/社區授課、學制分級收費、一對多客製定價、外派車馬費補貼、試教媒合流程、官方請假補課管制以及無金流轉帳末五碼核帳等關鍵業務模型。

1. 系統資料實體關聯圖 (ERD)

erDiagram
    USERS ||--o| TEACHER_PROFILES : "1:1 老師專屬資料"
    USERS ||--o{ STUDENTS : "1:N 家長關聯學生"
    USERS ||--o{ AUDIT_LOGS : "1:N 操作日誌"
    
    TEACHER_PROFILES ||--o{ TEACHER_DOCUMENTS : "1:N 審核證件(良民證/學歷)"
    TEACHER_PROFILES ||--o{ TEACHER_SUBJECTS : "1:N 專長科目(數學思維/全美語/全科)"
    TEACHER_PROFILES ||--o{ TEACHER_COURSE_RATES : "1:N 個別類型專屬收費"
    COURSE_TYPES ||--o{ TEACHER_COURSE_RATES : "1:N 老師費率配置"
    COURSE_TYPES ||--o{ COURSES : "1:N 課程引用類型"
    
    STUDENTS ||--o{ CASE_REQUESTS : "1:N 媒合與試教申請單"
    CASE_REQUESTS ||--o| COURSES : "1:1 媒合成案"
    
    TEACHER_PROFILES ||--o{ COURSES : "1:N 授課合約"
    STUDENTS ||--o{ COURSES : "1:N 參加課程(一對一或一對多)"
    
    COURSES ||--o{ CLASS_SESSIONS : "1:N 堂數紀錄(含鐘點與車馬費)"
    COURSES ||--o{ TUITION_PAYMENTS : "1:N 家長學費繳納紀錄(末五碼)"
    
    CLASS_SESSIONS ||--o| CLASS_EXCEPTIONS : "1:1 請假與補課管制紀錄"
    CLASS_SESSIONS ||--o| CLASS_EVALUATIONS : "1:1 課堂滿意度給評"
    
    TEACHER_PROFILES ||--o{ PAYROLL_RECORDS : "1:N 月度課酬與車馬費結算"
    PAYROLL_RECORDS ||--o{ PAYROLL_ITEMS : "1:N 薪資明細(時薪+車馬費補貼)"
    CLASS_SESSIONS ||--o{ PAYROLL_ITEMS : "0:1 對應課堂明細"

2. 采心教育定價與費率模型規格

2.1 學制與班制鐘點費對照標準 (Pricing Standard)

資料庫預設常數與驗證邏輯：

一對一課程 (ONE_ON_ONE)：
- KINDERGARTEN (幼稚園/學齡前)：NT$ 700 / hr
- ELEMENTARY (國小一般)：NT$ 800 / hr
- PRIVATE_ELEM (國小升私中專班)：NT$ 900 / hr
- JUNIOR_HIGH (國中一般)：NT$ 1,000 / hr
- PRIVATE_JUNIOR (私立中學 / 國三會考班)：NT$ 1,200 / hr
- SENIOR_HIGH (高中一般 / 學測分科)：NT$ 1,200 / hr
一對多客製小班課程 (每小時全班標準)：
- 一對二 (ONE_ON_TWO)：國中 1,600 元/hr、國小 1,400 元/hr、幼稚園 1,200 元/hr
- 一對三 (ONE_ON_THREE)：國中 2,100 元/hr、國小 1,800 元/hr、幼稚園 1,500 元/hr
- 一對四 (ONE_ON_FOUR)：國中 2,400 元/hr、國小 2,200 元/hr、幼稚園 2,000 元/hr
外派車馬費補貼 (travel_fee)：
- 預設每堂 0 ~ 300 元（依授課行政區與通勤距離自訂）。
- 線上視訊課程固定為 0 元。
超時陪讀優惠門檻 (hours_threshold)：
- 每月累計超過 40 小時 (40h)，超出之課時享有專案陪讀優惠費率（預設原價 8 折或固定陪讀費）。

3. 核心資料表詳細規格

3.1 老師檔案表 (`teacher_profiles`)

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	老師檔案識別碼
`user_id`	UUID	FK, UNIQUE, NOT NULL	-	關聯 `users.id`
`bio`	TEXT	NULL	-	教學理念、經歷自介 (五年以上經驗)
`highest_education`	VARCHAR(100)	NULL	-	最高學歷 (如臺大/清大/師大)
`review_status`	VARCHAR(20)	NOT NULL	`'PENDING'`	審核：`PENDING`, `APPROVED`, `REJECTED`
`tier`	VARCHAR(20)	NOT NULL	`'STANDARD'`	師資層級：`STANDARD`, `SENIOR`, `EXPERT`
`default_hourly_rate`	NUMERIC(10,2)	NOT NULL	`800.00`	預設基礎鐘點費
`default_travel_fee`	NUMERIC(10,2)	NOT NULL	`150.00`	外派到府預設每堂車馬費
`service_areas`	TEXT	NULL	-	新竹服務區域 (東區/北區/竹北/關埔等)
`bank_code`	VARCHAR(10)	NULL	-	撥款銀行代碼 (3 碼)
`bank_account`	VARCHAR(30)	NULL	-	撥款銀行帳號
`bank_account_name`	VARCHAR(50)	NULL	-	受款戶名

3.2 家教需求與試教申請表 (`case_requests`)

家長發布之媒合需求單，支援一對一或一對多、學制與外派地點。

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	案件需求識別碼
`parent_id`	UUID	FK, NOT NULL	-	關聯 `users.id` (家長)
`student_id`	UUID	FK, NOT NULL	-	關聯 `students.id` (學生)
`class_mode`	VARCHAR(20)	NOT NULL	`'ONE_ON_ONE'`	班制：`ONE_ON_ONE`, `ONE_ON_TWO`, `ONE_ON_THREE`, `ONE_ON_FOUR`
`grade_level`	VARCHAR(30)	NOT NULL	-	學制：`KINDERGARTEN`, `ELEMENTARY`, `PRIVATE_ELEM`, `JUNIOR_HIGH`, `PRIVATE_JUNIOR`, `SENIOR_HIGH`
`subject`	VARCHAR(50)	NOT NULL	-	需求科目 (數學思維/全美語/國中會考全科等)
`location_type`	VARCHAR(20)	NOT NULL	`'HOME'`	地點模式：`HOME` (到府), `COMMUNITY` (社區小班), `ONLINE` (線上)
`location_address`	TEXT	NOT NULL	-	上課地點 (如新竹市關新路社區)
`expected_travel_fee`	NUMERIC(10,2)	NOT NULL	`150.00`	該案約定每堂外派車馬費
`is_trial`	BOOLEAN	NOT NULL	`TRUE`	是否為預約試教案件 (預設先試教一次)
`status`	VARCHAR(20)	NOT NULL	`'OPEN'`	狀態：`OPEN` (待媒合), `ASSIGNED` (主任已指派), `CONVERTED` (轉為正式課), `CLOSED`
`assigned_teacher_id`	UUID	FK, NULL	-	主任指派之老師 `teacher_profiles.id`
`notes`	TEXT	NULL	-	備註 (學習弱點或特定期待)

3.3 課程與合約表 (`courses`)

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	課程唯一識別碼
`course_code`	VARCHAR(30)	UNIQUE, NOT NULL	-	課程代碼 (如 `CX-2026-MATH01`)
`title`	VARCHAR(100)	NOT NULL	-	課程名稱 (例：國二數學思維家教)
`teacher_id`	UUID	FK, NOT NULL	-	授課老師 `teacher_profiles.id`
`class_mode`	VARCHAR(20)	NOT NULL	`'ONE_ON_ONE'`	班制規模 (`ONE_ON_ONE` ~ `ONE_ON_FOUR`)
`grade_level`	VARCHAR(30)	NOT NULL	-	學制分類 (`KINDERGARTEN` ~ `SENIOR_HIGH`)
`parent_hourly_rate`	NUMERIC(10,2)	NOT NULL	-	1. 家長收款鐘點費率 (NT$/hr)
`center_service_fee`	NUMERIC(10,2)	NOT NULL	`200.00`	2. 媒合中心每小時服務抽成 (NT$/hr)
`teacher_hourly_rate`	NUMERIC(10,2)	NOT NULL	-	3. 給老師的鐘點費率 (NT$/hr)
`travel_fee_per_session`	NUMERIC(10,2)	NOT NULL	`150.00`	每堂課外派車馬費補貼 (全額歸老師)
`location_type`	VARCHAR(20)	NOT NULL	`'HOME'`	授課地點類型 (`HOME`, `COMMUNITY`, `ONLINE`)
`address`	TEXT	NULL	-	授課詳細地址
`status`	VARCHAR(20)	NOT NULL	`'ACTIVE'`	課程狀態：`ACTIVE`, `COMPLETED`, `PAUSED`

3.4 課堂與出勤紀錄表 (`class_sessions`)

記錄每堂上課的時數、鐘點費與實際外派車馬費。

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	堂數紀錄唯一碼
`course_id`	UUID	FK, NOT NULL	-	關聯 `courses.id`
`teacher_id`	UUID	FK, NOT NULL	-	關聯 `teacher_profiles.id`
`session_date`	DATE	NOT NULL	-	上課日期 (YYYY-MM-DD)
`start_time`	TIME	NOT NULL	-	預定開始時間
`end_time`	TIME	NOT NULL	-	預定結束時間
`actual_duration`	NUMERIC(4,2)	NULL	-	實際授課時數 (小時)
`travel_fee_applied`	NUMERIC(10,2)	NOT NULL	`150.00`	此堂實際計入之車馬費 (NT$)
`status`	VARCHAR(20)	NOT NULL	`'SCHEDULED'`	狀態：`SCHEDULED`, `ATTENDED`, `LEAVE`, `MAKEUP`
`review_status`	VARCHAR(20)	NOT NULL	`'UNREVIEWED'`	行政審核：`UNREVIEWED`, `CONFIRMED`
`progress_notes`	TEXT	NULL	-	當日教學進度與教材頁數
`focus_rating`	INT	NULL	-	學生專注度 (1~5 星)

3.5 課程請假與補課管制表 (`class_exceptions`)

嚴格落實官方 LINE 規定：每月 1 天事假、1 天病假，提前天數校驗，次月底前補課完畢。

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	假單識別碼
`session_id`	UUID	FK, NOT NULL	-	關聯 `class_sessions.id`
`student_id`	UUID	FK, NOT NULL	-	關聯 `students.id`
`leave_type`	VARCHAR(20)	NOT NULL	-	請假類別：`PERSONAL` (事假), `SICK` (病假)
`request_date`	DATE	NOT NULL	-	提出請假日期
`notice_days`	INT	NOT NULL	-	提前通知天數 (事假須 >= 3天、病假須 >= 1天)
`medical_proof_url`	TEXT	NULL	-	臨時病假之醫療看診證明截圖連結 (R2)
`makeup_deadline`	DATE	NOT NULL	-	補課法定截止日 (原上課月之次月底前)
`makeup_session_id`	UUID	FK, NULL	-	對應補課課堂 `class_sessions.id`
`is_makeup_locked`	BOOLEAN	NOT NULL	`TRUE`	補課時間一經確定不得更改
`status`	VARCHAR(20)	NOT NULL	`'PENDING'`	審核：`PENDING`, `APPROVED`, `REJECTED`, `COMPLETED`

3.6 學費繳款、三方分帳與轉帳核帳表 (`tuition_payments`)

支援無金流環境下，家長回報轉帳末五碼與主任核對開立收據，並清楚劃分三種收款設定：

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	繳費紀錄識別碼
`course_id`	UUID	FK, NOT NULL	-	關聯課程
`parent_id`	UUID	FK, NOT NULL	-	關聯家長
`billing_month`	VARCHAR(7)	NOT NULL	-	收費月份 (例：`2026-11`)
`parent_tuition_amount`	NUMERIC(10,2)	NOT NULL	-	1. 家長應繳鐘點學費總額
`travel_fee_total`	NUMERIC(10,2)	NOT NULL	`0.00`	外派車馬費總額合計
`discount_amount`	NUMERIC(10,2)	NOT NULL	`0.00`	超時 40h 陪讀等折讓優惠
`parent_total_amount`	NUMERIC(10,2)	NOT NULL	-	家長應繳總計 (學費+車馬費-折讓)
`center_income_amount`	NUMERIC(10,2)	NOT NULL	-	2. 媒合中心服務收益 (服務抽成)
`teacher_payout_amount`	NUMERIC(10,2)	NOT NULL	-	3. 給老師的錢 (老師時薪+車馬費)
`payment_method`	VARCHAR(20)	NOT NULL	`'TRANSFER'`	繳費管道：`TRANSFER` (ATM 轉帳), `CASH` (現金)
`transfer_last_5`	VARCHAR(5)	NULL	-	轉帳帳號後五碼
`transfer_date`	DATE	NULL	-	轉帳日期 (規定每月 5 日前)
`payment_status`	VARCHAR(20)	NOT NULL	`'REPORTED'`	狀態：`PENDING`, `REPORTED`, `VERIFIED`, `OVERDUE`
`receipt_number`	VARCHAR(30)	UNIQUE, NULL	-	官方正式學費收據號 (`REC-YYYYMM-XXX`)
`verified_at`	TIMESTAMPTZ	NULL	-	主任/秘書入帳核銷時間

3.7 管理者自訂課程類型表 (`course_types`)

提供管理者自主新增、修改與維護各種課程類型。

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	課程類型識別碼
`name`	VARCHAR(50)	NOT NULL	-	課程類型名稱 (例：國三會考衝刺班)
`grade_level`	VARCHAR(30)	NOT NULL	-	學制階段 (`KINDERGARTEN` ~ `SENIOR_HIGH`)
`class_mode`	VARCHAR(20)	NOT NULL	`'ONE_ON_ONE'`	班級規模 (`ONE_ON_ONE` ~ `ONE_ON_FOUR`)
`default_parent_rate`	NUMERIC(10,2)	NOT NULL	-	建議家長鐘點收費 (NT$/hr)
`default_teacher_rate`	NUMERIC(10,2)	NOT NULL	-	建議老師鐘點薪酬 (NT$/hr)
`default_travel_fee`	NUMERIC(10,2)	NOT NULL	`150.00`	建議每堂車馬費 (NT$)
`status`	VARCHAR(20)	NOT NULL	`'ACTIVE'`	狀態：`ACTIVE`, `INACTIVE`

3.8 老師依課程類型專屬收費表 (`teacher_course_rates`)

支援同一位老師針對不同課程類型配置個別差異化收費與拆帳。

欄位名稱	型態	限制條件	預設值	說明
`id`	UUID	PK	`gen_random_uuid()`	費率識別碼
`teacher_id`	UUID	FK, NOT NULL	-	關聯 `teacher_profiles.id`
`course_type_id`	UUID	FK, NOT NULL	-	關聯 `course_types.id`
`parent_hourly_rate`	NUMERIC(10,2)	NOT NULL	-	該老師此類型的家長收費 (NT$/hr)
`teacher_hourly_rate`	NUMERIC(10,2)	NOT NULL	-	該老師此類型的實領鐘點 (NT$/hr)
`center_service_fee`	NUMERIC(10,2)	NOT NULL	-	該老師此類型的中心抽成 (NT$/hr)
`custom_travel_fee`	NUMERIC(10,2)	NOT NULL	`150.00`	該老師此類型的專屬車馬費 (NT$)

4. 財務結算與三種收款試算演算法 (Financial Settlement Formula)

系統在對帳與計薪時，精確計算三種收款：

4.1 家長收款 (Parent Bill)

$$\text{Parent Bill} = \sum_{\text{sessions}} (\text{Actual Duration} \times \text{Parent Hourly Rate}) + \sum_{\text{sessions}} \text{Travel Fee Applied} - \text{Discount Over 40h}$$

4.2 給老師的錢 (Teacher Payout)

$$\text{Teacher Base Pay} = \sum_{\text{sessions}} (\text{Actual Duration} \times \text{Teacher Hourly Rate})$$ $$\text{Teacher Travel Subsidy} = \sum_{\text{sessions}} \text{Travel Fee Applied}$$ $$\text{Teacher Total Payout} = \text{Teacher Base Pay} + \text{Teacher Travel Subsidy}$$

4.3 媒合中心收款 (Center Platform Fee)

$$\text{Center Platform Income} = \text{Parent Bill} - \text{Teacher Total Payout}$$

若該月份家長每月超過 40 小時，系統自動套用專案陪讀折讓，並在對帳明細條目清楚標註「超時陪讀專案優惠」與「外派交通車馬費實額」，維護師生權益與帳目透明。

采心教育 · 家教媒合與學習管理平台 - 資料庫結構設計規格書 (Database Schema Specification)

1. 系統資料實體關聯圖 (ERD)

2. 采心教育定價與費率模型規格

2.1 學制與班制鐘點費對照標準 (Pricing Standard)

3. 核心資料表詳細規格

3.1 老師檔案表 (teacher_profiles)

3.2 家教需求與試教申請表 (case_requests)

3.3 課程與合約表 (courses)

3.4 課堂與出勤紀錄表 (class_sessions)

3.5 課程請假與補課管制表 (class_exceptions)

3.6 學費繳款、三方分帳與轉帳核帳表 (tuition_payments)

3.7 管理者自訂課程類型表 (course_types)

3.8 老師依課程類型專屬收費表 (teacher_course_rates)