CFDivePlatform/docs/analysis/2026-06-11-spec-implementation-audit.md

CFDivePlatform 規格與實作分析報告暨修補計畫

分析日期：2026-06-11 分析範圍：openspec/specs/（32 份規格）vs 後端實作（Laravel 11）、前端（frontend/ Vue 3）、測試（tests/） 分析基準：branch test/auth-tests-coverage（commit ca5b843，與 master 同步）

---

一、現況總覽

1.1 規格狀態

• OpenSpec 規格共 32 份，全部 change 已歸檔（openspec/changes/ 僅剩 archive/，無進行中 change）。
• 涵蓋範圍：認證安全（lockout / rate-limiting / OAuth state / token refresh）、三角色入口（Member / Coach / Admin）、預約生命週期、評價系統、通知系統、即時聊天、Swagger 文件、效能優化。

1.2 實作狀態

模組	規格	實作	測試
認證（三角色登入/註冊/登出）	✅	✅	✅ 39 案例
帳號鎖定 + OAuth state	✅	✅	✅ 15 案例
Token Refresh	✅	✅	✅ 11 案例
課程 CRUD + 圖片上傳	✅	✅	✅ 14 案例
開課時段管理	✅	✅	❌ 無
預約生命週期（七狀態機、防超賣、Scheduler）	✅	✅	❌ 無
評價系統（匿名、投票、rating 重算）	✅	✅	✅ 32 案例
通知系統（站內 + Email）	✅	✅	❌ 無
即時聊天 + Presence	✅	✅	❌ 無
Admin 管理端點（stats / users / offers / bookings / reviews）	✅	✅	❌ 無
教練審核流程	❌ 無規格	⚠️ 僅半套（見 P1-1）	❌ 無
金流整合	❌ 無規格	❌ 未實作	—

整體而言規格與實作的對應度高，路由、端點、middleware 配置大致與規格一致。以下列出本次稽核發現的偏差與風險。

---

二、發現問題（依嚴重度排序）

🔴 P0-1：POST /api/admin/register 完全公開，任何人可註冊管理員帳號

• 位置：routes/api.php:106、AuthController::registerAdmin()（AuthController.php:852）
• 事實：該路由無任何 middleware、無邀請碼、無「僅限第一位管理員」檢查；request 通過基本驗證後直接 role => 'admin' 建立帳號。
• 影響：攻擊者一個 HTTP 請求即可取得全平台管理權限（停權用戶、刪課程、刪評價、看全部個資），使 P0~P2 所有認證安全強化形同虛設。
• 規格對應：admin-auth 規格只定義「管理員登入」，從未定義公開註冊端點——此端點本身就是規格外實作。
• 附帶問題：密碼規則僅 min:6，低於一般管理帳號標準。

🟠 P1-1：is_verified（教練驗證）從未被任何業務邏輯強制執行

• 事實：is_verified 只出現在兩處——Admin 的 toggleProviderVerified()（AdminUserController.php:144）與 Model 屬性定義。教練註冊後不需任何審核即可登入、上架課程、被公開列表曝光、接受預約。
• 影響：Admin 後台的「驗證教練」開關是純展示功能，平台對教練資質零把關。這就是記憶中「教練審核流程未實作」的實際狀態：開關存在、約束不存在。
• 規格對應：目前沒有任何規格定義 is_verified 的業務語意（未驗證教練能做什麼/不能做什麼），屬規格空洞。

🟠 P1-2：登入頻率限制規格與實作不一致（規格漂移）

• 規格（openspec/specs/login-rate-limiting/spec.md）：Member / Provider 每 IP 每分鐘最多 5 次。
• 實作（routes/api.php:31,67）：throttle:10,1，即 10 次。
• 測試（AuthRateLimitTest.php）：已在 commit 0dabc4e 改為斷言 10 次，與實作一致、與規格矛盾。
• 影響：規格失去單一真實來源（single source of truth）地位。未來任何人依規格實作或稽核都會得出錯誤結論。Admin 的 3 次限制則規格實作一致。

🟡 P2-1：核心業務流程（預約）零測試覆蓋

• 現有 97 個測試案例集中在認證（70）、評價（32 中含投票）、圖片（14）。
• 預約狀態機（七狀態）、防超賣鎖定、Scheduler 自動過期/完成（ExpirePendingBookings、CompleteFinishedBookings）——平台最核心、含金量最高、最容易因修改而回歸的邏輯——沒有任何一條測試。
• 同樣無測試：時段管理（時段重疊/容量）、通知觸發、聊天授權（presence channel 參與方驗證）、全部 Admin 端點（含 P0-1 的權限邊界）。
• 依 CLAUDE.md Rule 9，這些測試需編碼「為什麼」：防超賣測試保護的是金錢與信任，狀態機測試保護的是不可逆操作的合法轉移。

🟡 P2-2：規格維護債

1. auth-test-coverage/spec.md 的 Purpose 仍是 TBD - created by archiving change，歸檔後未補。
2. member-portal-ui 規格寫「前端 SHALL 建立於獨立 repo」，實際前端在本 repo 的 frontend/ 目錄——規格描述已過時。
3. admin-auth 規格未涵蓋實際存在的 /admin/register、/admin/check-member/{id}、/admin/check-provider/{id} 端點。

---

三、修補計畫

Phase 1 — 立即（建議今天，0.5 天內）

T1.1 封鎖 POST /api/admin/register（對應 P0-1）

建議方案（擇一，建議 a）：

• (a) 移除公開路由，改為 artisan command php artisan admin:create（僅能從主機執行），生產環境的管理員一律由既有管理員或主機端建立。
• (b) 移入 auth:sanctum + admin middleware group（僅既有 admin 可開新 admin）——但需先用 (a) 或 seeder 解決第一位管理員的雞生蛋問題。

驗收標準：

• 未認證請求 POST /api/admin/register 回傳 404 或 401（不再是 201）。
• 補 Feature test：未授權者無法建立 admin 帳號。
• Demo seeder 既有的 admin 帳號不受影響。
• 同步新增/更新 admin-auth 規格段落，明確定義管理員帳號建立途徑。

T1.2 解決 rate-limiting 規格漂移（對應 P1-2）

• 先決定基準：5/min（規格）或 10/min（實作）。10/min 是後來有意調整（測試已配合修改），建議以實作為準、更新規格；若當初是誤改，則改回 5 並還原測試。
• 驗收標準：規格、routes/api.php、AuthRateLimitTest 三者數字一致。

Phase 2 — 短期（1~2 天）

T2.1 賦予 is_verified 最小業務語意（對應 P1-1，為完整教練審核流程鋪路）

最小可行約束（不做完整審核流程，僅堵住風險）：

• 未驗證 Provider 的課程不出現在公開列表 GET /api/diving-offers（或：未驗證 Provider 無法將課程上架/store() 回 403，二擇一，依產品決策）。
• 課程詳情頁顯示教練 is_verified 徽章（前端已有欄位可用）。
• 驗收標準：
  • 新增規格 provider-verification（最小版），定義未驗證教練的能力邊界。
  • Feature test：未驗證教練的課程不可被公開查詢（或不可建立）。
  • Admin toggle-verified 後行為立即生效（注意 api-cache-layer 的快取失效）。

完整審核流程（證照上傳、審核佇列、駁回原因）屬新功能，見《未來發展可行性評估》文檔。

Phase 3 — 中期（2~3 天）

T3.1 補預約核心測試（對應 P2-1，優先序由高至低）

1. BookingLifecycleTest：七狀態機合法/非法轉移（pending→confirmed→completed、reject、cancel、不可逆狀態防護）。
2. BookingOversellTest：併發/邊界情境下 confirmed 不超過時段容量；pending 不佔名額。
3. BookingSchedulerTest：app:expire-pending-bookings 與 app:complete-finished-bookings 的時間邊界。
4. BookingChatAuthTest：非參與方無法讀寫訊息、無法訂閱 presence channel。
5. AdminEndpointTest：非 admin token 存取 /api/admin/* 一律 403。

驗收標準：以上測試全綠且任一狀態機規則被改壞時至少一條測試會失敗（mutation 自查）。

Phase 4 — 規格清理（0.5 天，可與 Phase 3 並行）

• 補 auth-test-coverage 的 Purpose。
• 更新 member-portal-ui 的 repo 描述。
• admin-auth 補 check-member / check-provider 端點描述（register 端點依 T1.1 決策寫入或標記移除）。

---

四、風險與依賴

項目	風險	緩解
T1.1	前端 Admin 註冊頁（若存在）會失效	檢查 frontend/src/views/admin/，同步移除入口
T2.1	公開列表過濾可能影響 demo 資料展示	Demo seeder 將教練預設 is_verified=true
T3.1	測試需 MySQL 容器運行	沿用既有 php artisan test 容器內流程

五、規格同步狀態聲明

本報告本身不改動程式碼。執行修補計畫時需同步的規格文件：admin-auth（T1.1）、login-rate-limiting（T1.2）、新增 provider-verification（T2.1）、auth-test-coverage 與 member-portal-ui（Phase 4）。