Upload Histories

Overview Description

The Upload Histories feature provides clients with access to a paginated list of file upload history records. This feature allows users to view their upload history with filtering and pagination capabilities. The history includes information about uploaded files, their status, and any associated error messages. This is useful for tracking upload progress, reviewing past uploads, and debugging failed uploads.

Swagger Link

API: Upload Histories API

Case Documentation

Case 1: Get Upload Histories with Pagination

Description

Client requests a paginated list of upload history records for the current user's group.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: Get Upload Histories Flow
    
    rect rgb(200, 255, 200)
    Note right of Client: Happy Case Flow
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/list
    
    rect rgb(200, 230, 255)
    Note right of API: Input Validation
    API->>API: Validate request parameters
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Business Logic
    API->>Service: getHistories(request->all())
    Service->>Repository: serverPaginationFilteringFor(params)
    Repository->>Repository: Get logged in user's group ID
    Repository->>Database: SELECT with pagination and group filter
    Database-->>Repository: Return paginated results
    Repository-->>Service: Return LengthAwarePaginator
    Service-->>API: Return history data
    end
    
    API-->>Client: 200 OK (paginated history data)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Error Handling
    rect rgb(255, 230, 230)
    alt Validation Error
        API-->>Client: 422 Validation Error
    else Database Error
        Database-->>Repository: Database error
        Repository-->>Service: Error result
        Service-->>API: Error result
        API-->>Client: 400 Bad Request
    else Service Error
        Service-->>API: Error result
        API-->>Client: 400 Bad Request
    end
    end
    end

Steps

Step 1: Request Upload Histories

• Description: Client requests paginated list of upload histories
• Request: GET /api/v1/general/upload-file/gcs/histories/list
• Parameters:
  • per_page: Number of records per page (optional, default: 10)
  • page: Page number for pagination (optional, default: 1)
• Validation:
  • Per page must be a positive integer
  • Page must be a positive integer

Step 2: Retrieve Paginated History

• Description: System retrieves upload history for user's group with pagination
• Action:
  • Get logged-in user's group ID
  • Query database with group filter and pagination
  • Include user relationship data
  • Sort by creation date (newest first)

Step 3: Return Paginated Results

• Description: Return paginated history data to client
• Response:
  • Success: 200 OK with paginated history data including metadata
  • Error: Appropriate error code with message

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"
    }

    review_upload_histories ||--o{ users : belongs_to

Error Handling

• Log
  • History retrieval failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  422	Validation failed	When pagination parameters are invalid
  400	Failed to retrieve histories	When database operation fails

Key Features

• Group-Based Filtering: Automatic filtering by user's group for data security
• Pagination: Support for large datasets with configurable page size
• User Relationships: Include user information in history records
• Sorting: Default sorting by creation date (newest first)
• Error Handling: Comprehensive error handling with detailed logging

Security Considerations

• Group Isolation: Users can only access upload histories from their own group
• Input Validation: All pagination parameters are validated
• Error Logging: Failed operations are logged for monitoring
• User Authentication: Requires authenticated user with group membership