D15 - 第二階段驗收：盤點需求，為前端整合鋪路

哈囉，大家好！不知不覺，我們的 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 建立使用者介面。
• 持續優化，根據測試和反饋進行改進。
  希望大家能夠從這次驗收中學到一些實用的方法和技巧，應用到自己的專案中。讓我們繼續保持熱情，迎接下半程的挑戰！