使用者管理系統

這是一個基於 FastAPI 和 Clean Architecture 設計的使用者管理系統。系統採用 CSV 檔案作為資料存儲，實現了基本的使用者管理功能。

📝 本文檔由 Cursor AI 協助生成，基於專案的實際架構和程式碼進行分析後產生。

專案架構

<details open>

專案採用清晰架構（Clean Architecture）設計，目錄結構如下：

app/
├── api/            # API 層，處理 HTTP 請求
├── core/           # 核心配置和共用元件
├── domain/         # 領域模型和業務規則
├── infrastructure/ # 基礎設施實作（如 CSV 存儲）
├── interfaces/     # 介面定義
└── use_cases/      # 使用案例實作
tests/              # 測試目錄
├── conftest.py            # Pytest 共用測試夾具
├── test_csv_parser.py     # CSV 解析器測試
├── test_main.py          # 主應用程式測試
├── test_user_repository.py# Repository 層測試
├── test_user_router.py   # API 層測試
├── test_user_use_case.py # Use Case 層測試
└── __init__.py           # Python 包標識檔

</details>

功能特點

<details open>

• 使用者管理 CRUD 操作
• CSV 檔案資料存儲
• 使用者資料驗證
• 批量使用者導入
• 使用者年齡統計分析

</details>

API 端點

<details open>

• POST /create_user - 創建新使用者
• DELETE /delete_user - 刪除使用者
• GET /get_added_user - 獲取已添加的使用者列表
• POST /add_multiple_users_from_csv - 從 CSV 檔案批量導入使用者
• GET /calc_average_age_of_user_grouped_by_first_char_of_name - 計算按名字首字母分組的平均年齡

</details>

安裝與設置

<details open>

1. 建立虛擬環境：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows

2. 安裝依賴：

pip install -r requirements.txt

3. 運行應用：

uvicorn app.main:app --reload

</details>

API 文檔

<details open>

啟動應用後，可以通過以下地址訪問 Swagger UI 文檔：

• http://localhost:8000/docs
• http://localhost:8000/redoc

</details>

資料格式

<details open>

使用者模型

{
    "Name": "string",  // 使用者名稱（必填）
    "Age": int        // 使用者年齡（必填，非負數）
}

CSV 檔案格式

CSV 檔案必須包含以下欄位：

• Name：使用者名稱
• Age：使用者年齡

</details>

資料驗證規則

<details open>

• 使用者名稱（Name）：
  • 不能為空
  • 必須提供
• 使用者年齡（Age）：
  • 必須為非負整數
  • 必須提供

</details>

開發架構

<details open>

專案採用清晰架構（Clean Architecture）設計原則：

1. Domain Layer：

   • 定義核心業務實體和規則
   • 包含使用者模型和驗證邏輯

2. Use Cases Layer：

   • 實作業務邏輯
   • 處理使用者管理操作

3. Interface Layer：

   • 定義存儲和資料載入介面
   • 確保業務邏輯與實作細節解耦

4. Infrastructure Layer：

   • 提供具體實作
   • 包含 CSV 檔案操作邏輯

5. API Layer：

   • 處理 HTTP 請求
   • 提供 RESTful API 端點

</details>

錯誤處理

<details open>

系統採用統一的錯誤處理機制，所有異常都繼承自 AppBaseException。錯誤響應採用標準化的 JSON 格式：

{
    "detail": "ErrorType: 錯誤訊息",
    "status_code": 422,
    "exception_type": "ErrorType"
}

資料驗證異常 (HTTP 422)

1. Pydantic 驗證錯誤：

   • 狀態碼：422
   • 情境：當請求資料不符合模型定義時
   • 範例：

     {
       "detail": [
         {
           "type": "int_parsing",
           "loc": ["body", "Age"],
           "msg": "Input should be a valid integer",
           "input": "invalid"
         }
       ]
     }
     

2. 自定義驗證錯誤：

   • EmptyUserNameError

     • 狀態碼：422
     • 訊息："User name cannot be empty."
     • 情境：當使用者名稱為空字串時

   • NegativeUserAgeError

     • 狀態碼：422
     • 訊息："User age cannot be negative."
     • 情境：當使用者年齡為負數時

核心異常

• AppBaseException
  • 狀態碼：500
  • 基礎異常類別
  • 用於處理未分類的系統錯誤

業務邏輯異常 (HTTP 404)

• UserNotFoundError
  • 狀態碼：404
  • 訊息："User not found."
  • 情境：當要操作的使用者不存在時

資料處理異常 (HTTP 400)

• DataframeKeyException

  • 狀態碼：400
  • 訊息：動態生成（例如："Field {field} not found"）
  • 情境：當在 DataFrame 操作時找不到指定的欄位

• GroupbyKeyException

  • 狀態碼：400
  • 訊息：動態生成（例如："Field {field} not found in GroupBy"）
  • 情境：當在分組操作時找不到指定的欄位

• CSVParserException

  • 狀態碼：400
  • 訊息：動態生成（例如："Missing required columns"）
  • 情境：當 CSV 檔案格式或內容不符合要求時

</details>

技術堆疊

<details open>

• FastAPI：現代、快速的 Web 框架
• Pydantic：資料驗證和序列化
• Pandas：CSV 資料處理
• Cursor AI：文檔生成和程式碼分析

</details>

Docker 部署

<details open>

本專案提供 Docker 支援，可以輕鬆地在容器環境中運行應用程式。

前置需求

• 安裝 Docker

Docker 映像檔建立

docker build -t user-management .

運行容器

docker run -p 8000:8000 user-management

應用程式將在 http://localhost:8000 上運行，您可以通過以下地址訪問：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc

Docker 配置說明

專案使用以下 Docker 配置：

1. 基礎映像檔：

   • 使用 python:3.12-slim 作為基礎映像檔
   • 選擇 slim 版本以減少映像檔大小

2. 檔案排除： 使用 .dockerignore 排除不必要的檔案：

   • Python 快取檔案（__pycache__/, *.pyc）
   • 環境相關（venv/, .env）
   • 測試相關（.pytest_cache/, .coverage, htmlcov/）
   • 版本控制（.git/, .gitignore）
   • 文檔（README.md）

3. 安全性考慮：

   • 使用官方 Python 映像檔
   • 避免安裝不必要的套件
   • 使用 --no-cache-dir 減少映像檔大小

</details>

開發工具

<details open>

• Cursor IDE：整合 AI 輔助開發功能
• Cursor AI：協助生成文檔和程式碼分析
• Git：版本控制
• Python 3.12+：程式語言環境

</details>

測試

<details open>

專案使用 pytest 進行測試，並使用 pytest-cov 生成覆蓋率報告。

當前測試覆蓋率狀況

根據最新的覆蓋率報告（生成於 2025-04-10），專案達到了優秀的測試覆蓋率：

• 總體覆蓋率：100%
• 已測試語句數：202
• 未覆蓋語句數：0

各模組覆蓋率詳情

模組	語句數	覆蓋率
api/v1/user_router.py	33	100%
core/exceptions.py	6	100%
core/settings.py	6	100%
domain/user/exceptions.py	9	100%
domain/user/fields.py	5	100%
domain/user/models/new_user.py	2	100%
domain/user/models/user.py	15	100%
infrastructure/repositories/exceptions.py	11	100%
infrastructure/repositories/user_repository_csv.py	40	100%
infrastructure/services/csv_user_parser.py	19	100%
infrastructure/services/exceptions.py	6	100%
interfaces/user_data_loader.py	4	100%
interfaces/user_repository.py	6	100%
main.py	9	100%
use_cases/user/exceptions.py	5	100%
use_cases/user/user_use_case.py	26	100%

這個完美的測試覆蓋率表明：

1. 所有的程式碼路徑都經過測試
2. 沒有未測試的功能點
3. 測試案例完整且全面

執行測試

# 執行所有測試
pytest

# 執行測試並生成覆蓋率報告
pytest --cov=app --cov-report=html tests/

# 執行特定測試檔案
pytest tests/test_user_repository.py -v

# 執行並顯示詳細測試資訊
pytest -v

測試架構

1. 基礎設施層測試：

   • test_csv_parser.py：測試 CSV 檔案解析邏輯
   • test_user_repository.py：測試數據存取邏輯

2. API 層測試：

   • test_user_router.py：測試 API 端點
   • test_main.py：測試應用程式配置

3. Use Case 層測試：

   • test_user_use_case.py：測試業務邏輯

測試最佳實踐

1. 分層測試：

   • 每個架構層都有對應的測試
   • 確保各層級的獨立性和完整性

2. 測試隔離：

   • 使用 fixtures 確保測試獨立性
   • Mock 外部依賴避免副作用

3. 錯誤處理測試：

   • 驗證各種錯誤情況
   • 確保錯誤回應符合規範

4. 資料驗證：

   • 測試資料格式驗證
   • 確保資料完整性和正確性

</details>

致謝

<details open>

特別感謝 Cursor AI 協助生成本文檔，透過對專案結構和程式碼的智能分析，提供了清晰且結構化的文檔內容。

</details>