docs: 稽核文檔改為執行紀錄、開 provider-verification-gaps change 規劃遺留缺口

- 稽核報告：已完成的修補計畫改寫為執行紀錄（commit 對照表 + 偏差說明），未處理事項收斂為三項（verification 缺口 / 效能優化 / 新功能路線圖） - 新 change provider-verification-gaps：規劃 schedules/reviews 公開子端點過濾與預約入口檢查（含「既有預約不受影響」政策決定），待實作 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 19:06:34 +08:00
parent 520ec487ee
commit 99cf35c1ec
6 changed files with 146 additions and 96 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-11
@@ -0,0 +1,26 @@
+# Design — provider-verification-gaps
+
+## D1：預約入口擋在哪一層
+
+候選：
+- (a) `MemberBookingController::store` 的 Layer 1 快速失敗區（採用）——載入 `$schedule->divingOffer.provider.providerProfile` 後檢查，與既有「時段不開放」「名額不足」的 422 錯誤同層、同風格
+- (b) `CourseSchedule` 加 scope——過度設計，時段本身沒有可見性概念，可見性屬於課程
+
+回應訊息建議與既有風格一致：`['status' => false, 'message' => '此課程目前不開放預約']`，HTTP 422。不用 404：schedule id 是真實存在的資源，422 表達「請求合法但業務上不可行」。
+
+## D2：既有預約不受影響（關鍵政策決定）
+
+教練被取消驗證（toggle off）時：
+- **新預約**：擋（本 change 範圍）
+- **既有 pending**：教練仍可 confirm／reject——合約協商已開始，平台不單方面撕毀；若要更嚴格（pending 也凍結），屬產品決策，本 change 不做
+- **既有 confirmed / completed**：聊天、完課、評價全部照常——會員已付出時間成本，懲罰應落在教練（不能接新單）而非會員
+
+此政策需寫入規格 scenario，避免未來誤解為漏洞。
+
+## D3：visibleToPublic 的查詢成本
+
+`schedules` / `reviews` publicList 由 `findOrFail($offerId)` 改為 `visibleToPublic()->findOrFail($offerId)`，多一個 `whereExists` 子查詢（provider→providerProfile），單筆 by-id 查詢成本可忽略；兩端點目前無快取，無一致性問題。`store` 的檢查在 transaction 之外的 Layer 1 即可（教練驗證狀態變動頻率極低，不需要鎖）。
+
+## D4：測試歸屬
+
+擴充既有 `DivingOfferVisibilityTest`（同一保護目標：可見性），不另開檔案；預約入口的測試放 `BookingLifecycleTest`（屬建立預約的前置條件），各加 3~4 案例。
@@ -0,0 +1,30 @@
+## Why
+
+2026-06-11 修補（archive: `2026-06-11-audit-remediation`）讓未驗證教練的課程從公開 `GET /api/diving-offers`（列表/詳情）消失，但 `provider-verification` 規格 Notes 載明三個遺留缺口：
+
+1. `GET /api/diving-offers/{id}/schedules`（公開時段列表）未過濾——知道課程 id 仍可查到可預約時段
+2. `GET /api/diving-offers/{id}/reviews`（公開評價列表）未過濾——隱藏課程的評價仍可讀取
+3. `POST /api/member/bookings` 未檢查——會員可直接以 `schedule_id` 預約未驗證教練的課程，繞過整個可見性機制
+
+缺口 3 最關鍵：可見性過濾的目的（平台對教練資質把關）在預約入口被完全繞過。
+
+## What Changes
+
+- `ScheduleController::publicList`：`DivingOffer::findOrFail` 改為 `DivingOffer::visibleToPublic()->findOrFail`，隱藏課程的時段查詢回 404
+- `ReviewController::publicList`：同上，隱藏課程的評價查詢回 404
+- `MemberBookingController::store`：建立預約前驗證 schedule 所屬課程對該會員「可預約」（課程屬已驗證教練或 `provider_id` 為 null），否則回 422
+- **既有預約不受影響**：教練被取消驗證時，已成立的 pending / confirmed / completed 預約照常運作（含聊天、完課、評價）——只擋新預約，不毀既有合約
+- 補充 Feature tests 並更新 `provider-verification` 規格（Notes 移除、改為正式 Requirements）
+
+## Capabilities
+
+### Modified Capabilities
+
+- `provider-verification`：新增「公開子端點套用相同可見性」與「未驗證教練課程不可建立新預約」requirements；移除 Notes 中的已知限制聲明
+
+## Impact
+
+- 影響檔案：`ScheduleController`、`ReviewController`、`MemberBookingController`、`tests/Feature/DivingOfferVisibilityTest.php`（擴充）或新增測試檔
+- 行為變更：DemoSeeder 未驗證教練的課程時段/評價將不可公開查詢、不可新預約
+- 風險：低——`visibleToPublic` scope 已有 7 條測試保護，本 change 僅擴大套用範圍
+- 不影響：教練自有管理端點（`/api/provider/*`）、Admin 端點、既有預約的聊天與評價流程
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: 公開子端點套用相同可見性
+課程的公開子端點（`GET /api/diving-offers/{id}/schedules`、`GET /api/diving-offers/{id}/reviews`）SHALL 套用與課程詳情相同的可見性規則：課程屬未驗證教練時回傳 HTTP 404。
+
+#### Scenario: 隱藏課程的時段查詢回 404
+- **WHEN** 匿名使用者請求 `GET /api/diving-offers/{id}/schedules`，該課程屬未驗證教練
+- **THEN** 回傳 HTTP 404
+
+#### Scenario: 隱藏課程的評價查詢回 404
+- **WHEN** 匿名使用者請求 `GET /api/diving-offers/{id}/reviews`，該課程屬未驗證教練
+- **THEN** 回傳 HTTP 404
+
+#### Scenario: 可見課程的子端點正常
+- **WHEN** 課程屬已驗證教練或 `provider_id` 為 null
+- **THEN** 時段與評價端點照常回傳資料
+
+---
+
+### Requirement: 未驗證教練的課程不可建立新預約
+`POST /api/member/bookings` SHALL 在建立預約前驗證 schedule 所屬課程可預約（`provider_id` 為 null 或教練 `is_verified = true`），不符時回傳 HTTP 422，不建立預約。既有預約（pending / confirmed / completed）SHALL 不受教練驗證狀態變動影響：教練仍可處理 pending、confirmed 的聊天與完課流程照常、completed 可正常評價。
+
+#### Scenario: 未驗證教練課程的新預約被拒絕
+- **WHEN** 會員以未驗證教練課程的 schedule_id 送出預約
+- **THEN** 回傳 HTTP 422，`{ status: false, message: "此課程目前不開放預約" }`，不建立 Booking
+
+#### Scenario: 教練被取消驗證後既有預約照常
+- **WHEN** 教練在預約 confirmed 之後被取消驗證
+- **THEN** 該預約的聊天、完課、評價流程照常運作；僅新預約被擋
@@ -0,0 +1,19 @@
+## 1. 公開子端點套用可見性
+
+- [ ] 1.1 `ScheduleController::publicList`：`DivingOffer::findOrFail($offerId)` → `DivingOffer::visibleToPublic()->findOrFail($offerId)`
+- [ ] 1.2 `ReviewController::publicList`：同 1.1
+- [ ] 1.3 [整合測試] `DivingOfferVisibilityTest` 擴充：未驗證教練課程的 `/schedules` 回 404、`/reviews` 回 404、已驗證教練兩端點正常（3~4 案例）
+
+## 2. 預約入口檢查
+
+- [ ] 2.1 `MemberBookingController::store` Layer 1 增加課程可預約檢查（provider_id null 或教練已驗證），不符回 422 `此課程目前不開放預約`
+- [ ] 2.2 [整合測試] `BookingLifecycleTest` 擴充：未驗證教練課程的 schedule 不可建立預約（422）、已驗證可預約、教練被取消驗證後既有 confirmed 預約聊天/完課照常（3 案例）
+
+## 3. 規格同步
+
+- [ ] 3.1 `openspec/specs/provider-verification/spec.md`：新增「公開子端點套用相同可見性」「未驗證教練課程不可建立新預約」requirements（含既有預約不受影響 scenario），移除 Notes 已知限制段落
+
+## 4. 驗證
+
+- [ ] 4.1 容器內 `php artisan test` 全綠（基準：146 passed）
+- [ ] 4.2 手動驗證 DemoSeeder 未驗證教練課程：時段/評價查詢 404、無法新預約