Download Error CSV

Overview Description

The Download Error CSV feature allows clients to download a CSV file containing detailed error information for a specific upload history. This feature generates a downloadable CSV file with validation errors, including field headers, problematic values, line numbers, and error messages. The CSV file is generated from error data stored in Google Cloud Storage and provides a comprehensive error report for data correction.

Swagger Link

API: Upload Histories API

Case Documentation

Case 1: Download Error CSV File

Description

Client requests a downloadable CSV file containing validation errors for a specific upload history.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadHistoryRepository
    participant ExportService as ExportService
    participant GCS as Google Cloud Storage
    
    Note over Client,GCS: Download Error CSV Flow
    
    rect rgb(200, 255, 200)
    Note right of Client: Happy Case Flow
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}/download-errors
    
    rect rgb(200, 230, 255)
    Note right of API: Input Validation
    API->>API: Validate history ID parameter
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Business Logic
    API->>Repository: findById(historyId)
    Repository->>Repository: Apply group filter
    Repository->>API: Return ReviewUploadHistory model
    API->>API: Check if error_reason exists
    end
    
    rect rgb(255, 255, 200)
    Note right of API: CSV Generation
    API->>ExportService: handle(reviewUploadHistory)
    ExportService->>ExportService: Parse error_reason JSON
    ExportService->>GCS: Get error file content
    GCS-->>ExportService: Return CSV content
    ExportService->>ExportService: Set response headers
    ExportService-->>API: Return CSV response
    end
    
    API-->>Client: 200 OK (CSV file download)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Error Handling
    rect rgb(255, 230, 230)
    alt History Not Found
        Repository-->>API: Null result
        API-->>Client: 404 Not Found
    else No Error File
        API->>API: Check error_reason field
        API-->>Client: 400 Bad Request (empty errors)
    else GCS Error
        GCS-->>ExportService: Error response
        ExportService-->>API: Error result
        API-->>Client: 500 Internal Server Error
    end
    end
    end

Steps

Step 1: Request Error CSV Download

Description: Client requests CSV file with validation errors
Request: GET /api/v1/general/upload-file/gcs/histories/{id}/download-errors
Parameters:
- id: The unique identifier of the upload history record (required)
Validation:
- History ID must be a valid integer
- History ID must be greater than 0

Step 2: Retrieve History and Validate

Description: System retrieves upload history and validates error data
Action:
- Query database for history record by ID with group filter
- Verify history record exists
- Check if error_reason field contains error data
- Validate user has access to the requested history

Step 3: Generate and Return CSV

Description: Generate CSV file from error data and return to client
Action:
- Parse error_reason JSON to extract error file path
- Retrieve CSV content from Google Cloud Storage
- Set appropriate response headers for CSV download
- Return CSV file as downloadable response

Database Related Tables & Fields

erDiagram
    review_upload_histories {
        bigint id PK
        bigint user_id FK "Reference to users table"
        bigint group_id FK "Reference to groups table"
        string file_name "Name of the uploaded file"
        string gcs_path "Google Cloud Storage path where file is stored"
        tinyInteger status "Upload status: 0=Notyet, 1=processing, 2=success, 3=fail"
        string error_reason "Error message if upload failed (nullable)"
        timestamp validated_at "Timestamp when file was validated (nullable)"
        timestamp created_at
        timestamp updated_at
    }
    users {
        bigint id PK
        string name "User's full name"
        string email "User's email address"
    }
    groups {
        bigint id PK
        string name "Group name"
    }

    review_upload_histories ||--o{ users : belongs_to
    review_upload_histories ||--o{ groups : belongs_to

Error Handling

Log
- CSV download failures logged to application log

Error Detail:

Status Code	Error Message	Description
404	History not found	When specified ID history record doesn't exist
400	Empty errors	When history has no error data to download
500	Failed to download CSV	When GCS operation fails

Key Features

CSV File Generation: Generate downloadable CSV files with error data
Error Data Retrieval: Retrieve error files from Google Cloud Storage
File Download: Proper HTTP headers for CSV file download
Error Validation: Check for existence of error data before processing
Group-Based Access: Automatic filtering by user's group for security
Error Logging: Comprehensive error handling with detailed logging

Security Considerations

Group Isolation: Users can only download errors from their own group's histories
Input Validation: History ID is validated before processing
Error Logging: Failed operations are logged for monitoring
User Authentication: Requires authenticated user with group membership
File Access Control: Error files are stored in secure GCS location
Data Sanitization: CSV content is properly formatted and safe for download

06.download-error-csv