Get History by ID

Overview Description

The Get History by ID feature allows clients to retrieve detailed information about a specific upload history record. This feature provides complete information about a single upload including file details, status, error information, and user context. The feature includes group-based access control to ensure users can only access histories from their own group.

Swagger Link

API: Upload Histories API

Case Documentation

Case 1: Get Specific Upload History

Description

Client requests detailed information about a specific upload history by its unique identifier.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: Get History by ID Flow
    
    rect rgb(200, 255, 200)
    Note right of Client: Happy Case Flow
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}
    
    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(id)
    Repository->>Repository: Apply group filter
    Repository->>Database: SELECT with user relationships
    Database-->>Repository: Return history record
    Repository-->>API: Return ReviewUploadHistory model
    end
    
    API-->>Client: 200 OK (history details)
    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 Not Found Error
        Database-->>Repository: No matching record
        Repository-->>API: Null result
        API-->>Client: 404 Not Found
    else Database Error
        Database-->>Repository: Database error
        Repository-->>API: Error result
        API-->>Client: 400 Bad Request
    end
    end
    end

Steps

Step 1: Request History by ID

• Description: Client requests specific history details by ID
• Request: GET /api/v1/general/upload-file/gcs/histories/{id}
• Parameters:
  • id: The unique identifier of the upload history record (required)
• Validation:
  • ID must be a valid integer
  • ID must be greater than 0

Step 2: Retrieve History Details

• Description: System retrieves the specific history record
• Action:
  • Query database by primary key with group filter
  • Include all history fields and relationships
  • Verify user has access to the requested history
  • Return complete history information

Step 3: Return History Details

• Description: Return detailed history information to client
• Response:
  • Success: 200 OK with complete history data
  • 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 retrieval 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	Failed to retrieve history	When database operation fails
  422	Validation failed	When ID parameter is invalid

Key Features

• Detailed Information: Complete history record with all fields and relationships
• Group-Based Access: Automatic filtering by user's group for security
• User Context: Include user information in history details
• Error Handling: Comprehensive error handling with appropriate status codes
• Data Validation: Input validation for history ID parameter

Security Considerations

• Group Isolation: Users can only access histories from their own group
• Input Validation: History ID is validated before database query
• Error Logging: Failed operations are logged for monitoring
• User Authentication: Requires authenticated user with group membership
• Access Control: Automatic group-based filtering prevents unauthorized access