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>

openspec/changes/archive/2026-05-25-swagger-api-docs-completion/design.md

@@ -0,0 +1,63 @@
+## Context
+
+現有 `app/Docs/AuthApiDoc.php` 已建立 Swagger 基礎設定（`@OA\Info`、`@OA\Server`、`@OA\SecurityScheme`）並文件化 15 個 Auth 端點。其餘 61 個端點分散在 8 個 Controller 中，沒有任何 `@OA` 標注。`darkaonline/l5-swagger` 已安裝，執行 `php artisan l5-swagger:generate` 即可重新產生 JSON。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 補齊所有 61 個未文件化端點的 `@OA` 標注
+- 定義共用 Schema（分頁 meta、統一錯誤格式、DivingOffer、Review、Booking 等）
+- 文件依模組分檔，每個新檔對應一個 `app/Docs/*Doc.php`
+- 每個端點包含：summary、parameters、request body（POST/PUT）、response（200/201/400/401/403/422）
+
+**Non-Goals:**
+- 不修改任何 Controller / Route / Model 邏輯
+- 不為尚未實作的端點（金流、訂閱）補文件
+
+## Decisions
+
+### 決策 1：分檔策略 — 依模組建立獨立 Doc 類別
+
+**選擇**：每個模組一個 `app/Docs/*Doc.php`
+
+| 檔案 | 涵蓋端點 |
+|------|---------|
+| `AuthApiDoc.php` | **修正路徑錯誤**（`/register/member` → `/member/register` 等）；補 `POST /logout`、`GET /user` |
+| `PublicApiDoc.php` | 公開端點（diving-offers、reviews、schedules） |
+| `MemberApiDoc.php` | Member bookings、reviews、helpful、notifications |
+| `ProviderApiDoc.php` | Provider offers、images、schedules、bookings |
+| `AdminApiDoc.php` | Admin stats、users、offers、bookings、reviews |
+| `AuthSupplementDoc.php` | **僅** Google OAuth 2 個端點（`SocialAuthController`） |
+
+**理由**：單一大檔難以維護；按模組分檔讓每個 Doc 類別職責清晰，對應 Controller 結構
+
+**替代方案**：直接在 Controller 方法上加 `@OA` → 拒絕，Controller 文件與業務邏輯混雜，讀性差
+
+### 決策 2：共用 Schema 集中定義在 `PublicApiDoc.php`
+
+共用 Schema（`DivingOfferSchema`、`ReviewSchema`、`BookingSchema`、`PaginationMeta`、`ApiErrorResponse`）集中放在 `PublicApiDoc.php` 頂層 `@OA\Schema` 標注。
+
+**理由**：l5-swagger 掃描所有 `app/` 目錄，Schema 定義位置不影響其他檔案引用；放在 Public 層語意上最自然（核心資料結構）
+
+### 決策 3：Security 標注策略
+
+- 公開端點：不加 `security`
+- Member 端點：`security={{"bearerAuth": {}}}`（現有 scheme）
+- Provider 端點：`security={{"bearerAuth": {}}}`
+- Admin 端點：`security={{"bearerAuth": {}}}`
+
+三個 role 共用同一個 `bearerAuth` scheme，由後端 middleware 區分角色，不需要在 Swagger 定義三個不同 scheme。
+
+## Risks / Trade-offs
+
+- **[Risk] 手寫標注與實際 response 不同步** → 以實際 Controller 程式碼為準手寫；未來有 API 變更時需同步更新 Doc 檔
+- **[Risk] Schema 巢狀複雜導致 Swagger UI 渲染慢** → 分頁 response 使用 `allOf` 組合，避免深層巢狀
+
+## Migration Plan
+
+1. 依序建立 5 個新 Doc 檔案
+2. 在容器內執行 `php artisan l5-swagger:generate`
+3. 開啟 `http://localhost:8080/api/documentation` 確認 UI 正確渲染
+4. 確認所有 tag 與端點均出現在 Swagger UI
+
+**Rollback**：直接刪除新增的 Doc 檔案，重新 generate 即可回復到只有 Auth 端點的狀態