Lấy lịch sử theo ID

Mô tả Tổng quan

Tính năng Lấy lịch sử theo ID cho phép client truy xuất thông tin chi tiết về một bản ghi lịch sử tải lên cụ thể. Tính năng này cung cấp thông tin hoàn chỉnh về một lần tải lên bao gồm chi tiết tệp, trạng thái, thông tin lỗi và ngữ cảnh người dùng. Tính năng bao gồm kiểm soát truy cập dựa trên nhóm để đảm bảo người dùng chỉ có thể truy cập lịch sử từ nhóm của họ.

Liên kết Swagger

API: API Lấy lịch sử theo ID

Tài liệu Trường hợp

Trường hợp 1: Lấy lịch sử tải lên cụ thể

Mô tả

Client yêu cầu thông tin chi tiết về một lịch sử tải lên cụ thể bằng định danh duy nhất của nó.

Sơ đồ Tuần tự

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: Luồng lấy lịch sử theo ID
    
    rect rgb(200, 255, 200)
    Note right of Client: Luồng trường hợp thành công
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}
    
    rect rgb(200, 230, 255)
    Note right of API: Xác thực đầu vào
    API->>API: Xác thực tham số ID lịch sử
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Logic nghiệp vụ
    API->>Repository: findById(id)
    Repository->>Repository: Áp dụng bộ lọc nhóm
    Repository->>Database: SELECT với mối quan hệ người dùng
    Database-->>Repository: Trả về bản ghi lịch sử
    Repository-->>API: Trả về model ReviewUploadHistory
    end
    
    API-->>Client: 200 OK (chi tiết lịch sử)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Xử lý lỗi
    rect rgb(255, 230, 230)
    alt Lỗi xác thực
        API-->>Client: 422 Lỗi xác thực
    else Lỗi không tìm thấy
        Database-->>Repository: Không có bản ghi phù hợp
        Repository-->>API: Kết quả null
        API-->>Client: 404 Not Found
    else Lỗi cơ sở dữ liệu
        Database-->>Repository: Lỗi cơ sở dữ liệu
        Repository-->>API: Kết quả lỗi
        API-->>Client: 400 Bad Request
    end
    end
    end

Các bước

Bước 1: Yêu cầu lịch sử theo ID

Mô tả: Client yêu cầu chi tiết lịch sử cụ thể theo ID
Yêu cầu: GET /api/v1/general/upload-file/gcs/histories/{id}
Tham số:
- id: Định danh duy nhất của bản ghi lịch sử tải lên (bắt buộc)
Xác thực:
- ID phải là số nguyên hợp lệ
- ID phải lớn hơn 0

Bước 2: Truy xuất chi tiết lịch sử

Mô tả: Hệ thống truy xuất bản ghi lịch sử cụ thể
Hành động:
- Truy vấn cơ sở dữ liệu theo khóa chính với bộ lọc nhóm
- Bao gồm tất cả trường lịch sử và mối quan hệ
- Xác minh người dùng có quyền truy cập vào lịch sử được yêu cầu
- Trả về thông tin lịch sử hoàn chỉnh

Bước 3: Trả về chi tiết lịch sử

Mô tả: Trả về thông tin lịch sử chi tiết cho client
Phản hồi:
- Thành công: 200 OK với dữ liệu lịch sử hoàn chỉnh
- Lỗi: Mã lỗi thích hợp với thông báo

Bảng và trường liên quan đến cơ sở dữ liệu

erDiagram
    review_upload_histories {
        bigint id PK
        bigint user_id FK "Tham chiếu đến bảng users"
        bigint group_id FK "Tham chiếu đến bảng groups"
        string file_name "Tên tệp đã tải lên"
        string gcs_path "Đường dẫn Google Cloud Storage nơi tệp được lưu trữ"
        tinyInteger status "Trạng thái tải lên: 0=Chưa xử lý, 1=đang xử lý, 2=thành công, 3=thất bại"
        string error_reason "Thông báo lỗi nếu tải lên thất bại (có thể null)"
        timestamp validated_at "Thời gian khi tệp được xác thực (có thể null)"
        timestamp created_at
        timestamp updated_at
    }
    users {
        bigint id PK
        string name "Họ tên đầy đủ của người dùng"
        string email "Địa chỉ email của người dùng"
    }
    groups {
        bigint id PK
        string name "Tên nhóm"
    }

    review_upload_histories ||--o{ users : thuộc về
    review_upload_histories ||--o{ groups : thuộc về

Xử lý lỗi

Ghi log
- Lỗi truy xuất lịch sử được ghi vào log ứng dụng

Chi tiết lỗi:

Mã trạng thái	Thông báo lỗi	Mô tả
404	Lịch sử không tìm thấy	Khi bản ghi lịch sử với ID được chỉ định không tồn tại
400	Không thể truy xuất lịch sử	Khi thao tác cơ sở dữ liệu thất bại
422	Xác thực thất bại	Khi tham số ID không hợp lệ

Tính năng chính

Thông tin chi tiết: Bản ghi lịch sử hoàn chỉnh với tất cả trường và mối quan hệ
Truy cập dựa trên nhóm: Tự động lọc theo nhóm của người dùng để bảo mật
Ngữ cảnh người dùng: Bao gồm thông tin người dùng trong chi tiết lịch sử
Xử lý lỗi: Xử lý lỗi toàn diện với mã trạng thái thích hợp
Xác thực dữ liệu: Xác thực đầu vào cho tham số ID lịch sử

Cân nhắc bảo mật

Cô lập nhóm: Người dùng chỉ có thể truy cập lịch sử từ nhóm của họ
Xác thực đầu vào: ID lịch sử được xác thực trước khi truy vấn cơ sở dữ liệu
Ghi log lỗi: Các thao tác thất bại được ghi log để giám sát
Xác thực người dùng: Yêu cầu người dùng đã xác thực với thành viên nhóm
Kiểm soát truy cập: Tự động lọc dựa trên nhóm ngăn chặn truy cập trái phép

04.get-history-by-id