User Management System

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

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

專案架構

專案採用清晰架構（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>

功能特點

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

</details>

API 端點

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>

安裝與設置

建立虛擬環境：

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

安裝依賴：

pip install -r requirements.txt

運行應用：

uvicorn app.main:app --reload

</details>

API 文檔

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

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

</details>

資料格式

使用者模型

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

CSV 檔案格式

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

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

</details>

資料驗證規則

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

</details>

開發架構

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

Domain Layer：
- 定義核心業務實體和規則
- 包含使用者模型和驗證邏輯
Use Cases Layer：
- 實作業務邏輯
- 處理使用者管理操作
Interface Layer：
- 定義存儲和資料載入介面
- 確保業務邏輯與實作細節解耦
Infrastructure Layer：
- 提供具體實作
- 包含 CSV 檔案操作邏輯
API Layer：
- 處理 HTTP 請求
- 提供 RESTful API 端點

</details>

錯誤處理

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

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

資料驗證異常 (HTTP 422)

Pydantic 驗證錯誤：

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

範例：

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

自定義驗證錯誤：
- 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>

技術堆疊

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

</details>

Docker 部署

本專案提供 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 配置：

基礎映像檔：
- 使用 python:3.12-slim 作為基礎映像檔
- 選擇 slim 版本以減少映像檔大小
檔案排除：使用 .dockerignore 排除不必要的檔案：
- Python 快取檔案（__pycache__/, *.pyc）
- 環境相關（venv/, .env）
- 測試相關（.pytest_cache/, .coverage, htmlcov/）
- 版本控制（.git/, .gitignore）
- 文檔（README.md）
安全性考慮：
- 使用官方 Python 映像檔
- 避免安裝不必要的套件
- 使用 --no-cache-dir 減少映像檔大小

</details>

開發工具

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

</details>

測試

專案使用 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% |

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

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

執行測試

# 執行所有測試
pytest

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

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

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

測試架構

基礎設施層測試：
- test_csv_parser.py：測試 CSV 檔案解析邏輯
- test_user_repository.py：測試數據存取邏輯
API 層測試：
- test_user_router.py：測試 API 端點
- test_main.py：測試應用程式配置
Use Case 層測試：
- test_user_use_case.py：測試業務邏輯

測試最佳實踐

分層測試：
- 每個架構層都有對應的測試
- 確保各層級的獨立性和完整性
測試隔離：
- 使用 fixtures 確保測試獨立性
- Mock 外部依賴避免副作用
錯誤處理測試：
- 驗證各種錯誤情況
- 確保錯誤回應符合規範
資料驗證：
- 測試資料格式驗證
- 確保資料完整性和正確性

</details>

致謝

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

</details>