@@ -0,0 +1,233 @@
---
name: hardener
description: 程式碼實作完成後、呼叫 strict-reviewer 之前，依本專案 CLAUDE.md 慣例為 Laravel 的 Controller／
keywords: [defensive-programming, validation, authorization, exception-handling, logging, concurrency, laravel]
category: code-review
author: RD-Hank
origin: 改寫自 ProjectC 的 hardener skill（原為 C#／
---
# Hardener Skill — 防禦性編程（Laravel 版，比照 CLAUDE.md）
## 目的
在實作完成後，為方法補上下列防禦，**只補缺漏，不重寫已正確的程式碼**：
- 參數驗證（在邊界完成，且失敗發生在任何寫入或鎖定之前）
- 資源存在性與擁有權檢查
- 狀態機驗證（走既有的 Enum 與 `canTransitionTo()` ，不繞過）
- 併發處理（依實際需要序列化的資源設計，不套固定模板）
- 例外邊界（先分清是交易必要步驟還是 best-effort 副作用）
- 日誌（結構化、不含個資與機敏資訊、等級對應風險）
**核心原則（CLAUDE.md） ：
> 例外拋出時機僅在「無法在當層合理處理」時；可預期的業務失敗優先用明確的回傳值或明確的 HTTP 回應，不以例外控制流程。
## 先確認你在哪一層
這個專案目前沒有 `app/Services/` 、`app/Http/Requests/` ，
| 層 | 可預期的失敗（驗證不過、查無資源、無權限、狀態衝突） | 適用節數 |
|---|---|---|
| **Controller ** （ `app/Http/Controllers/API/` ） `{ status: false, message }` 與對應 HTTP 狀態碼（驗證 422、無權限 403、查無 404、狀態衝突沿用既有的 422） | 全部 1–8 |
| **Service ** （新增業務邏輯時抽出的類別） | 以明確的回傳值或窄型的業務例外表達，由 Controller 轉成 HTTP 回應 | 全部 1–
| **Model／ ** （例如 `BookingStatus::canTransitionTo` ） | 只確認既有不變量與慣例是否維持一致 | 僅第 3 節，不套用第 1、6、7 節 |
| **Artisan 指令、Queue job、排程 ** | 不經 HTTP 例外處理，需自行定義失敗行為（`tries` 、`backoff` 、`failed()` 、指令 exit code） | 第 5–
**不套用本 Skill**：
- private helper、單純 getter／ `formatBooking()` 這類純資料轉換
- 純計算邏輯（無 I/O）
- 方法尚未實作完整邏輯（先完成實作）
## 套用前必答（CLAUDE.md 安全強制規則）
方法涉及外部輸入、資料庫讀寫、授權或檔案時，套用前**必須在 commit 說明、PR 描述或工作紀錄實際寫下答案**，不能只是心裡想過：
```text
- 輸入驗證位置：（用了哪個 validate() 規則集或 FormRequest？還是目前完全沒有？）
- 權限檢查位置：（需要什麼角色與擁有權？檢查在哪一層？注意 member／provider 路由群組目前沒有角色 middleware）
- 是否有 N+1：（with()／ ／
- 是否需要悲觀鎖：（是／否，理由）
- 若需要，鎖定哪個資源、為什麼鎖它就足以涵蓋這個操作：（見第 5 節）
```
答不出來代表還沒讀懂現有程式碼，先停下來，不要繼續套用檢查清單。
## 檢查清單
### 1. 參數驗證
| 驗證內容 | 建議位置 |
|---|---|
| 欄位格式、數值範圍、集合不可空、`exists:` 外鍵 | `$request->validate()` 或 FormRequest（沿用同檔案既有寫法） |
| 簡單前置條件（路由參數 `int $id` 、必要的 query 參數） | 方法一開始的 guard clause |
| 跨資源的業務規則（例如人數不得超過剩餘名額） | Service 或 Controller 的前置檢查，並在鎖之後再驗一次（見第 5 節） |
| 單一資源的不變量 | Model／
```php
$data = $request->validate([
'schedule_id' => 'required|integer|exists:course_schedules,id',
'participants' => 'required|integer|min:1',
'notes' => 'nullable|string|max:500',
]);
```
- 驗證失敗必須發生在**任何資料庫寫入、交易、鎖定、外部呼叫之前**。
- 字串要有 `max` ，數值要有上下界，陣列要限制元素數量，避免超大輸入。
- `mass assignment` ： `create()` ／ `update()` 只傳入 `$validated` 或 `$request->only([...])` 的結果，不要傳 `$request->all()` ，且 Model 的 `$fillable` 不得包含 `role` 、`is_active` 、`provider_id` 、`verification_status` 這類不該被外部寫入的欄位。
### 2. 資源存在性與擁有權
單筆：
```php
$booking = Booking::with('schedule')->findOrFail($id); // 查無 → 404
if ($booking->member_id !== $request->user()->id) {
return response()->json(['status' => false, 'message' => '無權操作此預約'], 403);
}
```
- 沿用同一個資源既有的「404 先、403 後」順序與訊息，不要在同一個專案內兩種寫法並存；以對應 spec 為準。
- **擁有權檢查不可省略 ** ：只要資源有 `member_id` 、`provider_id` 等所屬欄位，就必須與呼叫者比對（IDOR）。
- 多筆：先對輸入 id 去重，再比對**實際找到的 id 集合**，不只比數量：
```php
$distinctIds = collect($ids)->unique()->values();
$found = Model::whereIn('id', $distinctIds)->pluck('id');
if ($found->count() !== $distinctIds->count()) {
return response()->json(['status' => false, 'message' => '部分資源不存在'], 422);
}
```
輸入含重複 id（例如 `[1, 1, 2]` ）時，資料庫只會回 2 筆卻要求 3 筆，會誤判成資料缺漏；去重之後再比對才正確。
### 3. 狀態機驗證
```php
if (! $booking->canTransitionTo(BookingStatus::Confirmed)) {
return response()->json(['status' => false, 'message' => '當前狀態無法確認'], 422);
}
```
- 狀態轉換一律經過 Enum 與 `canTransitionTo()` ，不要直接 `update(['status' => ...])` 繞過。
- 順序：先驗擁有權，再驗狀態；兩者都過了才進入寫入。
- 沿用既有的失敗狀態碼與訊息風格；不確定時對照同類端點，不要自創新的狀態碼。
### 4. 逾時與重試：不自創數值
- 外部呼叫（HTTP、S3、SMTP）若需要逾時（`Http::timeout()` 等），**數值與理由必須寫進對應 change 的 `design.md` **，不要在套用本 Skill 時隨手塞一個數字。
- Queue job 的 `$tries` 、`$timeout` 、`backoff()` 同理，沿用現有 Notification 的 `tries = 3` 並在 design 說明是否需要 `backoff` 。
- 不要為了防禦而自行包一層 `retry()` 迴圈。
### 5. 併發處理 — 依實際需要序列化的資源設計，不是套固定模板
**先分清楚兩件事**：
- `lockForUpdate()` 才是真正取得資料庫列鎖（`SELECT ... FOR UPDATE` ）。
- `$model->refresh()` 、`->fresh()` **不取得任何鎖 ** ，只是重新讀取目前的值，不能取代悲觀鎖。
專案既有的兩層驗證（`MemberBookingController::store` ）是可參考的具體案例，不是通用模板：
```php
// Layer 1：交易外快速失敗（便宜、無鎖）
if ($data['participants'] > $schedule->remainingSpots()) { /* 422 */ }
DB::transaction(function () use ($data, $schedule) {
// Layer 2：鎖住「真正需要序列化的資源」後，從資料庫重新讀取並再驗一次
$schedule = CourseSchedule::lockForUpdate()->find($schedule->id);
if ($data['participants'] > $schedule->remainingSpots()) { /* 中斷 */ }
// ... 寫入
});
```
套用到新方法時：
1. 先問「這個方法真正需要序列化的是哪個資源？」，不要預設答案是 `CourseSchedule` 。
2. **依快照做出的決策，與決策對應的寫入，必須在同一個鎖與交易內 ** 。若狀態是在鎖之前讀取、鎖之後才寫入，中間的時間差本身就是一個競態視窗（例如兩個並發請求都讀到 `confirmed` ，都各自扣減一次名額）。需要的話在鎖之後重新取得該列再判斷。
3. 計數器增減使用 `increment()` ／ `decrement()` 並在鎖內完成；之後要用最新值判斷（例如是否額滿）時，先 `refresh()` ，這是「重讀」，不提供並發保護。
4. 重複建立防護依靠資料庫唯一索引或鎖內的存在性檢查，不要只靠交易外的 `exists()` 判斷。
5. 沒有既有鎖定機制可比照、也想不出該鎖什麼時，**不要自己發明重試迴圈**。先確認這個方法是否真的需要處理併發（多數查詢方法不需要），需要就把設計決策寫進 `design.md` 。
6. **測試限制 ** ： `phpunit.xml` 強制使用 SQLite `:memory:` ， `lockForUpdate()` 在 SQLite 上沒有實質效果，單程序測試也無法重現真正的併發。因此併發行為的保證不能宣稱「已被自動化測試驗證」，必須另外在 MySQL 或容器內人工驗證，並在 PR 說明註明。
### 6. 例外邊界：先判斷是交易必要步驟還是 best-effort 副作用
**套用前先回答**：這段程式碼失敗時，是否應該讓整個請求失敗（交易必要步驟）？還是這個副作用允許失敗而不影響主流程（best-effort，且這個決策必須**已經寫在對應 change 的 spec 或 design**，不是套用本 Skill 時自己決定）？
**情境 A：交易必要步驟**（資料庫寫入、名額與狀態變更、授權變更、付款類操作）：
- 不要 `catch (Throwable)` 後吞掉。讓例外往外傳播，由 Laravel 例外處理器處理（本專案已透過 `Sentry\Laravel\Integration::handles` 回報）。
- 在 `DB::transaction()` 閉包內拋出例外會自動 rollback。
- 若需要在閉包內以例外中斷並轉成 422，**使用專用、窄型的業務例外**，且 Controller 只 catch 該型別。**不要 `catch (\RuntimeException $e)` 後把 `$e->getMessage()` 直接回給使用者**： `QueryException` ／ `PDOException` 也是 `RuntimeException` 的子類別，會把資料庫錯誤（含 SQL 與結構資訊）當成 422 回傳，也不會被 Sentry 收到。
**情境 B：
```php
try {
$provider->notify(new BookingCreatedNotification($booking));
} catch (\Throwable $e) {
report($e); // 讓 Sentry 收到；主流程已成功，不重新拋出
}
```
- 只能用在**交易 commit 之後**，且該副作用失敗不應讓已成功的主流程回報錯誤。
- 通知類別已實作 `ShouldQueue` 時，`notify()` 只是入列，這個 catch 防的是「入列失敗」（例如 Redis 不可用）。
- 記錄請用 `report($e)` ，或 `Log::error()` 搭配 context；單純 `Log::error('...' . $e->getMessage())` 不會送 Sentry。
**把情境 A 的作法套到情境 B 是錯的**（通知失敗讓已成功的預約回 500），**反過來更危險**：把資料庫寫入或名額扣減當成 best-effort 吞掉，會出現「回報成功、資料沒完成」。不確定屬於哪一種時，去讀對應 change 的 spec 與 design，不要自己猜。
**不要為每種失敗建立一個例外類別**。能用明確回應表達的失敗（驗證、查無、無權限、狀態衝突）就用回應；只有交易閉包內必須中斷流程時才需要業務例外，且整個專案用同一個窄型例外，不是一個失敗一個類別。
**非 HTTP 路徑**：
- Queue job：設定 `$tries` 、`backoff()` ，必要時實作 `failed()` ；重試用完會進 `failed_jobs` ，要確認有人監看。
- 指令與排程（例如 `app:expire-pending-bookings` ）：自行處理失敗並回傳非 0 的 exit code，不要假設有全域處理器兜底。
### 7. 日誌：結構化、不含個資、等級對應風險
```php
Log::info('預約已建立', ['booking_id' => $booking->id, 'schedule_id' => $schedule->id]);
Log::warning('預約確認被拒絕', ['booking_id' => $booking->id, 'reason' => 'insufficient_spots']);
```
- 用 context 陣列傳遞欄位，不要用字串插值把值拼進訊息，才能在 log 系統個別查詢。
- **不記錄**密碼、token、API key、Email、電話、地址等個資；必要時遮蔽或只記錄 id。
- 預設只記錄失敗的**類型或代碼**，不記錄使用者輸入原文或完整的 `$e->getMessage()` （可能含個資與 SQL）。
- 不要把例外訊息、堆疊追蹤或 SQL 回傳給 API 使用者。
- 等級對應風險，不要每個分支用同一等級：
| 情境 | 建議等級 |
|---|---|
| 預期內的輸入驗證失敗 | 通常不記錄或 `debug` （外部輸入錯誤是正常流量） |
| 查無資源 | 視情境；高頻查詢的 404 不需要記錄 |
| 權限拒絕、狀態衝突 | `info` 或 `warning` ，依業務風險決定 |
| 非預期技術例外 | `error` （並確認有送到 Sentry）
### 8. 測試要求
先列出這次實際補強的防禦分支；每個分支至少要有一項 Feature 或 Unit 測試覆蓋，缺哪個就明確標注「未覆蓋，原因：…」，不要預設全部都測過：
- 驗證失敗 → 422，**且資料庫沒有任何寫入**（`assertDatabaseCount` 或 `assertDatabaseMissing` ），證明失敗發生在寫入之前
- 資源不存在 → 404
- 擁有權不符、角色不符 → 403；涉及權限時要有 member／ `tests/Feature/AdminEndpointAuthTest.php` ）
- 狀態不合法 → 422，且狀態與名額沒有被改動
- 多筆存在性檢查的**重複 id** 邊界案例
- 併發行為 → 說明測試以 SQLite 執行、無法驗證行鎖；若寫了迴圈式的「模擬併發」測試，不得據此宣稱併發安全
- best-effort 副作用失敗 → 以 `Notification::fake()` 或讓 `notify()` 拋出例外，斷言**主流程仍成功**且已回報（例如 `report` ）
- 交易必要步驟失敗 → 斷言整筆 rollback，沒有留下半完成的資料
- 日誌 → 斷言沒有洩漏個資或機敏資訊（可用 `Log::spy()` ）
## 何時跳過
適用範圍已列於「先確認你在哪一層」。額外的跳過條件：
- 方法已有防禦：檢查清單全部通過，且分層正確
- 方法尚未實作完整邏輯
## 驗證步驟
套用本 Skill 後執行：
```bash
php artisan test
./vendor/bin/pint --test <本次變更的 PHP 檔案>
```
若套用本 Skill 導致任何程式碼變更，完成後必須再呼叫 `strict-reviewer` 。若只是檢查過一遍、確認既有程式碼已符合清單、沒有任何修改，不需要重複呼叫。
涉及併發的變更，驗證時另外註明：測試未在 MySQL 驗證行鎖，需人工確認。