docs:補全所有 API 端點 Swagger 文件（73 個端點）

- 修正 AuthApiDoc.php 路徑錯位（/register/member → /member/register 等）及 change-password 方法（Post→Put）；補上 POST /logout、GET /user - 新增 AuthSupplementDoc.php（Google OAuth 2 端點） - 新增 PublicApiDoc.php（共用 Schema + 公開課程 4 端點） - 新增 MemberApiDoc.php（預約、評價、通知共 13 端點） - 新增 ProviderApiDoc.php（課程、圖片、時段、預約管理共 18 端點） - 新增 AdminApiDoc.php（統計、會員/教練/課程管理共 16 端點） - 更新 README.md - 歸檔 swagger-api-docs-completion change，同步主規格 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-25 01:17:25 +08:00
parent 95bafef52d
commit 05ef8b9316
22 changed files with 6492 additions and 66 deletions
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Admin 端點 Swagger 文件
+
+`app/Docs/AdminApiDoc.php` SHALL 文件化所有需要 Admin Bearer token 的管理端點。
+
+#### Scenario: Admin stats 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** `GET /admin/stats` 端點有文件，response 包含 `total_members`、`total_providers`、`total_offers`；403 非 admin 亦有定義
+
+#### Scenario: Admin 會員管理端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件，標示 `security: bearerAuth`：
+  - `GET /admin/members`（分頁 response，含 member_profile）
+  - `GET /admin/members/{id}`
+  - `PUT /admin/members/{id}/toggle-active`（response: is_active 新狀態）
+  - `GET /admin/check-member/{id}`
+
+#### Scenario: Admin 教練管理端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /admin/providers`（分頁 response，含 provider_profile）
+  - `GET /admin/providers/{id}`
+  - `PUT /admin/providers/{id}/toggle-active`
+  - `PUT /admin/providers/{id}/toggle-verified`（response: is_verified 新狀態）
+  - `GET /admin/check-provider/{id}`
+
+#### Scenario: Admin 課程、預約、評價管理端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /admin/offers`（分頁 response）
+  - `DELETE /admin/offers/{id}`
+  - `GET /admin/bookings`（分頁 response）
+  - `PUT /admin/bookings/{id}/complete`
+  - `GET /admin/reviews`（分頁 response，含 per_page 參數，最大 100）
+  - `DELETE /admin/reviews/{id}`
@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: Auth 補全端點 Swagger 文件
+
+`app/Docs/AuthSupplementDoc.php` SHALL 補全未文件化的 Auth 相關端點（Google OAuth、change-password）。
+
+#### Scenario: Google OAuth 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /auth/google/redirect`（response: redirect_url，說明用途為取得 Google OAuth redirect URL）
+  - `GET /auth/google/callback`（response: token + user，說明此為 OAuth callback，通常由瀏覽器自動呼叫）
+
+#### Scenario: change-password 端點文件化（三個 role）
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件，各自標示對應 role 的 `security: bearerAuth`：
+  - `PUT /member/change-password`（request: current_password、password、password_confirmation）
+  - `PUT /provider/change-password`（同上）
+  - `PUT /admin/change-password`（同上）
+  - 422 驗證失敗 response 亦有定義
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Member 端點 Swagger 文件
+
+`app/Docs/MemberApiDoc.php` SHALL 文件化所有需要 Member Bearer token 的端點（bookings、reviews、helpful 投票、notifications）。
+
+#### Scenario: Member bookings 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件，並標示 `security: bearerAuth`：
+  - `POST /member/bookings`（request: schedule_id；response 201: Booking）
+  - `GET /member/bookings`（response: Booking 陣列 + 分頁 meta）
+  - `GET /member/bookings/{id}`（response: Booking 詳情）
+  - `DELETE /member/bookings/{id}`（response 200: message）
+
+#### Scenario: Member reviews 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `POST /member/reviews`（request: diving_offer_id、rating、comment；403 資格驗證失敗；422 重複評價）
+  - `PUT /member/reviews/{id}`（request: rating?、comment?；403 非本人）
+  - `DELETE /member/reviews/{id}`（403 非本人）
+  - `POST /reviews/{id}/helpful`（toggle，response: helpful_count、has_voted）
+
+#### Scenario: Member notifications 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /notifications`（response: 通知陣列 + 分頁 meta）
+  - `GET /notifications/unread-count`（response: count）
+  - `PATCH /notifications/{id}/read`
+  - `PATCH /notifications/read-all`
+  - `DELETE /notifications/{id}`
@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Provider 端點 Swagger 文件
+
+`app/Docs/ProviderApiDoc.php` SHALL 文件化所有需要 Provider Bearer token 的端點（offers CRUD、圖片、schedules、bookings）。
+
+#### Scenario: Provider offers CRUD 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件，標示 `security: bearerAuth`：
+  - `GET /provider/offers`（分頁 response）
+  - `POST /provider/offers`（request: title、location、spot?、price、region、tag?、badges?、description?）
+  - `GET /provider/offers/{id}`（403 非本人）
+  - `PUT /provider/offers/{id}`（request 同上，所有欄位 nullable）
+  - `DELETE /provider/offers/{id}`
+
+#### Scenario: Provider 圖片管理端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `POST /provider/offers/{id}/cover`（multipart/form-data: image；response: cover_image_url）
+  - `DELETE /provider/offers/{id}/cover`
+  - `POST /provider/offers/{id}/images`（multipart/form-data: images[]；最多 10 張）
+  - `DELETE /provider/images/{id}`
+
+#### Scenario: Provider schedules 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /provider/schedules`（query: offer_id?；response: CourseSchedule 陣列）
+  - `POST /provider/schedules`（request: diving_offer_id、date、period、capacity）
+  - `PUT /provider/schedules/{id}`
+  - `DELETE /provider/schedules/{id}`
+
+#### Scenario: Provider bookings 端點文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 以下端點均有文件：
+  - `GET /provider/bookings`（response: Booking 陣列，含 member 資訊）
+  - `PUT /provider/bookings/{id}/confirm`
+  - `PUT /provider/bookings/{id}/reject`
+  - `PUT /provider/bookings/{id}/complete`
+  - `PUT /provider/bookings/{id}/cancel`
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: 公開端點 Swagger 文件及共用 Schema
+
+`app/Docs/PublicApiDoc.php` SHALL 文件化所有無需認證的公開端點，並定義全域共用 Schema。
+
+#### Scenario: 共用 Schema 定義完整
+
+- **WHEN** 執行 `php artisan l5-swagger:generate`
+- **THEN** 以下 Schema 出現在產生的 JSON：`DivingOffer`、`Review`、`CourseSchedule`、`PaginationMeta`、`ApiErrorResponse`
+
+#### Scenario: GET /api/diving-offers 文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** `GET /diving-offers` 端點顯示 query parameters（`q`、`region`、`tag`、`per_page`、`page`）及包含分頁 meta 的 response schema
+
+#### Scenario: GET /api/diving-offers/{id} 文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** `GET /diving-offers/{id}` 端點顯示 path parameter `id` 及包含 `cover_image_url`、`images` 陣列的 response schema；404 response 亦有定義
+
+#### Scenario: GET /api/diving-offers/{id}/reviews 文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 端點顯示 `sort`（helpful/rating/newest）、`page`、`per_page` 參數；response 包含 `summary`（average、total、distribution）與分頁 `meta`
+
+#### Scenario: GET /api/diving-offers/{id}/schedules 文件化
+
+- **WHEN** 開啟 Swagger UI
+- **THEN** 端點顯示 response 包含 `CourseSchedule` 陣列（id、date、period、capacity、booked_count、status）