インポートエラーの取得

概要説明

インポートエラー取得機能により、クライアントは特定のアップロード履歴の検証エラーを取得できます。この機能は、フィールドヘッダー、問題のある値、行番号、エラーメッセージを含む詳細なエラー情報を提供します。エラーは別のテーブルに保存され、アップロード履歴にリンクされており、失敗したCSVインポートの包括的なエラー追跡とデバッグを可能にします。

Swaggerリンク

API: インポートエラー取得API

ケースドキュメント

ケース1: 履歴のインポートエラーを取得

説明

クライアントが特定のアップロード履歴レコードの詳細な検証エラーを要求します。

シーケンス図

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant ErrorRepository as ReviewUploadErrorRepository
    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/{id}/import-errors
    
    rect rgb(200, 230, 255)
    Note right of API: 入力検証
    API->>API: IDパラメータを検証
    end
    
    rect rgb(200, 255, 255)
    Note right of API: ビジネスロジック
    API->>Service: getImportErrors(id)
    Service->>Repository: findById(id)
    Repository->>Repository: ログインユーザーのグループIDを取得
    Repository->>Database: グループフィルター付きSELECT WHERE id = {id}
    Database-->>Repository: 履歴レコードを返す
    Repository-->>Service: ReviewUploadHistoryモデルを返す
    Service->>ErrorRepository: getErrorsByHistoryId(id)
    ErrorRepository->>Database: SELECT review_upload_errors WHERE history_id = {id}
    Database-->>ErrorRepository: エラーレコードを返す
    ErrorRepository-->>Service: エラーコレクションを返す
    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-->>ErrorRepository: データベースエラー
        ErrorRepository-->>Service: エラー結果
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: インポートエラーの要求

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

ステップ2: 履歴レコードの検証

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

ステップ3: エラーレコードの取得

説明: システムが指定された履歴に関連するすべてのエラーレコードを取得
アクション:
- review_upload_errorsテーブルから履歴IDでエラーをクエリ
- エラーメッセージ、フィールド情報、行番号を含める
- エラーが存在しない場合は空の配列を返す

ステップ4: エラーデータを返す

説明: 要求された履歴のエラーデータをクライアントに返す
レスポンス:
- 成功: 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
    }
    review_upload_errors {
        bigint id PK
        bigint review_upload_history_id FK "review_upload_historiesテーブルへの参照"
        string header "エラーを引き起こしたフィールドヘッダー（null可）"
        string value "問題のあるデータ値（null可）"
        integer error_line "エラーが発生した行番号（null可）"
        json error_messages "フィールドのエラーメッセージ配列"
        timestamp created_at
        timestamp updated_at
    }

    review_upload_histories ||--o{ review_upload_errors : 複数持つ

エラー処理

ログ記録
- インポートエラー取得失敗はアプリケーションログに記録されます

エラー詳細:

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

主要機能

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

セキュリティ考慮事項

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

05.get-import-errors