Lịch sử tải lên

Mô tả tổng quan

Tính năng lịch sử tải lên cho phép client truy cập danh sách có phân trang các bản ghi lịch sử tải lên tệp. Tính năng này cho phép người dùng xem lịch sử tải lên với khả năng lọc và phân trang. Lịch sử bao gồm thông tin về các tệp đã tải lên, trạng thái của chúng và các thông báo lỗi liên quan. Điều này hữu ích để theo dõi tiến trình tải lên, xem lại các tải lên trước đó và debug các tải lên thất bại.

Liên kết Swagger

API: API Lưu lịch sử tải lên

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

Trường hợp 1: Lấy lịch sử tải lên có phân trang

Mô tả

Client yêu cầu danh sách có phân trang các bản ghi lịch sử tải lên của nhóm người dùng hiện tại.

Sơ đồ tuần tự

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: Luồng lấy lịch sử tải lên
    
    rect rgb(200, 255, 200)
    Note right of Client: Luồng thành công
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/list
    
    rect rgb(200, 230, 255)
    Note right of API: Xác thực đầu vào
    API->>API: Xác thực tham số yêu cầu
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Logic nghiệp vụ
    API->>Service: getHistories(request->all())
    Service->>Repository: serverPaginationFilteringFor(params)
    Repository->>Repository: Lấy group_id của người dùng đăng nhập
    Repository->>Database: SELECT với bộ lọc nhóm và phân trang
    Database-->>Repository: Trả về kết quả phân trang
    Repository-->>Service: Trả về LengthAwarePaginator
    Service-->>API: Trả về dữ liệu lịch sử
    end
    
    API-->>Client: 200 OK (dữ liệu lịch sử có phân trang)
    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 cơ sở dữ liệu
        Database-->>Repository: Lỗi cơ sở dữ liệu
        Repository-->>Service: Kết quả lỗi
        Service-->>API: Kết quả lỗi
        API-->>Client: 400 Bad Request
    else Lỗi service
        Service-->>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ử tải lên

Mô tả: Client yêu cầu danh sách có phân trang lịch sử tải lên
Yêu cầu: GET /api/v1/general/upload-file/gcs/histories/list
Tham số:
- per_page: Số bản ghi trên mỗi trang (tùy chọn, mặc định: 10)
- page: Số trang cho phân trang (tùy chọn, mặc định: 1)
Xác thực:
- Per page phải là số nguyên dương
- Page phải là số nguyên dương

Bước 2: Lấy lịch sử có phân trang

Mô tả: Hệ thống lấy lịch sử tải lên của nhóm người dùng với phân trang
Hành động:
- Lấy group_id của người dùng đăng nhập
- Truy vấn cơ sở dữ liệu với bộ lọc nhóm và phân trang
- Bao gồm dữ liệu relationship người dùng
- Sắp xếp theo ngày tạo (mới nhất trước)

Bước 3: Trả về kết quả phân trang

Mô tả: Trả về dữ liệu lịch sử có phân trang cho client
Phản hồi:
- Thành công: 200 OK (dữ liệu lịch sử có phân trang bao gồm metadata)
- Lỗi: Mã lỗi và thông báo phù hợp

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

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 tệp được lưu trong Google Cloud Storage"
        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 khi tải lên thất bại (có thể null)"
        timestamp validated_at "Thời điểm 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"
    }

    review_upload_histories ||--o{ users : Thuộc về

Xử lý lỗi

Ghi log
- Lỗi lấy 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ả

422 Lỗi xác thực Tham số phân trang không hợp lệ

400 Không thể lấy lịch sử Thao tác cơ sở dữ liệu thất bại

Mã trạng thái	Thông báo lỗi	Mô tả
422	Lỗi xác thực	Tham số phân trang không hợp lệ
400	Không thể lấy lịch sử	Thao tác cơ sở dữ liệu thất bại

Tính năng chính

Lọc dựa trên nhóm: Tự động lọc theo nhóm của người dùng để bảo mật dữ liệu
Phân trang: Hỗ trợ tập dữ liệu lớn với kích thước trang có thể cấu hình
Relationship người dùng: Bao gồm thông tin người dùng trong bản ghi lịch sử
Sắp xếp: Sắp xếp mặc định theo ngày tạo (mới nhất trước)
Xử lý lỗi: Xử lý lỗi toàn diện với ghi log chi tiết

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

Phân tách nhóm: Người dùng chỉ có thể truy cập lịch sử tải lên của nhóm mình
Xác thực đầu vào: Tất cả tham số phân trang được xác thực
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

03.upload-histories