User Story: Xử lý lỗi khi parse file thất bại¶

1. Description¶

Là Manager, tôi muốn nhận được thông báo lỗi rõ ràng khi hệ thống parse file thất bại và có thể upload lại file, để tôi không bị mất thời gian và có thể nhanh chóng khắc phục vấn đề.

2. Acceptance Criteria¶

2.1 Happy Path¶

GIVEN quá trình parse file metadata thất bại (parse_status = FAILED)
WHEN Manager xem danh sách nguồn metadata trên màn hình SCR-DISC-10
THEN nguồn metadata bị lỗi hiển thị trạng thái FAILED kèm thông báo lỗi mô tả nguyên nhân (ví dụ: "File CSV rỗng", "Không tìm thấy câu lệnh CREATE TABLE", "Cú pháp DDL không hợp lệ tại dòng X")
GIVEN nguồn metadata có parse_status = FAILED
WHEN Manager chọn hành động "Upload lại" trên nguồn metadata bị lỗi
THEN hệ thống mở popup cho phép Manager chọn file mới để upload, giữ nguyên thông tin đơn vị đã chọn trước đó
GIVEN Manager upload file mới thay thế cho nguồn metadata bị lỗi
WHEN upload thành công
THEN hệ thống tạo bản ghi Metadata Source mới với parse_status = PENDING và tự động bắt đầu parse lại

2.2 Alternative Paths¶

GIVEN nguồn metadata có parse_status = FAILED
WHEN Manager không muốn upload lại và chọn chuyển sang khai báo thủ công
THEN hệ thống cho phép Manager chuyển sang phương thức khai báo thủ công cho cùng đơn vị đó (điều hướng đến chức năng khai báo thủ công)
GIVEN nguồn metadata có parse_status = FAILED
WHEN Manager muốn xóa nguồn metadata bị lỗi
THEN hệ thống cho phép xóa bản ghi Metadata Source có trạng thái FAILED (không có Extracted Field liên quan)

2.3 Error Cases¶

GIVEN Manager upload lại file mới cho nguồn metadata bị lỗi
WHEN file mới cũng gặp lỗi parse
THEN hệ thống cập nhật parse_status = FAILED cho nguồn metadata mới, hiển thị thông báo lỗi chi tiết, và cho phép Manager tiếp tục thử lại
GIVEN quá trình parse đang chạy ở chế độ background job (parse_status = PROCESSING)
WHEN xảy ra lỗi hệ thống trong quá trình xử lý nền
THEN hệ thống cập nhật parse_status = FAILED, ghi nhận thông tin lỗi, và thông báo cho Manager qua cơ chế thông báo hệ thống

3. Business Rules¶

Khi parse thất bại (parse_status = FAILED), hệ thống phải hiển thị thông báo lỗi chi tiết, mô tả nguyên nhân cụ thể
Manager có thể upload lại hoặc chuyển sang khai báo thủ công khi parse thất bại
Nguồn metadata có parse_status = FAILED không tạo ra Extracted Field nào
Background job cần có cơ chế thông báo khi xử lý thất bại
Không giới hạn số lần upload lại khi parse thất bại

4. Traceability¶

Feature: Upload & Phân tích Metadata

Screens: - SCR-DISC-10: Danh sách nguồn metadata - SCR-DISC-11: Popup Nhập metadata

Business Flows: - BPF-01: Vòng đời Quy hoạch Dữ liệu Thành phố

Business Entities: - Metadata Source

Role Matrix: - RM-001: Manager – Quản trị dữ liệu kỹ thuật

Third-Party Integrations: Không áp dụng

5. Out of Scope¶

Cơ chế tự động retry parse khi thất bại (retry tự động là quyết định thiết kế kỹ thuật)
Gửi email thông báo lỗi cho Manager
Phân tích chi tiết nội dung file để gợi ý sửa lỗi