User Story: Upload file CSV chứa metadata cấu trúc¶

1. Description¶

Là Manager, tôi muốn upload file CSV chứa metadata cấu trúc từ đơn vị Sở/Ban/Ngành lên hệ thống, để hệ thống tự động parse header row và trích xuất danh sách field names phục vụ cho quá trình matching với Anchored Data.

2. Acceptance Criteria¶

2.1 Happy Path¶

GIVEN Manager đã đăng nhập hệ thống với vai trò Manager và đang ở màn hình Danh sách nguồn metadata
WHEN Manager nhấn nút "Nhập metadata", chọn phương thức "Upload file CSV", chọn đơn vị Sở/Ban/Ngành từ danh sách, chọn file CSV từ máy tính và xác nhận upload
THEN hệ thống tạo bản ghi Metadata Source với file_type = CSV, parse_status = PENDING, gắn với đơn vị đã chọn, và tự động bắt đầu quá trình parse
GIVEN hệ thống đã nhận file CSV hợp lệ và bắt đầu parse
WHEN quá trình parse hoàn tất thành công
THEN hệ thống trích xuất danh sách field names từ header row (dòng đầu tiên), tạo các bản ghi Extracted Field tương ứng với matching_status = PENDING, cập nhật parse_status = COMPLETED, và hiển thị tổng số field đã trích xuất
GIVEN file CSV có kích thước lớn
WHEN hệ thống bắt đầu parse
THEN quá trình parse chạy ở chế độ background job, không block giao diện người dùng, hiển thị trạng thái PROCESSING cho Manager theo dõi

2.2 Alternative Paths¶

GIVEN Manager đang upload file CSV
WHEN Manager chọn nhầm đơn vị và muốn thay đổi trước khi xác nhận
THEN Manager có thể thay đổi đơn vị Sở/Ban/Ngành từ danh sách trước khi nhấn xác nhận upload
GIVEN một đơn vị đã có nguồn metadata trước đó (từ upload hoặc khai báo thủ công)
WHEN Manager upload thêm file CSV mới cho cùng đơn vị
THEN hệ thống tạo nguồn metadata mới, không ghi đè lên nguồn metadata cũ

2.3 Error Cases¶

GIVEN Manager chọn file không phải định dạng CSV (ví dụ: file Excel, JSON, PDF)
WHEN Manager xác nhận upload
THEN hệ thống từ chối upload và hiển thị thông báo lỗi "Chỉ hỗ trợ file CSV hoặc SQL DDL"
GIVEN Manager không chọn đơn vị Sở/Ban/Ngành
WHEN Manager xác nhận upload
THEN hệ thống hiển thị thông báo lỗi yêu cầu chọn đơn vị trước khi upload
GIVEN file CSV được upload nhưng file rỗng hoặc không có header row
WHEN hệ thống thực hiện parse
THEN hệ thống cập nhật parse_status = FAILED và hiển thị thông báo lỗi chi tiết cho Manager

3. Business Rules¶

Chỉ Manager có quyền upload file metadata
Mỗi file upload phải được gắn với một đơn vị Sở/Ban/Ngành cụ thể
File CSV: hệ thống parse header row (dòng đầu tiên) để lấy danh sách field names
Hệ thống tự động bắt đầu parse ngay sau khi upload thành công
Với file lớn, parse chạy ở chế độ background job để không ảnh hưởng trải nghiệm người dùng
Trạng thái parse chuyển theo luồng: PENDING -> PROCESSING -> COMPLETED hoặc FAILED
Kết quả parse tạo ra các bản ghi Extracted Field với matching_status = PENDING

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 - Extracted Field

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¶

Upload các định dạng file khác ngoài CSV (Excel, JSON, v.v.)
Khai báo metadata thủ công (thuộc EP-03-002)
Matching field với Anchored Data (thuộc EP-03-004)
Phân tích cấu trúc metadata sau khi parse (thuộc Story-003)
Kết nối trực tiếp tới CSDL của đơn vị để đọc schema