Business Entity Specification: Nền Tảng Quản Lý, Quản Trị Dữ Liệu Thành Phố¶

Phiên bản: 1.0 (Draft) Ngày tạo: 2026-03-31 Trạng thái: Draft – Chờ xác nhận từ stakeholder Nguồn: Business Understanding, Use Case Overview, BPF-01, Screen Flow

1. Tổng Quan¶

Tài liệu định nghĩa các thực thể nghiệp vụ cốt lõi của hệ thống, thuộc tính và mối quan hệ giữa chúng. Hệ thống chỉ quản lý metadata – không lưu dữ liệu thực tế.

2. Entity Relationship Diagram¶

Kroki

3. Danh Sách Entity¶

entity-domain¶

Name: Domain (Lĩnh vực dữ liệu) Description: Nhóm phân loại dữ liệu cấp cao nhất. Đại diện cho một chủ thể/đối tượng quản lý lớn của Thành phố (VD: Con người, Tổ chức, Đất đai). Tham chiếu: Phụ lục A.

entity-sub-domain¶

Name: Sub Domain (Phân nhóm dữ liệu) Description: Phân nhóm trong một Domain, chia nhỏ theo khía cạnh cụ thể hơn (VD: Domain "Con người" → Sub Domain "Định danh", "Y tế & Sức khỏe").

entity-data-element¶

Name: Data Element (Thành phần dữ liệu) Description: Đơn vị metadata nhỏ nhất được quản lý. Mỗi Data Element định nghĩa một trường dữ liệu gồm: tên, mô tả, kiểu dữ liệu, mã định danh. Hệ thống lưu định nghĩa, không lưu giá trị thực tế. Mỗi Data Element chỉ có một đơn vị chủ quản duy nhất (quy tắc 1:1).

entity-organization-unit¶

Name: Organization Unit (Đơn vị tổ chức) Description: Sở/Ban/Ngành/Phòng thuộc Thành phố. Có cấu trúc phân cấp (cây tổ chức). Mỗi đơn vị có thể đóng vai trò chủ quản (Data Owner) của một hoặc nhiều Data Element.

entity-user¶

Name: User (Người dùng) Description: Người sử dụng hệ thống, đăng nhập qua SSO. Mỗi user thuộc một đơn vị và được gán một hoặc nhiều vai trò (Manager, Data Owner, Approver, Staff, Admin).

entity-metadata-source¶

Name: Metadata Source (Nguồn metadata) Description: File dữ liệu được upload lên hệ thống bởi Manager, chứa thông tin cấu trúc dữ liệu của một đơn vị. Hỗ trợ: file CSV (header chứa field names), file SQL DDL (database schema). Mỗi file gắn với một đơn vị cụ thể.

entity-extracted-field¶

Name: Extracted Field (Trường dữ liệu đã trích xuất) Description: Một field name được hệ thống tự động parse/trích xuất từ Metadata Source. Bao gồm: tên field, kiểu dữ liệu (nếu có từ DDL), bảng/entity gốc. Là đầu vào cho quá trình matching với Anchored Data.

entity-matching-result¶

Name: Matching Result (Kết quả đối chiếu) Description: Kết quả của việc đối chiếu một Extracted Field với một Data Element trong Anchored Data. Gồm: confident score, trạng thái (auto-matched, manual-matched, rejected, unmatched). Đây là dữ liệu cốt lõi để xây dựng bản đồ hiện trạng.

entity-source-mapping¶

Name: Source Mapping (Ô Bản đồ Hiện trạng) Description: Một ô trong ma trận Bảng C (Data Element × Đơn vị). Mỗi record ghi nhận trạng thái dữ liệu tại một đơn vị cho một Data Element cụ thể. Hỗ trợ 8 trạng thái bao gồm DISPUTED (tranh chấp) với quy trình giải quyết bởi Approver. Là nền tảng để Approver phê duyệt Bảng C tổng thể.

4. Chi Tiết Entity¶

Entity: Domain (Lĩnh vực dữ liệu)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
code	Mã Domain	Yes	Text	Mã nghiệp vụ	Format: DM{N} (VD: DM1)	Unique, Not Null
name	Tên Domain	Yes	Text	Tên lĩnh vực dữ liệu	Min 2, Max 200 ký tự	Not Null
description	Mô tả	No	Text	Mô tả chi tiết về lĩnh vực	Max 1000 ký tự	—
created_at	Ngày tạo	Yes	DateTime	Thời điểm tạo	Auto-generated	Read-only
updated_at	Ngày cập nhật	Yes	DateTime	Thời điểm cập nhật cuối	Auto-generated	Read-only

Business Rules¶

Mã Domain phải duy nhất trong toàn hệ thống
Mã tự động sinh theo định dạng [DM{N}] (VD: DM1, DM2) — không cho phép chỉnh sửa thủ công sau khi tạo
Không thể xóa Domain nếu còn Sub Domain con
Chỉ Manager được tạo Domain cấp cao — Data Owner không có quyền tạo Domain mới

Entity: Sub Domain (Phân nhóm dữ liệu)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
code	Mã Sub Domain	Yes	Text	Mã nghiệp vụ	Format: DM{N}.{M} (VD: DM1.1)	Unique, Not Null
domain_id	Domain cha	Yes	Number	Tham chiếu đến Domain	Phải tồn tại	FK → Domain.id
name	Tên Sub Domain	Yes	Text	Tên phân nhóm	Min 2, Max 200 ký tự	Not Null
description	Mô tả	No	Text	Mô tả chi tiết	Max 1000 ký tự	—
created_at	Ngày tạo	Yes	DateTime	Thời điểm tạo	Auto-generated	Read-only
updated_at	Ngày cập nhật	Yes	DateTime	Thời điểm cập nhật cuối	Auto-generated	Read-only

Business Rules¶

Mã Sub Domain phải duy nhất trong toàn hệ thống
Mã tự động sinh theo định dạng [DM{N}.{M}] (VD: DM1.1) — không cho phép chỉnh sửa thủ công sau khi tạo
Prefix phải khớp với Domain cha (DM1.x thuộc DM1)
Không thể xóa Sub Domain nếu còn Data Element con
Data Owner có thể đề xuất Sub Domain mới trong Domain đã có (trạng thái PENDING → Manager phê duyệt)

Entity: Data Element (Thành phần dữ liệu)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
code	Mã Data Element	Yes	Text	Mã nghiệp vụ	Format: DE{NNN}-DM{N}.{M} (VD: DE001-DM1.1)	Unique, Not Null
sub_domain_id	Sub Domain cha	Yes	Number	Tham chiếu đến Sub Domain	Phải tồn tại	FK → Sub Domain.id
name	Tên Data Element	Yes	Text	Tên trường dữ liệu	Min 2, Max 200 ký tự	Not Null
description	Mô tả	Yes	Text	Ý nghĩa nghiệp vụ của trường	Min 10, Max 2000 ký tự	Not Null
data_type	Kiểu dữ liệu	Yes	Enum	Kiểu dữ liệu logic	Values: Text, Number, Date, Boolean, Enum, Other	Not Null
status	Trạng thái	Yes	Enum	Trạng thái vòng đời quy hoạch	Values: DRAFT, IN_REVIEW, APPROVED, PUBLISHED	Default: DRAFT
sensitivity_level	Mức độ nhạy cảm	Yes	Enum	Phân loại mức độ nhạy cảm của dữ liệu	Values: PUBLIC, INTERNAL, CONFIDENTIAL, SECRET	Default: INTERNAL
owner_organization_unit_id	Đơn vị chủ quản	No	Number	Tham chiếu đến đơn vị chịu trách nhiệm chính	Phải tồn tại	FK → Organization Unit.id
is_future	Dữ liệu tương lai	Yes	Boolean	Đánh dấu Data Element là "Dữ liệu tương lai" — chưa có đơn vị nào lưu trữ, nằm trong kế hoạch thu thập (UC-FUTURE-001)	—	Default: false
future_objective	Mục tiêu phát triển	No	Text	Mục tiêu phát triển thành phố liên quan đến Data Element tương lai	Max 1000 ký tự. Bắt buộc khi is_future = true	—
legal_basis	Cơ sở pháp lý	No	Text	Văn bản pháp lý quy định quyền chủ quản	Max 500 ký tự	—
created_at	Ngày tạo	Yes	DateTime	Thời điểm tạo	Auto-generated	Read-only
updated_at	Ngày cập nhật	Yes	DateTime	Thời điểm cập nhật cuối	Auto-generated	Read-only

Thuộc tính mở rộng — 14 thuộc tính nghiệp vụ¶

Bổ sung từ SRS v1.3. Trong tài liệu anh Trân gọi là "term attributes" — ở đây gộp vào Data Element. Giai đoạn hiện tại ghi nhận, triển khai khi mở rộng scope.

#	Field Name	Display Label	Required khi submit	Mô tả
1	ten_nghiep_vu	Tên nghiệp vụ	Có	Tên gọi nghiệp vụ chính thức của Data Element
2	dinh_nghia	Định nghĩa	Có	Định nghĩa nghiệp vụ chi tiết, phân biệt với các khái niệm liên quan
3	don_vi_tao_lap	Đơn vị tạo lập	Có	Đơn vị tạo lập dữ liệu gốc (có thể khác đơn vị chủ quản)
4	don_vi_so_huu	Đơn vị sở hữu	Có (lock)	Từ owner_organization_unit_id — không cho sửa trực tiếp
5	can_cu_phap_ly	Căn cứ pháp lý	Có	Văn bản pháp lý quy định thu thập/quản lý dữ liệu
6	nhom_du_lieu	Nhóm dữ liệu	Có	Phân loại theo nhóm dữ liệu (chủ đề, lĩnh vực)
7	muc_do_nhay_cam	Mức độ nhạy cảm	Có	PUBLIC / INTERNAL / CONFIDENTIAL / SECRET
8	tu_dong_nghia	Từ đồng nghĩa	Không	Các tên gọi khác, từ viết tắt phổ biến
9	vi_du	Ví dụ	Không	Giá trị mẫu minh hoạ
10	ghi_chu	Ghi chú	Không	Thông tin bổ sung
11	pham_vi_ap_dung	Phạm vi áp dụng	Không	Phạm vi áp dụng (toàn TP, một số Sở...)
12	tan_suat_cap_nhat	Tần suất cập nhật	Không	Dữ liệu cập nhật bao lâu một lần
13	nguon_du_lieu	Nguồn dữ liệu	Không	Nguồn gốc dữ liệu (hệ thống nào, quy trình nào)
14	lien_ket_tham_chieu	Liên kết tham chiếu	Không	Tham chiếu đến từ điển quốc gia hoặc Data Element khác

Thuộc tính mở rộng — 11 thuộc tính kỹ thuật¶

Phục vụ cho Discovery, Quality Check, và tích hợp hệ thống. Giai đoạn hiện tại ghi nhận, triển khai khi mở rộng scope.

#	Field Name	Display Label	Mô tả
1	ten_truong_ky_thuat	Tên trường kỹ thuật	Tên cột/field trong CSDL gốc (VD: cccd_so, ho_ten)
2	kieu_du_lieu_ky_thuat	Kiểu dữ liệu kỹ thuật	Kiểu dữ liệu DB (VD: VARCHAR(12), INTEGER, TIMESTAMP)
3	do_dai_toi_da	Độ dài tối đa	Giới hạn ký tự/byte
4	bat_buoc	Bắt buộc (nullable)	Trường có bắt buộc nhập không
5	gia_tri_mac_dinh	Giá trị mặc định	Default value nếu có
6	validation_rules	Quy tắc kiểm tra	Regex, min/max, danh sách giá trị hợp lệ (JSONB)
7	dinh_dang	Định dạng	Format hiển thị (VD: DD/MM/YYYY, ###-###-###)
8	don_vi_do	Đơn vị đo	Đơn vị đo lường nếu là số (VD: VND, m², kg)
9	he_thong_nguon	Hệ thống nguồn	Tên CSDL/hệ thống chứa dữ liệu gốc
10	bang_nguon	Bảng nguồn	Tên bảng trong CSDL gốc
11	lineage_info	Thông tin lineage	Nguồn dữ liệu đến/đi, transformation (JSONB, OpenLineage-compatible)

Enum: Sensitivity Level (Mức độ nhạy cảm)¶

Value	Meaning	Quy tắc hiển thị
PUBLIC	Công khai — ai cũng xem được	Hiển thị cho Staff không cần đăng nhập
INTERNAL	Nội bộ — cần đăng nhập	Hiển thị cho user đã đăng nhập
CONFIDENTIAL	Bảo mật — hạn chế truy cập	Chỉ Manager, Data Owner đơn vị liên quan, Approver
SECRET	Tối mật — kiểm soát chặt	Chỉ Admin và Approver được uỷ quyền

Business Rules¶

Mã tự động sinh theo định dạng [DE{NNN}-DM{N}.{M}] (VD: DE001-DM1.1) — không cho phép chỉnh sửa thủ công sau khi tạo
Quy tắc 1:1: Mỗi Data Element chỉ có tối đa một đơn vị chủ quản (owner_organization_unit_id)
Chủ quản cấp Phòng/Ban: owner_organization_unit_id phải tham chiếu đến đơn vị ở cấp PHONG hoặc sâu hơn trong cây tổ chức (không chỉ cấp Sở). Mã đơn vị theo định dạng IDxx.xx.xx (01=TP, xx=Sở, xx=Phòng)
Data Owner có thể đề xuất Data Element mới trong Sub Domain đã có (trạng thái PENDING → Manager phê duyệt)
owner_organization_unit_id có thể null khi status = DRAFT (chưa gán chủ quản)
owner_organization_unit_id bắt buộc khi status = APPROVED hoặc PUBLISHED
DE không có Sở nào lưu trữ: owner_organization_unit_id = NULL, ghi nhận "Dữ liệu cần xây dựng mới" — DE vẫn tồn tại trong khung Anchored Data nhưng chưa có chủ quản
legal_basis nên được điền khi chuyển sang APPROVED
Không thể xóa Data Element khi status = PUBLISHED

Enum Values¶

Status (Trạng thái vòng đời)¶

Giai đoạn hiện tại — 4 trạng thái:

Value	Meaning	Can Transition To
DRAFT	Đã khai báo, chưa matching	IN_REVIEW
IN_REVIEW	Đang matching và rà soát	APPROVED, DRAFT (nếu Approver từ chối)
APPROVED	Approver đã chốt chủ quản	PUBLISHED
PUBLISHED	Đã ban hành, Staff tra cứu được	(cần quy trình riêng để cập nhật)

Ghi nhận cho giai đoạn sau — 4 trạng thái bổ sung (tham khảo SRS v1.3):

Các trạng thái dưới đây chưa triển khai trong giai đoạn này. Ghi nhận để đảm bảo thiết kế không chặn việc mở rộng.

Value	Meaning	Khi nào cần	Ghi chú
PENDING_DISCOVERY	Lớp 2 (Agent) tự động phát hiện field mới từ CSDL đơn vị	Khi triển khai Discovery tự động (LDOP, Agent cron)	Chưa có chủ quản, chưa có trong Anchored Data
SURVEYED	Seed từ Bảng D — đã có chủ quản, chưa có định nghĩa đầy đủ	Khi triển khai P1 (quản lý nội dung từ điển)	Cầu nối P0→P1: sau khi Approver phê duyệt Bảng D, hệ thống tạo term SURVEYED để Data Owner điền định nghĩa
DEPRECATED	Lỗi thời, giữ tương thích ngược	Khi cần quản lý vòng đời dài hạn	Term vẫn hiển thị nhưng đánh dấu "không còn khuyến nghị sử dụng"
ARCHIVED	Lưu trữ vĩnh viễn, không hiển thị cho tra cứu	Sau DEPRECATED (tự động hoặc thủ công)	Xoá khỏi giao diện tra cứu, giữ trong DB để truy vết

Entity: Organization Unit (Đơn vị tổ chức)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
code	Mã đơn vị	Yes	Text	Mã nghiệp vụ	Format: IDxx.xx.xx (01=TP, xx=Sở, xx=Phòng). VD: ID01.01.01	Unique, Not Null
name	Tên đơn vị	Yes	Text	Tên đầy đủ của Sở/Ban/Ngành/Phòng	Min 2, Max 200 ký tự	Not Null
parent_organization_unit_id	Đơn vị cha	No	Number	Tham chiếu đến đơn vị cấp trên	Phải tồn tại nếu có giá trị	FK → Organization Unit.id (self)
level	Cấp tổ chức	Yes	Enum	Cấp trong cây phân cấp	Values: TINH, SO, BAN, PHONG	Not Null
contact_info	Thông tin liên hệ	No	Text	Địa chỉ, điện thoại	Max 500 ký tự	—
is_active	Trạng thái	Yes	Boolean	Đơn vị đang hoạt động	—	Default: true
created_at	Ngày tạo	Yes	DateTime	Thời điểm tạo	Auto-generated	Read-only
updated_at	Ngày cập nhật	Yes	DateTime	Thời điểm cập nhật cuối	Auto-generated	Read-only

Business Rules¶

Cây tổ chức phân cấp: Tỉnh → Sở/Ban → Phòng
Mã đơn vị IDxx.xx.xx phải duy nhất toàn hệ thống. Có thể cập nhật tên nhưng không đổi mã sau khi đã gán cho Data Element (ownership_plan)
Không thể xóa đơn vị nếu còn user hoặc đang là chủ quản Data Element. Dùng is_active=false để ẩn đơn vị đã giải thể — không xóa vật lý
parent_organization_unit_id = null khi cấp cao nhất (TINH)
Data Element chỉ được gán chủ quản ở cấp PHONG trở xuống — không gán ở cấp TINH hay SO

Enum Values¶

Level (Cấp tổ chức)¶

Value	Meaning
TINH	Cấp Tỉnh/Thành phố
SO	Cấp Sở/Ban/Ngành
BAN	Cấp Ban/Cục trực thuộc
PHONG	Cấp Phòng

Entity: User (Người dùng)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
full_name	Họ và tên	Yes	Text	Tên đầy đủ	Min 2, Max 100 ký tự	Not Null
email	Email	Yes	Email	Email đăng nhập (từ SSO)	Valid email format	Unique, Not Null
organization_unit_id	Đơn vị	Yes	Number	Tham chiếu đến đơn vị trực thuộc	Phải tồn tại	FK → Organization Unit.id
roles	Vai trò	Yes	Enum[]	Danh sách vai trò được gán	Ít nhất 1 vai trò	Not Null
is_active	Trạng thái	Yes	Boolean	Tài khoản đang hoạt động	—	Default: true
last_login	Đăng nhập lần cuối	No	DateTime	Thời điểm đăng nhập cuối	Auto-updated	Read-only
created_at	Ngày tạo	Yes	DateTime	Thời điểm tạo	Auto-generated	Read-only
updated_at	Ngày cập nhật	Yes	DateTime	Thời điểm cập nhật cuối	Auto-generated	Read-only

Business Rules¶

User xác thực qua SSO, hệ thống không lưu mật khẩu
Mỗi user thuộc đúng một đơn vị
Một user có thể có nhiều vai trò (VD: vừa Manager vừa Data Owner)
Admin không thể xóa chính mình

Enum Values¶

Roles (Vai trò)¶

Value	Meaning	Quyền chính
MANAGER	Quản trị dữ liệu kỹ thuật	Thiết lập Anchored Data, Discovery, Matching, đề xuất chủ quản
DATA_OWNER	Quản trị dữ liệu đơn vị	Xem (read-only) và xác nhận/từ chối bản đồ hiện trạng
APPROVER	Người phê duyệt	Chốt chủ quản, ban hành Từ điển Dữ liệu
STAFF	Người tra cứu	Tra cứu Từ điển Dữ liệu (read-only)
ADMIN	Quản trị hệ thống	Quản lý user, phân quyền, cây tổ chức

Entity: Metadata Source (Nguồn metadata)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
organization_unit_id	Đơn vị	Yes	Number	Tham chiếu đến đơn vị cung cấp file	Phải tồn tại	FK → Organization Unit.id
file_name	Tên file	Yes	Text	Tên file gốc đã upload	Max 255 ký tự	Not Null
file_type	Loại file	Yes	Enum	Loại file đã upload	Values: CSV, SQL_DDL, MANUAL	Not Null
upload_date	Ngày upload	Yes	DateTime	Thời điểm upload	Auto-generated	Read-only
uploaded_by_user_id	Người upload	Yes	Number	Tham chiếu đến user đã upload	Phải tồn tại	FK → User.id
field_count	Số field trích xuất	No	Number	Tổng số field đã parse	Auto-calculated	Read-only
parse_status	Trạng thái parse	Yes	Enum	Trạng thái xử lý file	Values: PENDING, PROCESSING, COMPLETED, FAILED	Default: PENDING

Business Rules¶

Chỉ Manager được upload file
Hệ thống tự động parse ngay sau upload (background job cho file lớn)
Khi parse_status = FAILED, Manager có thể upload lại hoặc khai báo thủ công

Enum Values¶

File Type (Loại file)¶

Value	Meaning
CSV	File CSV – parse header row để lấy field names
SQL_DDL	File SQL DDL – parse CREATE TABLE để lấy tên cột, kiểu dữ liệu
MANUAL	Khai báo thủ công – Manager nhập trực tiếp

Parse Status (Trạng thái parse)¶

Value	Meaning	Can Transition To
PENDING	Đang chờ xử lý	PROCESSING
PROCESSING	Đang parse	COMPLETED, FAILED
COMPLETED	Parse thành công	—
FAILED	Parse thất bại	PENDING (retry)

Entity: Extracted Field (Trường dữ liệu đã trích xuất)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
metadata_source_id	Nguồn metadata	Yes	Number	Tham chiếu đến file nguồn	Phải tồn tại	FK → Metadata Source.id
field_name	Tên field	Yes	Text	Tên field gốc từ CSV header hoặc DDL column	Max 255 ký tự	Not Null
field_data_type	Kiểu dữ liệu	No	Text	Kiểu dữ liệu (nếu có từ DDL: VARCHAR, INT...)	Max 100 ký tự	—
table_name	Tên bảng	No	Text	Tên bảng gốc (nếu DDL có nhiều bảng)	Max 255 ký tự	—
matching_status	Trạng thái matching	Yes	Enum	Trạng thái đối chiếu với Anchored Data	Values: PENDING, MATCHED, UNMATCHED, REJECTED	Default: PENDING

Business Rules¶

Được tạo tự động khi parse Metadata Source thành công
matching_status thay đổi sau khi chạy AI matching hoặc Manager rà soát

Enum Values¶

Matching Status (Trạng thái matching)¶

Value	Meaning	Can Transition To
PENDING	Chưa chạy matching	MATCHED, UNMATCHED
MATCHED	Đã match với Data Element (auto hoặc manual)	REJECTED, UNMATCHED
UNMATCHED	Không tìm thấy Data Element tương ứng	MATCHED (nếu Manager chỉnh)
REJECTED	Manager từ chối gợi ý matching của AI	MATCHED, UNMATCHED

Entity: Matching Result (Kết quả đối chiếu)¶

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
extracted_field_id	Field nguồn	Yes	Number	Tham chiếu đến field đã trích xuất	Phải tồn tại	FK → Extracted Field.id
data_element_id	Data Element đích	Yes	Number	Tham chiếu đến Data Element trong Anchored Data	Phải tồn tại	FK → Data Element.id
confident_score	Điểm tin cậy	Yes	Number	Điểm tin cậy của matching (0.0 – 1.0)	Min: 0.0, Max: 1.0	Not Null
match_method	Phương pháp matching	Yes	Enum	Cách thức matching	Values: AUTO_RULE, AUTO_AI, MANUAL	Not Null
match_status	Trạng thái xác nhận	Yes	Enum	Manager đã xác nhận chưa	Values: SUGGESTED, ACCEPTED, REJECTED	Default: SUGGESTED
matched_at	Thời điểm matching	Yes	DateTime	Khi nào matching được tạo	Auto-generated	Read-only
reviewed_by_user_id	Người rà soát	No	Number	Tham chiếu đến Manager đã rà soát	Phải tồn tại nếu có	FK → User.id
reviewed_at	Thời điểm rà soát	No	DateTime	Khi nào Manager rà soát	—	—

Business Rules¶

Giai đoạn hiện tại: Tất cả match_status khởi tạo là SUGGESTED bất kể confident_score. Manager rà soát toàn bộ (không auto-accept — xem ASM-INT-012)
Giai đoạn sau (khi enable auto-accept): confident_score >= threshold → match_status có thể tự động chuyển ACCEPTED (cấu hình, mặc định tắt)
Khi confident_score < threshold → match_status giữ SUGGESTED, chờ Manager rà soát
Threshold value là cấu hình hệ thống (TBD — xem ASM-INT-009)
Một Extracted Field có thể có nhiều Matching Result (top-N gợi ý), nhưng chỉ 1 được ACCEPTED

Enum Values¶

Match Method (Phương pháp matching)¶

Value	Meaning
AUTO_RULE	Rule-based matching (tên trường, kiểu dữ liệu)
AUTO_AI	AI matching (ngữ nghĩa, pattern recognition)
MANUAL	Manager matching thủ công

Match Status (Trạng thái xác nhận)¶

Value	Meaning	Can Transition To
SUGGESTED	AI/Rule gợi ý, chưa xác nhận	ACCEPTED, REJECTED
ACCEPTED	Manager đã chấp nhận	REJECTED
REJECTED	Manager đã từ chối	ACCEPTED (nếu xem lại)

Entity: Source Mapping (Ô Bản đồ Hiện trạng — Bảng C)¶

Entity mới bổ sung theo GAP 5 — mỗi record đại diện cho một ô trong ma trận Data Element × Đơn vị (Bảng C).

Field Specifications¶

Field Name	Display Label	Required	Data Type	Description	Validation Rules	Constraints
id	ID	Yes	Number	Định danh duy nhất	Auto-generated	PK
data_element_id	Data Element	Yes	Number	Tham chiếu đến Data Element (hàng)	Phải tồn tại	FK → Data Element.id
organization_unit_id	Đơn vị	Yes	Number	Tham chiếu đến đơn vị Sở/Ban/Ngành (cột)	Phải tồn tại	FK → Organization Unit.id
current_state	Trạng thái ô	Yes	Enum	Trạng thái hiện tại của ô Bảng C	Values: DATABASE, DATABASE_OVERLAP, FRAGMENTED, READY, EMPTY, DISPUTED, CONFIRMED, REJECTED	Default: EMPTY
dispute_note	Ghi chú tranh chấp	No	Text	Lý do đánh dấu DISPUTED	Min 20 ký tự (bắt buộc khi DISPUTED)	—
disputed_by	Người đánh dấu	No	Number	User đánh dấu DISPUTED	Phải tồn tại nếu có	FK → User.id
disputed_at	Thời điểm đánh dấu	No	DateTime	Khi nào đánh dấu DISPUTED	—	—
resolved_by	Người giải quyết	No	Number	Approver giải quyết DISPUTED	Phải tồn tại nếu có	FK → User.id
resolved_at	Thời điểm giải quyết	No	DateTime	Khi nào giải quyết DISPUTED	—	—
confirmed_by	Người xác nhận	No	Number	Data Owner xác nhận ô	Phải tồn tại nếu có	FK → User.id
confirmed_at	Thời điểm xác nhận	No	DateTime	Khi nào xác nhận	—	—

Business Rules¶

Mỗi cặp (data_element_id, organization_unit_id) là duy nhất — một ô cho mỗi DE × Đơn vị
Đánh dấu DISPUTED bắt buộc ghi dispute_note ≥ 20 ký tự
Data Owner chỉ đánh dấu DISPUTED ô thuộc đơn vị mình (unit-scoped)
Chỉ Approver mới giải quyết được DISPUTED
Guard cứng: Không thể phê duyệt Bảng D (quy hoạch chủ quản) khi còn ô DISPUTED

Enum Values¶

Current State (Trạng thái ô Bảng C)¶

Value	Meaning	Ai set	Can Transition To
DATABASE	Có trong CSDL cấu trúc	Discovery tự động / khai báo	DISPUTED, CONFIRMED
DATABASE_OVERLAP	Cùng DE lưu ở nhiều bảng/CSDL trong cùng đơn vị	Discovery tự động	DISPUTED, CONFIRMED
FRAGMENTED	Dữ liệu rải rác, chưa cấu trúc	Sở khai báo	DISPUTED, CONFIRMED
READY	Có CSDL + API, sẵn sàng kết nối	Sở khai báo	DISPUTED, CONFIRMED
EMPTY	Sở không có DE này	Discovery / Sở xác nhận	—
DISPUTED	Sở không đồng ý với gợi ý mapping	Data Owner / Manager	CONFIRMED, REJECTED, DATABASE
CONFIRMED	Đã xác nhận đúng	Sở xác nhận / Approver	—
REJECTED	Bác bỏ ánh xạ (Approver quyết định)	Approver	—

5. Quan Hệ Giữa Các Entity¶

Quan hệ	Entity A	Entity B	Loại	Mô tả
Domain chứa Sub Domain	Domain	Sub Domain	1:N	Mỗi Domain có nhiều Sub Domain
Sub Domain chứa Data Element	Sub Domain	Data Element	1:N	Mỗi Sub Domain có nhiều Data Element
Data Element có chủ quản	Data Element	Organization Unit	N:1 (quy tắc 1:1)	Mỗi DE chỉ có tối đa 1 đơn vị chủ quản
Đơn vị lưu trữ DE	Organization Unit	Data Element	N:N	Nhiều đơn vị có thể lưu trữ cùng 1 DE (chồng chéo) — thể hiện qua Source Mapping
Ô Bảng C (hàng)	Data Element	Source Mapping	1:N	Mỗi DE có nhiều ô (một per đơn vị)
Ô Bảng C (cột)	Organization Unit	Source Mapping	1:N	Mỗi đơn vị có nhiều ô (một per DE)
Đơn vị có user	Organization Unit	User	1:N	Mỗi user thuộc 1 đơn vị
Đơn vị cung cấp file	Organization Unit	Metadata Source	1:N	Mỗi đơn vị có thể upload nhiều file
File trích xuất field	Metadata Source	Extracted Field	1:N	Mỗi file parse ra nhiều field
Field match với DE	Extracted Field	Data Element	N:1 (via Matching Result)	Mỗi field có thể match với 1 DE
Cây tổ chức	Organization Unit	Organization Unit	Self-reference	parent_organization_unit_id → cấu trúc phân cấp

6. Ghi Chú¶

Cơ sở pháp lý (legal_basis) trên Data Element: thông tin từ mockup Phụ lục D, ghi nhận văn bản pháp lý quy định quyền chủ quản (VD: "Luật Căn cước công dân 2014" cho Số CCCD).
Matching threshold: Giá trị ngưỡng confident score chưa được chốt — cần xác định ở giai đoạn thiết kế kỹ thuật.
Audit log: Mọi thay đổi trên Data Element (status, owner_organization_unit_id) cần ghi lại lịch sử. Chi tiết audit log sẽ được định nghĩa ở giai đoạn thiết kế kỹ thuật.
Dữ liệu Tương lai: Không tạo entity riêng — sử dụng flag is_future trên Data Element để đánh dấu. Manager tạo (UC-FUTURE-001), Approver phê duyệt. Khi is_future = true, owner_organization_unit_id có thể NULL và future_objective bắt buộc nhập.