Tải xuống CSV lỗi

Mô tả Tổng quan

Tính năng Tải xuống CSV lỗi cho phép client tải xuống một tệp CSV chứa thông tin lỗi chi tiết cho một lịch sử tải lên cụ thể. Tính năng này tạo ra một tệp CSV có thể tải xuống với lỗi xác thực, bao gồm tiêu đề trường, giá trị có vấn đề, số dòng và thông báo lỗi. Tệp CSV được tạo từ dữ liệu lỗi được lưu trữ trong Google Cloud Storage và cung cấp báo cáo lỗi toàn diện để sửa dữ liệu.

Liên kết Swagger

API: API Tải xuống CSV lỗi

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

Trường hợp 1: Tải xuống tệp CSV lỗi

Mô tả

Client yêu cầu một tệp CSV có thể tải xuống chứa lỗi xác thực cho một lịch sử tải lên cụ thể.

Sơ đồ Tuần tự

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadHistoryRepository
    participant ExportService as ExportService
    participant GCS as Google Cloud Storage
    
    Note over Client,GCS: Luồng tải xuống CSV lỗi
    
    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}/download-errors
    
    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(historyId)
    Repository->>Repository: Áp dụng bộ lọc nhóm
    Repository-->>API: Trả về model ReviewUploadHistory
    API->>API: Kiểm tra nếu error_reason tồn tại
    end
    
    rect rgb(255, 255, 200)
    Note right of API: Tạo CSV
    API->>ExportService: handle(reviewUploadHistory)
    ExportService->>ExportService: Phân tích JSON error_reason
    ExportService->>GCS: Lấy nội dung tệp lỗi
    GCS-->>ExportService: Trả về nội dung CSV
    ExportService->>ExportService: Thiết lập headers phản hồi
    ExportService-->>API: Trả về phản hồi CSV
    end
    
    API-->>Client: 200 OK (tệp CSV để tải xuống)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Xử lý lỗi
    rect rgb(255, 230, 230)
    alt Lịch sử không tìm thấy
        Repository-->>API: Kết quả null
        API-->>Client: 404 Not Found
    else Không có tệp lỗi
        API->>API: Kiểm tra trường error_reason
        API-->>Client: 400 Bad Request (lỗi trống)
    else Lỗi GCS
        GCS-->>ExportService: Phản hồi lỗi
        ExportService-->>API: Kết quả lỗi
        API-->>Client: 500 Internal Server Error
    end
    end
    end

Các bước

Bước 1: Yêu cầu tải xuống CSV lỗi

Mô tả: Client yêu cầu tệp CSV với lỗi xác thực
Yêu cầu: GET /api/v1/general/upload-file/gcs/histories/{id}/download-errors
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 lịch sử phải là số nguyên hợp lệ
- ID lịch sử phải lớn hơn 0

Bước 2: Truy xuất lịch sử và xác thực

Mô tả: Hệ thống truy xuất lịch sử tải lên và xác thực dữ liệu lỗi
Hành động:
- Truy vấn cơ sở dữ liệu cho bản ghi lịch sử theo ID với bộ lọc nhóm
- Xác minh bản ghi lịch sử tồn tại
- Kiểm tra nếu trường error_reason chứa dữ liệu lỗi
- Xác thực người dùng có quyền truy cập vào lịch sử được yêu cầu

Bước 3: Tạo và trả về CSV

Mô tả: Tạo tệp CSV từ dữ liệu lỗi và trả về cho client
Hành động:
- Phân tích JSON error_reason để trích xuất đường dẫn tệp lỗi
- Truy xuất nội dung CSV từ Google Cloud Storage
- Thiết lập headers phản hồi thích hợp cho tải xuống CSV
- Trả về tệp CSV như phản hồi có thể tải xuống

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 tải xuống CSV đượ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	Lỗi trống	Khi lịch sử không có dữ liệu lỗi để tải xuống
500	Không thể tải xuống CSV	Khi thao tác GCS thất bại

Tính năng chính

Tạo tệp CSV: Tạo tệp CSV có thể tải xuống với dữ liệu lỗi
Truy xuất dữ liệu lỗi: Truy xuất tệp lỗi từ Google Cloud Storage
Tải xuống tệp: Headers HTTP thích hợp cho tải xuống tệp CSV
Xác thực lỗi: Kiểm tra sự tồn tại của dữ liệu lỗi trước khi xử lý
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
Ghi log 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

Cô lập nhóm: Người dùng chỉ có thể tải xuống lỗi từ lịch sử của nhóm của họ
Xác thực đầu vào: ID lịch sử được xác thực trước khi xử lý
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ệp: Tệp lỗi được lưu trữ ở vị trí GCS an toàn
Làm sạch dữ liệu: Nội dung CSV được định dạng đúng cách và an toàn để tải xuống

06.download-error-csv