User Management System

プロジェクトは 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 包標識檔

• ユーザー管理の CRUD 操作
• CSV ファイルへのデータ保存
• ユーザーデータの検証
• ユーザーの一括インポート
• ユーザーの年齢統計分析

• 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 - 名前の先頭文字ごとにグループ化した平均年齢を計算

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

アプリケーションの起動後、以下のアドレスから Swagger UI ドキュメントにアクセスできます。

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

ユーザーモデル

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

CSV ファイル形式

CSV ファイルには、以下の列が必要です。

• Name：ユーザー名
• Age：ユーザーの年齢

• ユーザー名（Name）：
  • 空欄にできません
  • 必須項目です
• ユーザーの年齢（Age）：
  • 0 以上の整数である必要があります
  • 必須項目です

プロジェクトは Clean Architecture の設計原則に基づいています。

1. ドメイン層：

   • 中核となるビジネスエンティティとルールを定義します
   • ユーザーモデルと検証ロジックを含みます

2. ユースケース層：

   • ビジネスロジックを実装します
   • ユーザー管理操作を処理します

3. インターフェース層：

   • ストレージとデータ読み込みのインターフェースを定義します
   • ビジネスロジックを実装の詳細から切り離します

4. インフラストラクチャ層：

   • 具体的な実装を提供します
   • CSV ファイルの操作ロジックを含みます

5. API 層：

   • HTTP リクエストを処理します
   • RESTful API エンドポイントを提供します

システムは統一されたエラー処理機構を採用しており、すべての例外は 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 ファイルの形式または内容が要件を満たさない場合

• FastAPI：モダンで高速な Web フレームワーク
• Pydantic：データ検証とシリアライズ
• Pandas：CSV データ処理
• Cursor AI：ドキュメント生成とコード分析

このプロジェクトは 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 を使用してイメージサイズを小さくします

• Cursor IDE：AI 支援開発機能を統合
• Cursor AI：ドキュメントの生成とコード分析を支援
• Git：バージョン管理
• Python 3.12+：プログラミング言語環境

プロジェクトでは pytest を使用してテストを実施し、pytest-cov を使用してカバレッジレポートを生成します。

現在のテストカバレッジ

最新のカバレッジレポート（2025-04-10 生成）によると、プロジェクトは優れたテストカバレッジを達成しています。

• 全体のカバレッジ：100%
• テスト済みの文数：202
• 未カバーの文数：0

各模組覆蓋率詳情

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

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. 資料驗證：

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

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