ID別履歴取得

概要説明

ID別履歴取得機能により、クライアントは特定のアップロード履歴レコードの詳細情報を取得できます。この機能は、ファイル詳細、ステータス、エラー情報、ユーザーコンテキストを含む単一のアップロードに関する完全な情報を提供します。この機能には、ユーザーが自分のグループの履歴のみにアクセスできることを保証するグループベースのアクセス制御が含まれています。

Swaggerリンク

API: アップロード履歴API

ケースドキュメント

ケース1: 特定のアップロード履歴の取得

説明

クライアントがその一意の識別子によって特定のアップロード履歴の詳細情報を要求します。

シーケンス図

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: ID別履歴取得フロー
    
    rect rgb(200, 255, 200)
    Note right of Client: 成功ケースフロー
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}
    
    rect rgb(200, 230, 255)
    Note right of API: 入力検証
    API->>API: IDパラメータを検証
    end
    
    rect rgb(200, 255, 255)
    Note right of API: ビジネスロジック
    API->>Service: getHistoryById(id)
    Service->>Repository: findById(id)
    Repository->>Repository: ログインユーザーのグループIDを取得
    Repository->>Database: グループフィルター付きSELECT WHERE id = {id}
    Database-->>Repository: 履歴レコードを返す
    Repository-->>Service: ReviewUploadHistoryモデルを返す
    Service-->>API: 履歴データを返す
    end
    
    API-->>Client: 200 OK (履歴詳細データ)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: エラー処理
    rect rgb(255, 230, 230)
    alt 検証エラー
        API-->>Client: 422 検証エラー
    else 履歴が見つからない
        Database-->>Repository: レコードなし
        Repository-->>Service: null
        Service-->>API: 履歴が見つからない
        API-->>Client: 404 Not Found
    else アクセス拒否
        Repository-->>Service: アクセス拒否
        Service-->>API: アクセス拒否
        API-->>Client: 403 Forbidden
    else データベースエラー
        Database-->>Repository: データベースエラー
        Repository-->>Service: エラー結果
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: 履歴詳細の要求

説明: クライアントが特定のIDのアップロード履歴詳細を要求
リクエスト: GET /api/v1/general/upload-file/gcs/histories/{id}
パラメータ:
- id: 取得するアップロード履歴の一意の識別子（必須）
バリデーション:
- IDは正の整数である必要があります

ステップ2: 履歴レコードの取得

説明: システムが指定されたIDの履歴レコードを取得
アクション:
- ログインユーザーのグループIDを取得
- グループフィルターとIDでデータベースをクエリ
- ユーザーリレーションデータを含める
- レコードが存在しない場合は404エラーを返す

ステップ3: 履歴詳細を返す

説明: 要求された履歴レコードの詳細をクライアントに返す
レスポンス:
- 成功: 200 OK（ID、ファイル情報、ステータス、ユーザー情報を含む完全な履歴データ）
- エラー: 適切なエラーコードとメッセージ

データベース関連テーブルとフィールド

erDiagram
    review_upload_histories {
        bigint id PK
        bigint user_id FK "usersテーブルへの参照"
        bigint group_id FK "groupsテーブルへの参照"
        string file_name "アップロードされたファイル名"
        string gcs_path "ファイルが保存されているGoogle Cloud Storageのパス"
        tinyInteger status "アップロードステータス: 0=未処理, 1=処理中, 2=成功, 3=失敗"
        string error_reason "アップロード失敗時のエラーメッセージ（null可）"
        timestamp validated_at "ファイルが検証された時刻（null可）"
        timestamp created_at
        timestamp updated_at
    }
    users {
        bigint id PK
        string name "ユーザーのフルネーム"
        string email "ユーザーのメールアドレス"
    }

    review_upload_histories ||--o{ users : 所属

エラー処理

ログ記録
- 履歴取得失敗はアプリケーションログに記録されます

エラー詳細:

ステータスコード	エラーメッセージ	説明
422	検証失敗	IDパラメータが無効な場合
404	履歴が見つかりません	指定されたIDの履歴が存在しない場合
403	アクセス拒否	ユーザーがこの履歴にアクセスする権限がない場合
400	履歴の取得に失敗	データベース操作が失敗した場合

主要機能

グループベースアクセス制御: データセキュリティのためのユーザーのグループによる自動フィルタリング
ユーザーリレーションシップ: 履歴レコードにユーザー情報を含める
エラーハンドリング: 詳細なログ記録による包括的なエラーハンドリング
セキュリティ: ユーザーは自分のグループの履歴のみにアクセス可能

セキュリティ考慮事項

グループ分離: ユーザーは自分のグループのアップロード履歴のみにアクセス可能
入力検証: すべてのIDパラメータが検証されます
アクセス制御: グループベースのフィルタリングにより不正アクセスを防止
エラーログ記録: 失敗した操作は監視のためにログに記録されます
ユーザー認証: グループメンバーシップを持つ認証されたユーザーが必要です

04.get-history-by-id