哈囉，大家好！不知不覺，我們的 30 天鐵人挑戰已經過了一半。這段期間，我們一起從零開始，建立了個人財務管理系統的後端，從資料庫設計、模型建立、路由設定到控制器實作，甚至進行了單元測試。
現在，是時候停下腳步，來一場 第二階段的驗收。
在開始前，我想分享一個個人經驗：以前我在開發專案時，總是急於向前衝，結果到最後才發現有許多細節沒處理好，導致後續的整合和維護變得困難重重。這次，我們不要重蹈覆轍，讓我們一起盤點已完成的功能，確保接下來的 Nuxt 前端串接能夠順利進行。
一、為什麼需要進行中期驗收？
在軟體開發中，定期的驗收和回顧是非常重要的。透過驗收，我們可以：
- 確認進度：確保已完成的功能符合最初的需求。
- 發現問題：及早發現並修正潛在的錯誤或遺漏。
- 調整計畫：根據現狀調整後續的開發方向和優先級。
就像爬山一樣，爬到一半時停下來看看地圖，確認一下方向，補充一下能量，再繼續前進。
二、盤點需求與實際達成內容
首先，我們需要回顧一下最初列出的需求，然後檢查我們實際完成了哪些。
1. 需求清單
- 使用者管理：
- 註冊新使用者
- 使用者登入驗證
- 更新使用者資料
- 刪除使用者帳號
- 銀行帳戶管理：
- 新增銀行帳戶
- 編輯銀行帳戶資訊
- 刪除銀行帳戶
- 列出使用者的所有銀行帳戶
- 分類管理：
- 新增收入/支出分類
- 編輯分類名稱和類型
- 刪除分類
- 列出所有分類
- 交易紀錄管理：
- 新增交易紀錄（收入/支出）
- 編輯交易紀錄
- 刪除交易紀錄
- 查詢交易紀錄
- 根據日期範圍查詢交易紀錄
- 報表功能：
- 每月收入/支出統計
- 按分類統計收入/支出
- 生成圖表（未實作，計畫在前端完成）
2. 實際完成的內容
經過前面的開發，我們已經：
- 建立了 使用者、銀行帳戶、分類、交易紀錄 的資料表和模型。
- 實作了上述資源的 CRUD API。
- 完成了基本的 資料驗證 和 錯誤處理。
- 撰寫了部分的 單元測試，確保關鍵功能的正確性。
3. 尚未完成的部分
- 使用者登入驗證：目前尚未實作身份驗證機制（如 JWT 或 Laravel Sanctum）。
- 報表功能的 API：報表的生成尚未在後端提供 API。
- 進階查詢：如根據日期範圍或分類篩選交易紀錄的功能需要加強。
- 測試覆蓋率：單元測試還不夠全面，需要補充更多測試案例。
三、驗收 API 功能
為了確保後續的前端開發能夠順利進行，我們需要逐一測試每個 API，確認其功能和輸出符合預期。
1. 使用 Postman 測試 API
Postman 是一個強大的 API 測試工具，以下是我常用的驗收方法：
- 建立測試環境：在 Postman 中設定環境變數，如 API 伺服器的 URL。
- 撰寫測試腳本：為每個 API 請求建立對應的測試案例。
- 檢查回應格式：確認 API 回應的 JSON 結構是否符合預期。
- 驗證狀態碼：例如，創建成功應回傳 201，刪除成功應回傳 204。
2. 測試各個 API
（1）使用者 API
- GET /api/users：應回傳使用者列表。
- POST /api/users：提供必要的資料，應成功創建新使用者。
- GET /api/users/{id}：應回傳指定使用者的資料。
- PUT /api/users/{id}：更新使用者資料，確認變更是否生效。
- DELETE /api/users/{id}：刪除使用者，確認資料庫中已無此使用者。
（2）銀行帳戶 API
- GET /api/bank-accounts：應回傳銀行帳戶列表。
- POST /api/bank-accounts：創建新帳戶，檢查必填欄位和驗證規則。
- GET /api/bank-accounts/{id}：取得特定帳戶資訊。
- PUT /api/bank-accounts/{id}：更新帳戶資訊，確認變更。
- DELETE /api/bank-accounts/{id}：刪除帳戶，確認是否同時刪除了相關的交易紀錄（若有設定）。
（3）分類 API
- GET /api/categories：應回傳分類列表。
- POST /api/categories：新增分類，測試收入和支出類型。
- GET /api/categories/{id}：取得分類詳情。
- PUT /api/categories/{id}：更新分類名稱或類型。
- DELETE /api/categories/{id}：刪除分類，確認系統處理方式（如是否影響相關交易紀錄）。
（4）交易紀錄 API
- GET /api/transactions：應回傳所有交易紀錄。
- POST /api/transactions：新增交易紀錄，測試不同類型、金額和日期。
- GET /api/transactions/{id}：取得交易詳情。
- PUT /api/transactions/{id}：更新交易資訊。
- DELETE /api/transactions/{id}：刪除交易，確認資料庫更新。
3. 檢查資料驗證與錯誤處理
- 輸入驗證：嘗試傳遞錯誤或缺少的資料，確認系統是否返回適當的錯誤訊息。
- 權限控制：目前尚未實作，但需要考慮未來加入身份驗證後的權限驗證。
- 錯誤回應格式：確保錯誤訊息統一且易於理解，方便前端處理。
4. 確認 API 文件
雖然我們是獨立開發，但良好的 API 文件對於自己和他人都是一種負責任的態度。建議使用工具如 Swagger 或 ApiDoc 生成 API 文件，記錄：
- API 路徑與方法：如 GET /api/transactions。
- 請求參數：包括必要的和可選的參數，類型和說明。
- 回應格式：成功和錯誤的回應範例。
- 錯誤碼：常見的錯誤碼及其意義。
四、為前端整合做好準備
在確認後端 API 功能正常後，我們需要考慮如何讓前端開發更順利。
1. 統一回應格式
- 成功回應：統一使用固定的格式，例如：
{
"status": "success",
"data": { ... }
}
- 錯誤回應：提供一致的錯誤結構，方便前端解析：
{
"status": "error",
"message": "錯誤訊息",
"errors": { ... }
}
2. CORS 設定
為了讓前端（尤其是使用不同網域時）能夠順利訪問 API，需要在後端設定 CORS（跨來源資源共享）。
在 app/Http/Kernel.php 中，確認已經加入了 \Fruitcake\Cors\HandleCors::class。
3. 身份驗證與安全性
雖然我們還沒有實作身份驗證，但在進行前端整合前，需要決定：
- 使用哪種身份驗證方式：如 JWT、Laravel Sanctum 等。
- 保護哪些路由：哪些 API 需要登入後才能訪問。
- 前後端如何傳遞身份驗證資訊：如使用 HTTP Header 傳遞 Token。
五、未來的調整與計畫
經過這次驗收，我們發現還有一些需要改進的地方：
- 完善單元測試：增加測試覆蓋率，特別是關鍵功能和邊界情況。
- 實作身份驗證：保護使用者資料的安全性。
- 優化 API：考慮性能和可擴展性，如加入分頁、快取等。
- 準備前端開發環境：設定 Nuxt 專案，並與後端 API 整合。
六、個人經驗分享
走到這裡，我們已經完成了後端開發的主要部分。回想起來，每次在專案中進行這樣的中期驗收，總能讓我發現許多之前忽略的細節。這不僅有助於提升專案品質，還能節省後續整合時的時間和精力。
我建議大家在開發過程中，多花點時間進行這樣的盤點和檢查。雖然看似耗時，但長遠來看，絕對是划算的投資。
小結
今天，我們一起進行了第二階段的驗收，盤點了需求與實際完成的內容，並測試了各個 API 的功能。這為我們接下來的前端整合鋪平了道路。
在接下來的日子裡，我們將：
- 實作身份驗證機制，確保使用者資料安全。
- 開始前端開發，使用 Nuxt.js 建立使用者介面。
- 持續優化，根據測試和反饋進行改進。
希望大家能夠從這次驗收中學到一些實用的方法和技巧，應用到自己的專案中。讓我們繼續保持熱情，迎接下半程的挑戰！
