CFDivePlatform/openspec/changes/archive/2026-05-25-api-performance-optimization/design.md

Context

前端請求回應偏慢，調查後確認三個根本原因：

1. 無快取：所有請求直打 DB，cache driver 設為 database（等於又多一次 DB 查詢）
2. 全表查詢：AdminReviewController::index() 與 ReviewController::publicList() 直接 .get() 無分頁，資料量增長後線性惡化
3. 缺少索引：notifications 與 diving_offers 表缺少 WHERE clause 中常用欄位的索引，導致全表掃描

Goals / Non-Goals

Goals:

• 補全缺少的 DB 索引，消除 notifications / diving_offers 的全表掃描
• 將 ReviewController::publicList() 的 3 次 SQL 合併，並加入分頁
• AdminReviewController::index() 加入分頁（預設 20 筆）
• 引入 Redis 快取層，覆蓋 Admin Stats、課程列表、評價分布三個高頻端點
• 將 CACHE_STORE 切換為 redis

Non-Goals:

• 前端 HTTP 層級的 CDN / HTTP Cache-Control header 優化
• Elasticsearch 全文搜尋（課程 LIKE 搜尋的長期方案）
• 資料庫連線池調整（屬於 DevOps 層級）
• API Response Compression（gzip，屬於 nginx 設定）

Decisions

決策 1：Cache driver 改為 Redis 而非 Memcached

選擇：Redis

理由：

• Docker 環境中加一個 redis:alpine service 即可，成本低
• Redis 支援 TTL、Pub/Sub、Queue（未來 Job Queue 可複用同一個 Redis）
• Memcached 無法用於 Laravel Queue，擴展性較差

替代方案：保留 database driver → 拒絕，因為快取本身又增加 DB 負擔，反效果

---

決策 2：ReviewController::publicList 合併查詢策略

目前狀況：3 次獨立 SQL

1. Review::where()->get() — 撈評價列表
2. ReviewVote::where()->pluck() — 撈已投票 ID
3. Review::selectRaw()->groupBy()->pluck() — 統計分布

選擇：合併為 2 次 SQL

• SQL 1：Review::with('votes')->where()->paginate() — 評價列表（含 votes eager load）
• SQL 2：Review::selectRaw()->groupBy()->pluck() — 統計分布（保留，邏輯獨立）
• has_voted 改從 eager loaded votes collection 中判斷，不再發第 3 次 SQL

理由：分布統計邏輯與列表查詢職責不同，維持獨立 SQL 可讀性更高；votes 用 eager load 解決 N+1

替代方案：全部合一次 SQL（subquery）→ 拒絕，可讀性差，維護困難

---

決策 3：快取 TTL 策略

端點	TTL	失效時機
Admin Stats（總數統計）	5 分鐘	手動清除（可接受少許延遲）
課程列表（GET /api/diving-offers）	3 分鐘	Provider 新增/修改/刪除課程時 Cache::forget()
評價分布（per offer）	10 分鐘	Member 新增/修改/刪除評價時 Cache::forget()

理由：Stats 為 Admin 用，接受延遲；課程列表對 SEO 重要，失效時機明確；評價分布計算成本高，TTL 稍長

---

決策 4：分頁預設值

• ReviewController::publicList()：per_page 預設 20，最大 50
• AdminReviewController::index()：per_page 預設 20，最大 100
• 相容性：前端目前不傳 page，Laravel paginate() 預設 page=1，現有行為不破壞

Risks / Trade-offs

• [Risk] Redis 服務故障 → CACHE_STORE=redis 時 Redis 掛掉會拋出 Exception → Mitigation：在 .env.example 補 fallback 說明；生產環境考慮 CACHE_STORE 動態切換
• [Risk] 快取資料與 DB 短暫不一致 → 課程列表快取 3 分鐘內不即時 → Mitigation：寫入操作（新增/修改/刪除課程、新增評價）主動 Cache::forget()，只有統計類允許延遲
• [Risk] Migration 補索引在生產環境加鎖 → MySQL 8 ADD INDEX 為 online DDL，不鎖表 → 低風險

Migration Plan

1. 執行 php artisan migrate（補索引 migration）
2. docker-compose.yml 加入 Redis service
3. .env 設定 CACHE_STORE=redis、REDIS_HOST=redis
4. 部署後重啟 cfdive-app container

Rollback：

• 索引可 DROP INDEX（不影響資料）
• 快取失效直接 CACHE_STORE=database 回退，行為與現在相同

Open Questions

• Redis 是否需要設定 maxmemory-policy（防止記憶體溢出）？建議 allkeys-lru，但需確認 Docker 記憶體限制
• 課程列表的快取 key 是否要包含搜尋參數？若包含，失效邏輯需改為 tag-based invalidation（Cache::tags()）