a620906209/CFDivePlatform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
後端：
- 新增 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>
This commit is contained in:
Hank
2026-05-12 00:24:51 +08:00
parent ad2c05779d
commit 975b56ca54
40 changed files with 2202 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/archive/2026-05-12-booking-system/specs/booking-lifecycle/spec.md
+104
View File
@@ -0,0 +1,104 @@
## ADDED Requirements
### Requirement: Member 送出預約
Member SHALL 能選擇一個開放時段送出預約，系統記錄價格快照。
#### Scenario: 成功建立預約
- **WHEN** 已登入 Member 送出 `POST /api/member/bookings`，指定 `schedule_id` 與 `participants`（≥1）
- **THEN** 系統建立 Booking，status 為 `pending`，`total_price` 快照為 `diving_offer.price × participants`，回傳 201
#### Scenario: 時段已滿無法預約
- **WHEN** 指定時段 status 為 `full` 或 `cancelled`
- **THEN** 系統回傳 422，告知時段不可用
#### Scenario: 超過剩餘名額（API 層快速驗證）
- **WHEN** `participants` 大於時段當前剩餘名額（`max_participants - current_participants`），在進入 DB transaction 前
- **THEN** 系統回傳 422，告知人數超過上限，不進入 lockForUpdate 流程
#### Scenario: 超過剩餘名額（DB 層二次驗證）
- **WHEN** API 層通過但 lockForUpdate 後重新計算剩餘名額仍不足（race condition 情境）
- **THEN** 系統 rollback transaction，回傳 422，告知名額不足
#### Scenario: 不可重複預約同一時段
- **WHEN** Member 對同一 `schedule_id` 已有 `pending` 或 `confirmed` 狀態的 Booking
- **THEN** 系統回傳 422，告知已有預約
### Requirement: 預約狀態機
系統 SHALL 維護七個合法狀態，且只允許以下轉換：
- `pending` → `confirmed`（Provider 確認）
- `pending` → `rejected`（Provider 拒絕）
- `pending` → `member_cancelled`（Member 取消）
- `pending` → `expired`（Scheduler 超時）
- `confirmed` → `completed`（Scheduler 課程後自動）
- `confirmed` → `member_cancelled`（Member 取消）
- `confirmed` → `provider_cancelled`（Provider 取消）
#### Scenario: 非法狀態轉換被拒絕
- **WHEN** 任何角色嘗試執行上述以外的狀態轉換
- **THEN** 系統回傳 422，說明當前狀態不允許此操作
### Requirement: Provider 確認或拒絕預約
Provider SHALL 能對自己課程的 `pending` 預約執行確認或拒絕。
#### Scenario: 確認預約
- **WHEN** Provider 送出 `PUT /api/provider/bookings/{id}/confirm`
- **THEN** Booking status 改為 `confirmed`，時段 `current_participants` 更新
#### Scenario: 拒絕預約
- **WHEN** Provider 送出 `PUT /api/provider/bookings/{id}/reject`
- **THEN** Booking status 改為 `rejected`
#### Scenario: 只能操作自己課程的預約
- **WHEN** Provider 嘗試操作不屬於自己課程的 Booking
- **THEN** 系統回傳 403 Forbidden
### Requirement: Provider 取消已確認預約
Provider SHALL 能取消 `confirmed` 狀態的預約（例如天氣因素）。
#### Scenario: Provider 取消確認中預約
- **WHEN** Provider 送出 `PUT /api/provider/bookings/{id}/cancel`
- **THEN** Booking status 改為 `provider_cancelled`，時段名額釋放
### Requirement: Member 取消預約
Member SHALL 能取消自己的 `pending` 或 `confirmed` 預約，但須在課程開始前 24 小時之前提出。
#### Scenario: 取消 pending 預約（期限內）
- **WHEN** Member 送出 `DELETE /api/member/bookings/{id}`，Booking status 為 `pending`，且當前時間早於 `scheduled_date + start_time - 24h`
- **THEN** Booking status 改為 `member_cancelled`
#### Scenario: 取消 confirmed 預約（期限內）
- **WHEN** Member 送出 `DELETE /api/member/bookings/{id}`，Booking status 為 `confirmed`，且當前時間早於 `scheduled_date + start_time - 24h`
- **THEN** Booking status 改為 `member_cancelled`，時段名額釋放
#### Scenario: 課程開始前 24h 內不可取消
- **WHEN** Member 送出 `DELETE /api/member/bookings/{id}`，但當前時間距 `scheduled_date + start_time` 不足 24 小時
- **THEN** 系統回傳 422，告知「距課程開始不足 24 小時，無法取消，請聯繫教練」；Booking 狀態不變
#### Scenario: 不可取消已終態預約
- **WHEN** Booking status 為 `completed`、`rejected`、`expired`、`provider_cancelled`
- **THEN** 系統回傳 422，告知無法取消
### Requirement: 系統自動過期 pending 預約
Scheduler SHALL 每小時掃描 `pending` 超過 48 小時的 Booking 並標記為 `expired`。
#### Scenario: 過期觸發
- **WHEN** Booking status 為 `pending` 且 `created_at` 早於 48 小時前
- **THEN** Scheduler 將 status 改為 `expired`
### Requirement: 系統自動完成 confirmed 預約
Scheduler SHALL 每日掃描課程日期已過的 `confirmed` Booking 並標記為 `completed`。
#### Scenario: 自動完成
- **WHEN** Booking status 為 `confirmed`，對應 `course_schedule.scheduled_date` 早於今天
- **THEN** Scheduler 將 status 改為 `completed`
### Requirement: Member 查看自己的預約列表
Member SHALL 能查詢自己所有預約的列表及詳情。
#### Scenario: 取得預約列表
- **WHEN** 已登入 Member 送出 `GET /api/member/bookings`
- **THEN** 系統回傳該 Member 所有 Booking，含課程名稱、時段日期、狀態、金額
#### Scenario: 取得單一預約詳情
- **WHEN** 已登入 Member 送出 `GET /api/member/bookings/{id}`
- **THEN** 系統回傳該 Booking 詳情；若非本人預約則回傳 403
openspec/changes/archive/2026-05-12-booking-system/specs/course-scheduling/spec.md
+72
View File
@@ -0,0 +1,72 @@
## ADDED Requirements
### 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`。
#### 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`、日期未過的時段列表（含剩餘名額）
#### Scenario: 已滿時段不顯示
- **WHEN** 時段 status 為 `full`
- **THEN** 不包含在上述列表中