アップロード履歴

概要説明

アップロード履歴機能により、クライアントはファイルアップロード履歴レコードのページネーション付きリストにアクセスできます。この機能により、ユーザーはフィルタリングとページネーション機能を使用してアップロード履歴を表示できます。履歴には、アップロードされたファイル、そのステータス、関連するエラーメッセージに関する情報が含まれます。これは、アップロードの進行状況の追跡、過去のアップロードの確認、失敗したアップロードのデバッグに役立ちます。

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: アップロード履歴取得フロー
    
    rect rgb(200, 255, 200)
    Note right of Client: 成功ケースフロー
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/list
    
    rect rgb(200, 230, 255)
    Note right of API: 入力検証
    API->>API: リクエストパラメータを検証
    end
    
    rect rgb(200, 255, 255)
    Note right of API: ビジネスロジック
    API->>Service: getHistories(request->all())
    Service->>Repository: serverPaginationFilteringFor(params)
    Repository->>Repository: ログインユーザーのグループIDを取得
    Repository->>Database: グループフィルターとページネーション付きSELECT
    Database-->>Repository: ページネーション結果を返す
    Repository-->>Service: LengthAwarePaginatorを返す
    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: エラー結果
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    else サービスエラー
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: アップロード履歴の要求

説明: クライアントがアップロード履歴のページネーション付きリストを要求
リクエスト: GET /api/v1/general/upload-file/gcs/histories/list
パラメータ:
- per_page: ページあたりのレコード数（オプション、デフォルト: 10）
- page: ページネーション用のページ番号（オプション、デフォルト: 1）
バリデーション:
- Per pageは正の整数である必要があります
- Pageは正の整数である必要があります

ステップ2: ページネーション付き履歴の取得

説明: システムがユーザーのグループのアップロード履歴をページネーション付きで取得
アクション:
- ログインユーザーのグループIDを取得
- グループフィルターとページネーションでデータベースをクエリ
- ユーザーリレーションデータを含める
- 作成日でソート（最新が最初）

ステップ3: ページネーション結果を返す

説明: ページネーション付き履歴データをクライアントに返す
レスポンス:
- 成功: 200 OK（メタデータを含むページネーション付き履歴データ）
- エラー: 適切なエラーコードとメッセージ

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

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	検証失敗	ページネーションパラメータが無効な場合
400	履歴の取得に失敗	データベース操作が失敗した場合

主要機能

グループベースフィルタリング: データセキュリティのためのユーザーのグループによる自動フィルタリング
ページネーション: 設定可能なページサイズによる大規模データセットのサポート
ユーザーリレーションシップ: 履歴レコードにユーザー情報を含める
ソート: 作成日によるデフォルトソート（最新が最初）
エラーハンドリング: 詳細なログ記録による包括的なエラーハンドリング

セキュリティ考慮事項

グループ分離: ユーザーは自分のグループのアップロード履歴のみにアクセス可能
入力検証: すべてのページネーションパラメータが検証されます
エラーログ記録: 失敗した操作は監視のためにログに記録されます
ユーザー認証: グループメンバーシップを持つ認証されたユーザーが必要です

03.upload-histories