02.store-upload-history

Store Upload History

Overview Description

The Store Upload History feature allows clients to save metadata about file uploads to Google Cloud Storage. This feature stores information about uploaded files including file name, GCS path, upload status, and any error reasons. This history is used for tracking upload progress, debugging failed uploads, and providing audit trails for file management operations.

Swagger Link

API: Store Upload History API

Case Documentation

Case 1: Store Successful Upload History

Description

Client stores metadata about a successfully uploaded file to track the upload history.

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: Store Upload History Flow
    
    rect rgb(200, 255, 200)
    Note right of Client: Happy Case Flow
    
    Client->>API: POST /api/v1/general/upload-file/gcs/upload-history
    
    rect rgb(200, 230, 255)
    Note right of API: Input Validation
    API->>API: Validate request data using StoreUploadHistoryRequest
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Business Logic
    API->>Service: createHistory(request->all())
    Service->>Service: Get logged in user and group information
    Service->>Repository: create(historyData)
    Repository->>Database: INSERT INTO review_upload_histories
    Database-->>Repository: Return created record
    Repository-->>Service: Return ReviewUploadHistory model
    Service-->>API: Return history data
    end
    
    API-->>Client: 200 OK (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: Submit Upload History

  • Description: Client submits upload history after successful file upload
  • Request: POST /api/v1/general/upload-file/gcs/upload-history
  • Parameters:
    • file_name: The name of the uploaded file (required)
    • gcs_path: The Google Cloud Storage path where the file is stored (required)
    • error_reason: Error message if upload failed (optional)
  • Validation:
    • File name must be a string and not exceed 255 characters
    • GCS path must be a string
    • Error reason must be a string and not exceed 255 characters if provided

Step 2: Process History Storage

  • Description: System stores upload history with user and group context
  • Action:
    • Get current logged-in user information
    • Get user's group ID from group membership
    • Create history record with user_id, group_id, and provided data
    • Set default status to 'Notyet' (0)

Step 3: Return History Data

  • Description: Return the created history record to client
  • Response:
    • Success: 200 OK with complete history data including ID, timestamps, and relationships
    • 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"
    }
    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
    • History storage failures logged to application log
  • Error Detail:
    Status Code Error Message Description
    422 Validation failed When request parameters are invalid
    400 Failed to store history When database operation fails

Case 2: Store Failed Upload History

Description

Client stores metadata about a failed file upload with error information for debugging.

Steps

Step 1: Submit Failed Upload History

  • Description: Client submits upload history with error information
  • Request: POST /api/v1/general/upload-file/gcs/upload-history
  • Parameters:
    • file_name: The name of the file that failed to upload
    • gcs_path: The intended GCS path
    • error_reason: Detailed error message explaining the failure

Step 2: Process Failed History Storage

  • Description: System stores failed upload history with error context
  • Action:
    • Store history record with error_reason field populated
    • Maintain same user and group context as successful uploads
    • Enable error tracking and debugging capabilities

Step 3: Return Failed History Data

  • Description: Return the failed history record to client
  • Response:
    • Success: 200 OK with history data including error information
    • Error: Appropriate error code with message

Error Handling

  • Log
    • Failed upload history storage logged for debugging
  • Error Detail:
    Status Code Error Message Description
    422 Validation failed When request parameters are invalid
    400 Failed to store history When database operation fails

Key Features

  • User Context: Automatic association with logged-in user and their group
  • Error Tracking: Support for storing detailed error messages
  • Status Management: Default status setting for new upload histories
  • Validation: Comprehensive input validation for all fields
  • Audit Trail: Complete tracking of upload attempts and outcomes

Security Considerations

  • Group Isolation: History records are automatically associated with user's group
  • Input Validation: All fields are validated before storage
  • Error Logging: Failed operations are logged for monitoring
  • User Authentication: Requires authenticated user with group membership