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

Mô tả tổng quan

Tính năng lưu lịch sử tải lên cho phép client lưu metadata về việc tải lên tệp lên Google Cloud Storage. Tính năng này lưu trữ thông tin về các tệp đã tải lên bao gồm tên tệp, đường dẫn GCS, trạng thái tải lên và lý do lỗi. Lịch sử này được sử dụng để theo dõi tiến trình tải lên, debug các tải lên thất bại và cung cấp audit trail cho các thao tác quản lý tệp.

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ưu lịch sử tải lên thành công

Mô tả

Client lưu metadata về một tệp đã tải lên thành công để theo dõi lịch sử tải lên.

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ưu lịch sử tải lên
    
    rect rgb(200, 255, 200)
    Note right of Client: Luồng thành công
    
    Client->>API: POST /api/v1/general/upload-file/gcs/upload-history
    
    rect rgb(200, 230, 255)
    Note right of API: Xác thực đầu vào
    API->>API: Xác thực dữ liệu yêu cầu bằng StoreUploadHistoryRequest
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Logic nghiệp vụ
    API->>Service: createHistory(request->all())
    Service->>Service: Lấy thông tin người dùng đăng nhập và nhóm
    Service->>Repository: create(historyData)
    Repository->>Database: INSERT INTO review_upload_histories
    Database-->>Repository: Trả về bản ghi đã tạo
    Repository-->>Service: Trả về model ReviewUploadHistory
    Service-->>API: Trả về dữ liệu lịch sử
    end
    
    API-->>Client: 200 OK (dữ liệu 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 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: Gửi lịch sử tải lên

• Mô tả: Client gửi dữ liệu lịch sử sau khi tải lên tệp thành công
• Yêu cầu: POST /api/v1/general/upload-file/gcs/upload-history
• Tham số:
  • file_name: Tên tệp đã tải lên (bắt buộc)
  • gcs_path: Đường dẫn tệp được lưu trong Google Cloud Storage (bắt buộc)
  • error_reason: Thông báo lỗi khi tải lên thất bại (tùy chọn)
• Xác thực:
  • Tên tệp phải là chuỗi và không quá 255 ký tự
  • Đường dẫn GCS phải là chuỗi
  • Lý do lỗi phải là chuỗi và không quá 255 ký tự (nếu được cung cấp)

Bước 2: Xử lý lưu lịch sử

• Mô tả: Hệ thống lưu lịch sử tải lên với ngữ cảnh người dùng và nhóm
• Hành động:
  • Lấy thông tin người dùng đang đăng nhập
  • Lấy group_id từ thành viên nhóm của người dùng
  • Tạo bản ghi lịch sử với user_id, group_id và dữ liệu được cung cấp
  • Đặt trạng thái mặc định là 'Notyet' (0)

Bước 3: Trả về dữ liệu lịch sử

• Mô tả: Trả về bản ghi lịch sử đã tạo cho client
• Phản hồi:
  • Thành công: 200 OK (dữ liệu lịch sử đầy đủ bao gồm ID, timestamp, relationships)
  • 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"
    }
    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 lưu 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ố yêu cầu không hợp lệ
  400	Không thể lưu lịch sử	Thao tác cơ sở dữ liệu thất bại

Trường hợp 2: Lưu lịch sử tải lên thất bại

Mô tả

Client lưu metadata về một tệp tải lên thất bại với thông tin lỗi để debug.

Các bước

Bước 1: Gửi lịch sử tải lên thất bại

• Mô tả: Client gửi lịch sử tải lên với thông tin lỗi
• Yêu cầu: POST /api/v1/general/upload-file/gcs/upload-history
• Tham số:
  • file_name: Tên tệp tải lên thất bại
  • gcs_path: Đường dẫn GCS dự định
  • error_reason: Thông báo lỗi chi tiết giải thích lý do thất bại

Bước 2: Xử lý lưu lịch sử thất bại

• Mô tả: Hệ thống lưu lịch sử tải lên thất bại với ngữ cảnh lỗi
• Hành động:
  • Lưu bản ghi lịch sử với trường error_reason được điền
  • Duy trì cùng ngữ cảnh người dùng và nhóm như tải lên thành công
  • Kích hoạt tính năng theo dõi lỗi và debug

Bước 3: Trả về dữ liệu lịch sử thất bại

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

Xử lý lỗi

• Ghi log
  • Lỗi lưu lịch sử tải lên thất bại được ghi log để debug
• 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ố yêu cầu không hợp lệ
  400	Không thể lưu lịch sử	Thao tác cơ sở dữ liệu thất bại

Tính năng chính

• Ngữ cảnh người dùng: Tự động liên kết với người dùng đăng nhập và nhóm của họ
• Theo dõi lỗi: Hỗ trợ lưu thông báo lỗi chi tiết
• Quản lý trạng thái: Đặt trạng thái mặc định cho lịch sử tải lên mới
• Xác thực: Xác thực đầu vào toàn diện cho tất cả trường
• Audit trail: Theo dõi hoàn toàn các lần thử tải lên và kết quả

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

• Phân tách nhóm: Bản ghi lịch sử được tự động liên kết với nhóm của người dùng
• Xác thực đầu vào: Tất cả trường được xác thực trước khi lư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