エラーCSVダウンロード

概要説明

エラーCSVダウンロード機能により、クライアントは特定のアップロード履歴の詳細なエラー情報を含むCSVファイルをダウンロードできます。この機能は、検証エラー、フィールドヘッダー、問題のある値、行番号、エラーメッセージを含むダウンロード可能なCSVファイルを生成します。CSVファイルはGoogle Cloud Storageに保存されているエラーデータから生成され、データ修正のための包括的なエラー報告を提供します。

Swaggerリンク

API: エラーCSVダウンロードAPI

ケースドキュメント

ケース1: エラーCSVファイルのダウンロード

説明

クライアントが特定のアップロード履歴の検証エラーを含むダウンロード可能なCSVファイルを要求します。

シーケンス図

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant ErrorRepository as ReviewUploadErrorRepository
    participant ExportService as ExportService
    participant Database as Database
    
    Note over Client,Database: エラーCSVダウンロードフロー
    
    rect rgb(200, 255, 200)
    Note right of Client: 成功ケースフロー
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}/download-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: downloadErrorCsv(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->>ExportService: generateErrorCsv(errors)
    ExportService->>ExportService: CSVファイルを生成
    ExportService-->>Service: CSVファイルデータを返す
    Service-->>API: CSVファイルデータを返す
    end
    
    API-->>Client: 200 OK (CSVファイルダウンロード)
    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 CSV生成エラー
        ExportService-->>Service: CSV生成エラー
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    else データベースエラー
        Database-->>ErrorRepository: データベースエラー
        ErrorRepository-->>Service: エラー結果
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: エラーCSVダウンロードの要求

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

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

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

ステップ3: エラーデータの取得

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

ステップ4: CSVファイルの生成

説明: システムがエラーデータからCSVファイルを生成
アクション:
- エラーデータをCSV形式に変換
- ヘッダー、値、行番号、エラーメッセージを含む列を追加
- 適切なファイル名とMIMEタイプを設定

ステップ5: CSVファイルを返す

説明: 生成されたCSVファイルをクライアントにダウンロードとして返す
レスポンス:
- 成功: 200 OK（CSVファイルのダウンロードレスポンス）
- エラー: 適切なエラーコードとメッセージ

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

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 : 複数持つ

エラー処理

ログ記録
- エラーCSVダウンロード失敗はアプリケーションログに記録されます

エラー詳細:

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

主要機能

グループベースアクセス制御: データセキュリティのためのユーザーのグループによる自動フィルタリング
CSVファイル生成: エラーデータから構造化されたCSVファイルの自動生成
詳細エラー情報: フィールドレベル、行レベル、値レベルの包括的なエラー追跡
ダウンロード機能: 適切なヘッダーとMIMEタイプでのファイルダウンロード
エラーハンドリング: 詳細なログ記録による包括的なエラーハンドリング

セキュリティ考慮事項

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

06.download-error-csv