CFDivePlatform/openspec/specs/feature-test-coverage/spec.md

# feature-test-coverage Specification

## Purpose
定義核心業務流程端點的測試覆蓋契約：Provider 課程 CRUD、時段管理、Admin 使用者操作、通知直接觸發路徑、預約列表端點。補齊 2026-06-11 稽核報告識別的 Feature test 缺口，確保這些端點的回歸能被測試套件即時攔截。

---

## Requirements

### Requirement: Provider 課程 CRUD 測試覆蓋
測試套件 SHALL 驗證 `POST /api/provider/offers`、`PUT /api/provider/offers/{id}`、`DELETE /api/provider/offers/{id}` 的正常流程與所有權邊界。

#### Scenario: Provider 建立課程成功
- **WHEN** 已認證的 Provider 送出有效的 title / location / price / region 至 `POST /api/provider/offers`
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, title, provider_id } }`，DB 存在對應記錄且 `provider_id` 為當前 Provider

#### Scenario: 建立課程缺少必填欄位回傳 422
- **WHEN** Provider 送出缺少 `title` 的請求至 `POST /api/provider/offers`
- **THEN** 回傳 HTTP 422，body 包含對應欄位的驗證錯誤

#### Scenario: Provider 更新自己的課程
- **WHEN** 已認證的 Provider 送出有效更新欄位至 `PUT /api/provider/offers/{id}`（該課程屬於此 Provider）
- **THEN** 回傳 HTTP 200，body 包含更新後的課程資料，DB 記錄已變更

#### Scenario: Provider 不可更新他人課程
- **WHEN** Provider A 嘗試 `PUT /api/provider/offers/{id}`，但該課程屬於 Provider B
- **THEN** 回傳 HTTP 403，body 包含 `{ status: false }`

#### Scenario: Provider 刪除自己的課程
- **WHEN** 已認證的 Provider 送出 `DELETE /api/provider/offers/{id}`（該課程屬於此 Provider）
- **THEN** 回傳 HTTP 200，body 包含 `{ status: true }`，DB 記錄已不存在

#### Scenario: Provider 不可刪除他人課程
- **WHEN** Provider A 嘗試 `DELETE /api/provider/offers/{id}`，但該課程屬於 Provider B
- **THEN** 回傳 HTTP 403

#### Scenario: 未認證請求被拒絕
- **WHEN** 未帶任何 token 送出 `POST /api/provider/offers`
- **THEN** 回傳 HTTP 401

---

### Requirement: Provider 時段管理測試覆蓋
測試套件 SHALL 驗證 `POST /api/provider/schedules`、`PUT /api/provider/schedules/{id}`、`DELETE /api/provider/schedules/{id}` 的正常流程、所有權邊界與容量驗證。

#### Scenario: Provider 建立時段成功
- **WHEN** Provider 送出有效的 diving_offer_id / scheduled_date（未來日期）/ start_time / max_participants 至 `POST /api/provider/schedules`
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, scheduled_date, status: "open" } }`

#### Scenario: Provider 不可為他人課程建立時段
- **WHEN** Provider A 送出 Provider B 課程的 diving_offer_id 至 `POST /api/provider/schedules`
- **THEN** 回傳 HTTP 403

#### Scenario: 時段日期不可為過去
- **WHEN** Provider 送出 scheduled_date 為過去日期
- **THEN** 回傳 HTTP 422

#### Scenario: Provider 更新時段人數上限
- **WHEN** Provider 送出新的 max_participants 至 `PUT /api/provider/schedules/{id}`（新值 ≥ 目前 current_participants）
- **THEN** 回傳 HTTP 200，DB 記錄已更新

#### Scenario: 人數上限不可低於已確認人數
- **WHEN** Provider 嘗試將 max_participants 設為低於時段 current_participants 的值
- **THEN** 回傳 HTTP 422，message 說明不可低於已確認人數

#### Scenario: Provider 不可更新他人時段
- **WHEN** Provider A 嘗試 `PUT /api/provider/schedules/{id}`，但該時段屬於 Provider B
- **THEN** 回傳 HTTP 403

#### Scenario: 刪除時段同時將進行中預約標記為 provider_cancelled
- **WHEN** Provider 對有 pending/confirmed 預約的時段送出 `DELETE /api/provider/schedules/{id}`
- **THEN** 回傳 HTTP 200；時段 status 改為 `cancelled`（記錄保留，不刪除）；該時段的 pending/confirmed booking status 改為 `provider_cancelled`（記錄保留，不刪除）；已是終態的 booking（completed/expired/已取消）不受影響

---

### Requirement: Admin 使用者管理測試覆蓋
測試套件 SHALL 驗證 Admin 查詢會員/教練列表、切換帳號啟用狀態、切換教練驗證狀態的正確行為。

#### Scenario: Admin 取得會員列表
- **WHEN** Admin 送出 `GET /api/admin/members`
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=member 的使用者

#### Scenario: Admin 取得教練列表
- **WHEN** Admin 送出 `GET /api/admin/providers`
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=provider 的使用者

#### Scenario: Admin 切換會員帳號啟用狀態
- **WHEN** Admin 送出 `PUT /api/admin/members/{id}/toggle-active`（目標會員 is_active=true）
- **THEN** 回傳 HTTP 200，DB 記錄 is_active 由 true 變為 false

#### Scenario: Admin 核准教練審核
- **WHEN** Admin 對 `verification_status=pending` 的教練送出 `PUT /api/admin/verifications/{userId}/approve`
- **THEN** 回傳 HTTP 200，provider_profiles.verification_status 變為 `approved`
- **NOTE** `toggle-verified` 路由已由 provider-verification-workflow 移除，驗證狀態變更一律透過審核狀態機

#### Scenario: 非 Admin 角色被拒絕
- **WHEN** role=member 的使用者送出 `GET /api/admin/members`
- **THEN** 回傳 HTTP 403

---

### Requirement: 通知直接觸發路徑測試覆蓋
測試套件 SHALL 驗證預約 controller 操作直接觸發的通知事件，補足 Scheduler 路徑以外的覆蓋缺口。收件者依實際 controller 實作：新預約與 member 取消通知教練，其餘通知學員。

#### Scenario: 建立預約觸發 BookingCreatedNotification 至教練
- **WHEN** Member 成功建立預約（`POST /api/member/bookings`）
- **THEN** `BookingCreatedNotification` 被派發至該預約所屬的 **Provider**

#### Scenario: Provider 確認預約觸發 BookingConfirmedNotification 至學員
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/confirm`
- **THEN** `BookingConfirmedNotification` 被派發至該預約的 **Member**

#### Scenario: Provider 拒絕預約觸發 BookingRejectedNotification 至學員
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/reject`
- **THEN** `BookingRejectedNotification` 被派發至該預約的 **Member**

#### Scenario: Member 取消預約觸發 BookingCancelledNotification 至教練
- **WHEN** Member 對 pending 預約呼叫 `DELETE /api/member/bookings/{id}`
- **THEN** `BookingCancelledNotification` 被派發至該預約所屬的 **Provider**

#### Scenario: Provider 取消預約觸發 BookingCancelledNotification 至學員
- **WHEN** Provider 對 confirmed 預約呼叫 `PUT /api/provider/bookings/{id}/cancel`
- **THEN** `BookingCancelledNotification` 被派發至該預約的 **Member**

---

### Requirement: 預約列表端點測試覆蓋
測試套件 SHALL 驗證下列三個路由的資料隔離行為：
- `GET /api/member/bookings`（middleware: `auth:sanctum`，隔離靠 `where member_id = auth()->id()`）
- `GET /api/provider/bookings`（middleware: `auth:sanctum`，隔離靠 `whereHas schedule.provider_id`）
- `GET /api/admin/bookings`（middleware: `auth:sanctum` + `admin`，EnsureAdmin 於 middleware 層強制 403）

#### Scenario: Member 只能看到自己的預約
- **WHEN** Member A 呼叫 `GET /api/member/bookings`，系統中同時存在 Member A 與 Member B 各一筆預約
- **THEN** 回傳 data 只包含 Member A 的 booking id；Member B 的 booking id 不在 data 中

#### Scenario: Provider 只能看到屬於自己課程的預約
- **WHEN** Provider A 呼叫 `GET /api/provider/bookings`，系統中有屬於 Provider A 與 Provider B 課程各一筆預約
- **THEN** 回傳 data 只包含 Provider A 課程的 booking id；Provider B 課程的 booking id 不在 data 中

#### Scenario: Admin 可查看所有預約
- **WHEN** Admin 呼叫 `GET /api/admin/bookings`，系統中有 2 筆不同 Member 的預約
- **THEN** 回傳 data 包含兩筆 booking id

#### Scenario: 未認證請求被拒絕
- **WHEN** 未帶 token 呼叫 `GET /api/member/bookings`
- **THEN** 回傳 HTTP 401