CFDivePlatform/openspec/specs/course-scheduling/spec.md at 975b56ca54353fc5a4672b4243c83a6f2913f0bb

a620906209/CFDivePlatform

Files

T

a620906209 975b56ca54 feat:實作預約系統 — 時段管理、預約生命週期與前端整合

後端：
- 新增 course_schedules / bookings migration（含索引）
- BookingStatus / ScheduleStatus PHP BackedEnum
- CourseSchedule / Booking Model（七狀態機 VALID_TRANSITIONS）
- ScheduleController、ProviderBookingController、MemberBookingController
- 雙層名額驗證（API 層快速失敗 + DB lockForUpdate 防超賣）
- 24h 取消截止、pending 不佔位設計
- ExpirePendingBookings（每小時）/ CompleteFinishedBookings（每日）Scheduler
- Docker cron 配置、CACHE_STORE 改為 file 修正 502

前端：
- 課程詳情頁加入時段選擇與預約流程
- 我的預約頁（展開式卡片、狀態說明、連結課程詳情）
- Coach 時段管理（上午/下午時間選擇器、新課程引導）
- Coach 預約管理（依課程分組、待確認徽章）
- Navbar 新增「我的預約」與「時段/預約管理」入口
- 密碼格式提示與即時比對

OpenSpec：
- booking-system change 歸檔至 archive/2026-05-12-booking-system
- 新增 specs/course-scheduling 與 specs/booking-lifecycle 主規格

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

2026-05-12 00:24:51 +08:00

3.8 KiB

Raw Blame History

Requirement: Provider 建立開課時段

Provider SHALL 能為自己擁有的 DivingOffer 建立開課時段，指定日期、開始時間、人數上限。

Scenario: 成功建立時段

WHEN Provider 送出 POST /api/provider/schedules，包含合法的 diving_offer_id、scheduled_date（未來日期）、start_time、max_participants（≥1）
THEN 系統建立 CourseSchedule，status 為 open，回傳 201 與新時段資料

Scenario: 不可為他人課程建立時段

WHEN Provider 送出的 diving_offer_id 屬於其他 Provider
THEN 系統回傳 403 Forbidden

Scenario: 日期不可為過去

WHEN scheduled_date 早於今天
THEN 系統回傳 422，錯誤訊息指出日期無效

Requirement: Provider 管理既有時段

Provider SHALL 能更新或取消自己的開課時段。

Scenario: 更新時段資訊

WHEN Provider 送出 PUT /api/provider/schedules/{id}，修改 start_time 或 max_participants
THEN 系統更新時段資料，回傳更新後內容

Scenario: 取消時段

WHEN Provider 送出 DELETE /api/provider/schedules/{id}
THEN 系統將時段 status 改為 cancelled，不實體刪除；cascade 處理所有相關 Booking（詳見下方 Requirement）

Scenario: 不可修改他人時段

WHEN Provider 嘗試修改不屬於自己的時段
THEN 系統回傳 403 Forbidden

Requirement: 取消時段的 Booking Cascade 處理

Provider 取消時段時，系統 SHALL 在同一 DB transaction 內處理該時段下所有活躍 Booking，並明確定義各狀態的 cascade 規則。

Scenario: pending Booking cascade 為 provider_cancelled

WHEN Provider 取消時段，時段下存在 status 為 pending 的 Booking
THEN 這些 Booking status 全部改為 provider_cancelled

Scenario: confirmed Booking cascade 為 provider_cancelled

WHEN Provider 取消時段，時段下存在 status 為 confirmed 的 Booking
THEN 這些 Booking status 全部改為 provider_cancelled，current_participants 不需調整（時段已取消）

Scenario: 終態 Booking 不受 cascade 影響

WHEN Provider 取消時段，時段下存在 status 為 completed、rejected、expired、member_cancelled、provider_cancelled 的 Booking
THEN 這些 Booking status 維持不變

Scenario: cascade 在同一 transaction 內完成

WHEN Provider 取消時段
THEN 時段狀態更新與所有 Booking cascade 更新在同一 DB transaction 內完成；任一失敗則全部 rollback，API 回傳 500

Requirement: 時段人數自動管理

系統 SHALL 在預約確認時自動累計 current_participants，並於額滿時將時段 status 改為 full。current_participants 只計算 confirmed 人數，pending 不佔位。

Scenario: 預約確認後人數更新

WHEN Provider 確認一筆 Booking（confirmed），booking 的 participants 為 N
THEN course_schedules.current_participants 增加 N；若達到 max_participants 則 status 改為 full

Scenario: 預約取消後人數釋放

WHEN 一筆 confirmed 狀態的 Booking 被取消（member_cancelled 或 provider_cancelled）
THEN current_participants 減少對應人數；若原本為 full 則 status 改回 open

Requirement: Member 查詢可用時段

Member SHALL 能查詢指定課程的可用開課時段列表。

Scenario: 取得開放時段

WHEN 任何人（含未登入）送出 GET /api/diving-offers/{id}/schedules
THEN 系統回傳該課程 status 為 open、日期未過的時段列表（含剩餘名額 remaining_spots），依日期升冪排序

Scenario: 已滿時段不顯示

WHEN 時段 status 為 full
THEN 不包含在上述列表中

3.8 KiB Raw Blame History Unescape Escape