docs: 稽核文檔改為執行紀錄、開 provider-verification-gaps change 規劃遺留缺口
Run Tests / test (pull_request) Successful in 2m1s
Run Tests / test (pull_request) Successful in 2m1s
- 稽核報告：已完成的修補計畫改寫為執行紀錄（commit 對照表 + 偏差說明）， 未處理事項收斂為三項（verification 缺口 / 效能優化 / 新功能路線圖） - 新 change provider-verification-gaps：規劃 schedules/reviews 公開子端點 過濾與預約入口檢查（含「既有預約不受影響」政策決定），待實作 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -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、無法新預約
|
||||
Reference in New Issue
Block a user