Lấy lỗi nhập

Mô tả Tổng quan

Tính năng Lấy lỗi nhập cho phép client truy xuất lỗi xác thực cho một lịch sử tải lên cụ thể. Tính năng này cung cấp thông tin lỗi chi tiết bao gồm tiêu đề trường, giá trị có vấn đề, số dòng và thông báo lỗi. Các lỗi được lưu trữ trong một bảng riêng biệt và liên kết với lịch sử tải lên, cho phép theo dõi lỗi toàn diện và gỡ lỗi cho các lần nhập CSV thất bại.

Liên kết Swagger

API: API Lấy lỗi nhập

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

Trường hợp 1: Lấy lỗi nhập cho lịch sử

Mô tả

Client yêu cầu lỗi xác thực chi tiết cho một bản ghi lịch sử tải lên cụ thể.

Sơ đồ Tuần tự

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadErrorRepository
    participant Resource as ImportReviewCSVErrorResource
    participant Database as Database
    
    Note over Client,Database: Luồng lấy lỗi nhập
    
    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}/import-errors
    
    rect rgb(200, 230, 255)
    Note right of API: Xác thực đầu vào
    API->>API: Xác thực ID lịch sử và tham số phân trang
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Logic nghiệp vụ
    API->>Repository: serverPaginationFilteringFor(historyId, params)
    Repository->>Repository: Áp dụng bộ lọc ID lịch sử và phân trang
    Repository->>Database: SELECT review_upload_errors với phân trang
    Database-->>Repository: Trả về kết quả lỗi có phân trang
    Repository-->>API: Trả về LengthAwarePaginator
    end
    
    rect rgb(255, 255, 200)
    Note right of API: Chuyển đổi tài nguyên
    API->>Resource: collection(errors)
    Resource->>Resource: Chuyển đổi từng bản ghi lỗi
    Resource-->>API: Trả về collection được định dạng
    end
    
    API-->>Client: 200 OK (dữ liệu lỗi được định dạng)
    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ó lỗi 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ỗi nhập

Mô tả: Client yêu cầu lỗi xác thực cho lịch sử tải lên cụ thể
Yêu cầu: GET /api/v1/general/upload-file/gcs/histories/{id}/import-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)
- 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:
- ID lịch sử phải là số nguyên hợp lệ
- Per page phải là số nguyên dương
- Page phải là số nguyên dương

Bước 2: Truy xuất dữ liệu lỗi

Mô tả: Hệ thống truy xuất lỗi xác thực cho lịch sử được chỉ định
Hành động:
- Truy vấn bảng review_upload_errors được lọc theo ID lịch sử
- Áp dụng phân trang cho kết quả lỗi
- Bao gồm tất cả trường lỗi (header, value, error_line, error_messages)
- Trả về collection lỗi có phân trang

Bước 3: Chuyển đổi và trả về kết quả

Mô tả: Chuyển đổi dữ liệu lỗi và trả về cho client
Phản hồi:
- Thành công: 200 OK với collection lỗi được định dạng bao gồm metadata
- 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
    }
    review_upload_errors {
        bigint id PK
        bigint review_upload_history_id FK "Tham chiếu đến bảng review_upload_histories"
        string header "Tiêu đề trường gây ra lỗi (có thể null)"
        string value "Giá trị dữ liệu có vấn đề (có thể null)"
        integer error_line "Số dòng nơi lỗi xảy ra (có thể null)"
        json error_messages "Mảng thông báo lỗi cho trường"
        timestamp created_at
        timestamp updated_at
    }

    review_upload_histories ||--o{ review_upload_errors : có nhiều

Xử lý lỗi

Ghi log
- Lỗi truy xuất lỗi nhập đượ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ỗi nhập không tìm thấy	Khi không có lỗi tồn tại cho lịch sử được chỉ định
400	Không thể lấy lỗi nhập	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ố không hợp lệ

Tính năng chính

Thông tin lỗi chi tiết: Thông tin lỗi hoàn chỉnh bao gồm tiêu đề trường, giá trị và số dòng
Hỗ trợ phân trang: Xử lý tập dữ liệu lỗi lớn với phân trang có thể cấu hình
Chuyển đổi tài nguyên API: Định dạng dữ liệu lỗi nhất quán sử dụng Laravel resources
Liên kết lịch sử: Lỗi được liên kết với lịch sử tải lên cụ thể
Mảng thông báo lỗi: Hỗ trợ nhiều thông báo lỗi cho mỗi trường
Theo dõi số dòng: Theo dõi số dòng cụ thể nơi lỗi xảy ra

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

Liên kết lịch sử: Lỗi được lọc theo ID lịch sử tải lên
Xác thực đầu vào: Tất cả tham 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
Làm sạch dữ liệu: API resources đảm bảo đầu ra dữ liệu lỗi an toàn

05.get-import-errors