User Story: Upload file SQL DDL chứa database schema¶

1. Description¶

Là Manager, tôi muốn upload file SQL DDL chứa database schema từ đơn vị Sở/Ban/Ngành lên hệ thống, để hệ thống tự động parse câu lệnh CREATE TABLE và trích xuất tên cột, kiểu dữ liệu, nhóm theo bảng phục vụ cho quá trình matching.

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 SQL DDL", chọn đơn vị Sở/Ban/Ngành, chọn file DDL 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 = SQL_DDL, 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 SQL DDL 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 tên cột, kiểu dữ liệu từ các câu lệnh CREATE TABLE, nhóm theo tên bảng, tạo các bản ghi Extracted Field tương ứng (bao gồm field_name, field_data_type, table_name) với matching_status = PENDING, và cập nhật parse_status = COMPLETED
GIVEN file SQL DDL chứa nhiều câu lệnh CREATE TABLE
WHEN hệ thống parse file
THEN hệ thống trích xuất và nhóm field theo từng bảng, mỗi Extracted Field ghi nhận tên bảng gốc (table_name)

2.2 Alternative Paths¶

GIVEN file SQL DDL chứa các câu lệnh không phải CREATE TABLE (ví dụ: INSERT, ALTER, DROP)
WHEN hệ thống parse file
THEN hệ thống bỏ qua các câu lệnh không phải CREATE TABLE và chỉ trích xuất từ CREATE TABLE
GIVEN file SQL DDL có kích thước lớn với nhiều bảng
WHEN hệ thống bắt đầu parse
THEN quá trình parse chạy ở chế độ background job, cập nhật parse_status = PROCESSING, không block giao diện người dùng

2.3 Error Cases¶

GIVEN file upload có phần mở rộng không hợp lệ (không phải .sql hoặc .ddl)
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 về định dạng file không được hỗ trợ
GIVEN file SQL DDL có cú pháp không hợp lệ hoặc không chứa câu lệnh CREATE TABLE nào
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 mô tả nguyên nhân parse thất bại
GIVEN quá trình parse bị lỗi giữa chừng do file quá lớn hoặc lỗi hệ thống
WHEN parse bị gián đoạn
THEN hệ thống cập nhật parse_status = FAILED, không tạo Extracted Field không đầy đủ, và thông báo 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 SQL DDL: hệ thống parse câu lệnh CREATE TABLE để lấy tên cột và kiểu dữ liệu, nhóm theo bảng
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
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, bao gồm thông tin kiểu dữ liệu và tên bảng gốc

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 file CSV (thuộc Story-001)
Upload các định dạng file khác ngoài SQL DDL (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)
Kết nối trực tiếp tới CSDL của đơn vị để đọc schema