From 529ba94dc7b7781c5cfa656c7c2d8f7931b534e9 Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:20:26 +0800 Subject: [PATCH 1/2] =?UTF-8?q?chore(openspec):=20=E6=9B=B4=E6=96=B0=20con?= =?UTF-8?q?fig.yaml=20=E5=B0=88=E6=A1=88=20context=20=E4=B8=A6=E8=A3=9C?= =?UTF-8?q?=E4=B8=8A=20proposal/specs/design/tasks=20=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- openspec/config.yaml | 91 +++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 31 deletions(-) diff --git a/openspec/config.yaml b/openspec/config.yaml index 041a038..7f8064f 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -3,55 +3,84 @@ schema: spec-driven context: | ## 專案：CFDivePlatform 潛水課程媒合平台，連結潛水教練（Provider）與學員（Member）。 + 各功能的行為以 `openspec/specs/` 為準；本段只描述專案背景與慣例，不逐項複製規格內容。 + 每次歸檔（archive）後，請檢查本段是否需要更新。 ## 架構 - - 後端：Laravel 11 + Sanctum（Bearer token）+ MySQL，跑在 Docker（cfdive-app / cfdive-nginx:8080） + - 後端：Laravel 11 + Sanctum（Bearer token）+ MySQL 8 + Redis（cache / session / queue） + - 即時通訊：Laravel Reverb（WebSocket），前端以 Laravel Echo 連線 + - 檔案儲存：`public` disk，支援切換為 S3 相容物件儲存（見 `file-storage-s3` spec） - 前端：Vue 3 + Vite + Tailwind CSS + Pinia + Vue Router 4 + Axios - 原始碼在 `frontend/`（同一個 repo） - - Docker image: cfdive-frontend，對外 port 5173 - - DB：MySQL 8（Docker），ORM 使用 Eloquent - - 部署：docker-compose，`docker-compose up --build` 即可啟動全部服務 + - 部署：Docker Compose，程式碼與 vendor 烘進 image，不使用 bind mount（見 `image-baked-deployment` spec） + - 服務：app（php-fpm）、nginx、frontend、db、redis、reverb、queue-worker、scheduler + - push master 會觸發 Gitea Actions 自動部署，因此變更一律走 PR，禁止直接 push master + - 測試：PHPUnit Feature / Unit，CI 與本機預設使用 SQLite；涉及 `lockForUpdate` 等行鎖行為的測試在 SQLite 上不具驗證力 ## 使用者角色 - - `member`：一般會員，瀏覽/搜尋課程，Google OAuth 登入 - - `provider`：教練/業者，管理自己的課程（CRUD），使用 ProviderProfile - - `admin`：平台管理員，尚未實作 + - `member`：一般會員，瀏覽/搜尋課程、預約、聊天、評價；Email 或 Google OAuth 登入 + - `provider`：教練/業者，管理課程、時段、預約；需通過資格審核才會公開課程與接受預約 + - `admin`：平台管理員；帳號只能由主機端 `php artisan app:create-admin` 建立，不提供公開註冊 + - 角色存於 `users.role`，三種角色各有獨立的登入端點與 Profile 資料表 - ## 已完成模組 - - Member Portal（`/`、`/courses`、`/login`、`/register`、`/profile`） - - Coach Portal（`/coach/*`）：登入、註冊、課程 CRUD Dashboard、個人資料 - - Diving Offers 公開 API（`GET /api/diving-offers`、`GET /api/diving-offers/{id}`） - - Provider Auth API（`/api/provider/login|register|logout|profile`） - - Provider Offers API（`/api/provider/offers` CRUD，含 provider_id 所有權驗證） + ## 已實作範圍（細節見對應 spec） + - Member Portal、Coach Portal（`/coach/*`）、Admin Panel（`/admin/*`） + - 認證：三角色登入、Token Refresh、登入限流、帳號鎖定、OAuth state 驗證 + - 課程（diving offers）公開查詢與教練 CRUD、課程圖片上傳（含伺服器端壓縮） + - 課程時段、預約生命週期（pending → confirmed → completed / 取消）、名額超賣防護 + - 預約即時訊息（文字 + 圖片、已讀回執）、使用者在線狀態 + - 評價（含匿名、編輯紀錄、有幫助投票） + - 站內通知與 Email 通知（除即時訊息通知外皆經 Queue 處理） + - 教練資格審核（證照上傳、送審、通過 / 駁回 / 撤銷） + - 排程：逾期 pending 預約自動失效、已結束預約自動完成 + - Swagger（l5-swagger）API 文件，註解集中於 `app/Docs/` + + ## 尚未實作 + - 金流整合 + - 訂閱方案（`subscriptions` / `plans` 資料表已於 2026-05-25 移除） ## 關鍵資料模型 - - `users`：role enum（member / provider / admin），`is_active` - - `provider_profiles`：業者資料（business_name、certifications、dive_sites 等） - - `member_profiles`：會員資料（birthday、gender、emergency_contact 等） - - `diving_offers`：課程（title、location、spot、price、region、tag、badges JSON、provider_id nullable FK） - - `subscriptions` / `plans`：訂閱方案（尚未實作 API） + - `users`：role（member / provider / admin）、`is_active` + - `provider_profiles`：業者資料與 `verification_status`；`provider_certifications`：證照 + - `member_profiles`、`admin_profiles` + - `diving_offers`（含 `provider_id`、`cover_image`）、`course_images` + - `course_schedules`（含 `max_participants` / `current_participants`）、`bookings` + - `reviews`、`review_edits`、`review_votes` + - `booking_messages`、`notifications`、`social_accounts` ## 前端慣例 - - Member 認證：`src/stores/auth.js`，localStorage key `token` / `user` - - Coach 認證：`src/stores/coachAuth.js`，localStorage key `coach_token` / `coach_user` - - Member Axios：`src/api/axios.js` - - Coach Axios：`src/api/coachAxios.js` - - Coach 頁面包在 `src/layouts/CoachLayout.vue`（含 CoachNavBar） - - 所有 `/coach/*` protected 路由：`meta: { requiresCoach: true }` + - 三組認證各自獨立：Axios 實例、Pinia store、storage key 皆分開 + - Member：`src/stores/auth.js`、`src/api/axios.js`，sessionStorage `token` / `user` + - Coach：`src/stores/coachAuth.js`、`src/api/coachAxios.js`，sessionStorage `coach_token` / `coach_user` + - Admin：`src/stores/adminAuth.js`、`src/api/adminAxios.js`，localStorage `admin_token` / `admin_user` + （與其他兩者不一致為已知議題，見 docs/analysis/2026-10-14-project-review-todo.md M4） + - Coach 頁面包在 `CoachLayout.vue`，Admin 頁面包在 `AdminLayout.vue` + - Protected 路由以 route meta 標示：`requiresAuth`（member）、`requiresCoach`、`requiresAdmin` + - 401 時自動以 refresh token 換新並重試 + + ## 後端慣例 + - Controller 位於 `app/Http/Controllers/API/`，Swagger 註解位於 `app/Docs/` + - 路由集中於 `routes/api.php`；admin 群組以 `admin` middleware 保護 + - member / provider 路由群組目前僅有 `auth:sanctum`，角色檢查需在 Controller 內自行處理 + （已知缺口，見 docs/analysis/2026-10-14-project-review-todo.md H1；新增路由時不可假設已有角色保護） ## API 回應格式 成功：`{ status: true, message?: "...", data: {...} 或 [...] }` 失敗：`{ status: false, message: "...", errors?: {...} }` - ## 尚未實作 - - Admin Panel - - 預約/訂單系統 - - 金流整合 - - 課程圖片上傳 - - 教練審核流程 - rules: + proposal: + - 必須列出受影響的主規格（`openspec/specs/` 下的 capability 名稱） + - 必須說明是否影響既有 API 回應格式或前端行為 + specs: + - 每個 Requirement 至少要有一個 `#### Scenario` + - Scenario 必須具體到可直接轉成測試（明確的前置條件、動作、預期的 HTTP 狀態碼與回應內容） + - 涉及角色權限的 Requirement，必須明確寫出各角色（member / provider / admin / 未登入）的預期結果 + design: + - 若涉及 CLAUDE.md 列出的安全觸發條件（外部輸入、資料庫讀寫、身份驗證/授權、檔案上傳、外部 API），必須包含「安全確認」段落，回答輸入驗證、資料庫存取方式、權限檢查層級 + - 新增或修改的路由必須註明所掛的角色 middleware 或 Controller 內的所有權檢查 tasks: - 後端任務標記 [後端]，前端任務標記 [前端]，整合測試標記 [整合測試] - 每個 task 描述應包含具體的檔案路徑或方法名稱 + - 每個 spec 的 Scenario 至少要對應一個 [整合測試] task，缺少對應者不得進入實作 - 手動驗證類 task 放在最後一個 group From db4f11a7401f1ae219ebc0d368dda67f3124a46a Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:22:19 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(analysis):=20=E4=BF=AE=E6=AD=A3=20M3?= =?UTF-8?q?=20=E6=8F=8F=E8=BF=B0=EF=BC=8C=E9=80=9A=E7=9F=A5=E5=AF=A6?= =?UTF-8?q?=E9=9A=9B=E5=B7=B2=E5=A4=9A=E6=95=B8=E4=BD=BF=E7=94=A8=20Should?= =?UTF-8?q?Queue=EF=BC=8C=E4=B8=8B=E4=BF=AE=E5=84=AA=E5=85=88=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-14-project-review-todo.md | 34 ++++++++++++------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/analysis/2026-10-14-project-review-todo.md b/docs/analysis/2026-10-14-project-review-todo.md index 5f3e596..f1939af 100644 --- a/docs/analysis/2026-10-14-project-review-todo.md +++ b/docs/analysis/2026-10-14-project-review-todo.md @@ -16,12 +16,12 @@ | H2 | 🔴 高 | 正式環境 `APP_DEBUG` 與預設值風險 | 否（設定確認）+ 視情況改 `.env.example` | — | | M1 | 🟡 中 | AuthController 過大、無 FormRequest／Service 層 | 是 | `refactor-auth-controller` | | M2 | 🟡 中 | 預約名額邏輯重複 | 是 | `extract-booking-service` | -| M3 | 🟡 中 | 通知同步發送且例外被吞掉 | 是 | `queue-booking-notifications` | +| M3 | 🟡 中（已下修，見內文） | 通知派送的例外處理與失敗可觀測性 | 視範圍而定 | `harden-notification-dispatch` | | M4 | 🟡 中 | 前端 token 儲存不一致（admin 用 localStorage） | 是 | `unify-frontend-token-storage` | | M5 | 🟡 中 | CORS 在正式環境仍允許 localhost | 是（小） | `restrict-cors-by-env` | | M6 | 🟡 中 | CI 使用 SQLite，鎖定／超賣測試可能假綠 | 是 | `ci-mysql-test-job` | -建議順序：H1 → H2 → M6 → M5 → M3 → M2 → M1 → M4。 +建議順序：H1 → H2 → M6 → M5 → M2 → M1 → M4 → M3（M3 已下修，可視驗證結果延後或關閉）。 理由：H1 是安全漏洞；M6 先建立可信的測試基礎，後續重構（M1、M2）才有安全網。 --- @@ -120,21 +120,31 @@ --- -## M3　通知同步發送，例外被吞掉 +## M3　通知派送的例外處理與失敗可觀測性 + +> 2026-10-14 更新：初版誤判為「通知同步發送」。實際檢查後，9 個 Notification 中 8 個已實作 `ShouldQueue` 並設有 `public int $tries = 3`，`cfdive-queue` 容器也已在跑。原本的風險大幅降低，本項由「中」下修，並縮小範圍。 **現況** -`MemberBookingController`、`ProviderBookingController` 多處以 `try { notify() } catch (\Throwable) { Log::error }` 發送通知。 +- `BookingCreated`、`BookingConfirmed`、`BookingRejected`、`BookingCancelled`、`BookingCompleted`、`ProviderVerificationApproved`、`ProviderVerificationRejected`、`ReviewReceived`：皆為 `ShouldQueue`，`tries = 3` +- `NewBookingMessageNotification`：**未**實作 `ShouldQueue`，檔案內註解說明是刻意同步，讓後續的 `NotificationCreated` broadcast 能立刻讓前端拉到正確的未讀數 +- `MemberBookingController`、`ProviderBookingController` 仍以 `try { notify() } catch (\Throwable) { Log::error }` 包住派送 -**風險** -- 若 Notification 未實作 `ShouldQueue`，會在請求內同步寄信，拖慢回應 -- 失敗只留 log，沒有重試，也沒有告警（Sentry 不會收到被吞掉的例外） +**仍存在的風險** +- try/catch 現在只會攔到「派送入列」階段的失敗（例如 Redis 無法連線），這可能是刻意讓預約流程不因通知失敗而中斷；但例外只進 log，不會送 Sentry，也沒有補送機制 +- 8 個 Notification 都只設了 `tries`，沒有 `backoff`，重試會立刻連續發生，對暫時性故障（SMTP、Redis 抖動）幫助有限 +- 沒有 `failed()` 處理：重試用完後只留在 `failed_jobs`，是否會送到 Sentry **我不確定，需要驗證** +- `NewBookingMessageNotification` 同步發送，聊天頻繁時會增加請求延遲（且有 Redis broadcast 依賴） **待辦** -- [ ] 檢查 `app/Notifications/*` 是否皆實作 `ShouldQueue` -- [ ] 改為交由 queue worker 處理（`cfdive-queue` 容器已存在），並設定 `tries`／`backoff` -- [ ] 移除 Controller 內的 try/catch，改用 queue 失敗處理；必要時以 `report($e)` 送 Sentry -- [ ] 更新 `NotificationTriggerTest` 使用 `Queue::fake()` 或 `Notification::fake()` -- [ ] 更新 spec：`notification-core`、`notification-triggers`、`notification-email` +- [ ] 先驗證：讓一個 Notification job 失敗，確認 Sentry 是否收到；確認 `failed_jobs` 是否有人監看 +- [ ] 為 8 個 queued Notification 補上 `backoff`（例如 `[10, 60, 300]`） +- [ ] 將 Controller 內的 `Log::error` 改為 `report($e)`，讓 Sentry 收到派送失敗，並保留「不中斷主流程」的行為 +- [ ] 評估 `NewBookingMessageNotification` 是否能在不破壞未讀數即時性的前提下改為 queued（可能需調整 broadcast 時序），不可行則在 spec 註明為刻意設計 +- [ ] 更新 `NotificationTriggerTest` 涵蓋失敗情境 +- [ ] 如行為有變更，更新 spec：`notification-core`、`notification-triggers`、`notification-email` + +**備註** +若驗證後發現 Sentry 已能收到失敗，且 Redis 故障非實際風險，本項可降為低優先或直接關閉。 ---