Public Schema

Schema public chứa 30 model bao gồm miền kinh doanh chính. Các model được định nghĩa sử dụng pgTable() từ Drizzle ORM và sử dụng generateCommonColumnDefs() chung cho các cột id, createdAt, modifiedAt, deletedAt, và metadata.

Nguồn: packages/core/src/models/schemas/public/

Quản lý Người dùng

Sơ đồ quan hệ thực thể sau đây thể hiện các liên kết giữa các model liên quan đến người dùng và phân quyền:

User

Thực thể người dùng chính đại diện cho tất cả người dùng hệ thống.

Cột	Kiểu	Ràng buộc	Mô tả
id	text	PK	Snowflake ID
realm	text	DEFAULT ''	Realm/tenant người dùng
status	text	NOT NULL	Trạng thái người dùng (từ CommonStatuses)
type	text	NOT NULL	Loại người dùng (SYSTEM, LINKED)
activated_at	timestamptz		Thời gian kích hoạt tài khoản
last_login_at	timestamptz		Thời gian đăng nhập lần cuối
parent_id	text		Tham chiếu người dùng cha
+ các cột chung			createdAt, modifiedAt, deletedAt, metadata

Sử dụng extraUserColumns({ idType: 'string' }) từ IGNIS.

UserProfile

Thông tin người dùng mở rộng (quan hệ một-một với User).

Cột	Kiểu	Ràng buộc	Mô tả
emails	text[]	DEFAULT '{}'	Mảng địa chỉ email
phones	text[]	DEFAULT '{}'	Mảng số điện thoại
first_name	text		Tên
last_name	text		Họ
birthday	isoTimestamp		Ngày sinh (chuỗi ISO 8601)
locale	text	DEFAULT 'en-US'	Tùy chọn ngôn ngữ
user_id	text	NOT NULL	FK đến User
+ các cột chung

UserIdentifier

Nhiều phương thức định danh cho người dùng.

Cột	Kiểu	Ràng buộc	Mô tả
scheme	text	NOT NULL	Loại định danh (USERNAME, EMAIL, PHONE_NUMBER, USER_NUMBER, NX_AUTH)
identifier	text	NOT NULL	Giá trị định danh
verified	boolean	NOT NULL, DEFAULT false	Trạng thái xác minh
user_id	text	NOT NULL	FK đến User
+ các cột chung

Ràng buộc duy nhất: (scheme, identifier)

UserCredential

Thông tin xác thực (mật khẩu, token OAuth).

Cột	Kiểu	Ràng buộc	Mô tả
scheme	text	NOT NULL	Loại thông tin xác thực (BASIC, TWO_FA, OAUTH, OAUTH2)
credential	text	NOT NULL	Giá trị thông tin xác thực đã băm
user_id	text	NOT NULL	FK đến User
+ các cột chung

UserConfiguration

Cài đặt cấu hình theo từng người dùng sử dụng mẫu cột kiểu dữ liệu.

Cột	Kiểu	Ràng buộc	Mô tả
name	text		Tên cấu hình
code	text	NOT NULL	Mã cấu hình (ví dụ: PREFERENCES)
description	text		Mô tả
group	text	NOT NULL	Nhóm cấu hình
user_id	text	NOT NULL	FK đến User
+ các cột kiểu dữ liệu			dataType, tValue, nValue, boValue, bValue, jValue
+ các cột chung

UserMapping

Ánh xạ người dùng đến tổ chức và merchant sử dụng tham chiếu đa hình.

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID đích đa hình (ví dụ: ID tổ chức hoặc merchant)
principal_type	text		Loại đích đa hình (ví dụ: Organizer, Merchant)
user_id	text	NOT NULL	FK đến User
+ các cột chung

UserRole

Liên kết người dùng với vai trò sử dụng phạm vi đa hình.

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID phạm vi (ví dụ: ID tổ chức cho vai trò có phạm vi)
principal_type	text		Loại phạm vi
user_id	text	NOT NULL	FK đến User
+ các cột chung

Phân quyền

Role

Định nghĩa vai trò cho RBAC với hỗ trợ đa ngôn ngữ.

Cột	Kiểu	Ràng buộc	Mô tả
identifier	text	NOT NULL, UNIQUE	Mã vai trò (ví dụ: 999-super-admin)
priority	integer	NOT NULL	Mức độ ưu tiên (cao hơn = đặc quyền hơn)
status	text	NOT NULL	Trạng thái vai trò
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
+ các cột chung

Sử dụng extraRoleColumns() từ IGNIS. Các vai trò được định nghĩa sẵn:

Vai trò	Định danh	Ưu tiên
Super Admin	999-super-admin	999
Admin	998-admin	998
Operator	997-operator	997
Organizer Owner	899-organizer-owner	899
Employee	898-employee	898

Permission

Định nghĩa quyền cho kiểm soát truy cập.

Cột	Kiểu	Ràng buộc	Mô tả
code	text	NOT NULL, UNIQUE	Mã quyền
name	text	NOT NULL	Tên quyền
subject	text	NOT NULL	Chủ thể tài nguyên
p_type	text	NOT NULL	Loại quyền
action	text	NOT NULL	Hành động được phép
scope	text	NOT NULL	Phạm vi quyền
parent_id	text		FK quyền cha
+ các cột chung

Sử dụng extraPermissionColumns({ idType: 'string' }) từ IGNIS.

PermissionMapping

Ánh xạ quyền đến vai trò (bảng nối nhiều-nhiều).

Cột	Kiểu	Ràng buộc	Mô tả
+ các cột ánh xạ quyền			Từ extraPermissionMappingColumns({ idType: 'string' })
+ các cột chung

Tổ chức

Sơ đồ quan hệ thực thể sau đây thể hiện các liên kết giữa các model tổ chức và sản phẩm:

Organizer

Thực thể tổ chức kinh doanh cấp cao nhất với thông tin pháp lý, liên hệ, và vị trí.

Cột	Kiểu	Ràng buộc	Mô tả
slug	text	NOT NULL, UNIQUE	Định danh thân thiện URL
status	text	NOT NULL, DEFAULT ACTIVATED	Trạng thái tổ chức
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: O_20260216_...)
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
tax_number	text		Mã số thuế
registration_number	text		Số đăng ký kinh doanh
registration_type	text		Loại đăng ký (VN_HOUSEHOLD_BUSINESS, VN_PRIVATE_ENTERPRISE, v.v.)
registration_date	isoTimestamp		Ngày đăng ký
license_number	text		Số giấy phép kinh doanh
vat_number	text		Số VAT
contact_name	text		Tên liên hệ chính
contact_phone	text		Điện thoại liên hệ
contact_email	text		Email liên hệ
website	text		URL trang web
location	jsonb (ILocation)		Địa chỉ vật lý và tọa độ
social	jsonb (ISocial)		Liên kết mạng xã hội
parent_id	text		FK tổ chức cha
created_by	text		ID người dùng tạo
modified_by	text		ID người dùng sửa đổi cuối
+ các cột chung

Merchant

Thực thể cửa hàng/chi nhánh thuộc một tổ chức.

Cột	Kiểu	Ràng buộc	Mô tả
slug	text	NOT NULL	Định danh thân thiện URL (duy nhất theo tổ chức)
status	text	NOT NULL, DEFAULT ACTIVATED	Trạng thái merchant
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: M_20260216_...)
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
currency	text	NOT NULL	Mã tiền tệ (ví dụ: VND)
type	text	NOT NULL	Loại merchant (DEFAULT, TICKET, FNB, THEATER)
date_from	isoTimestamp		Ngày bắt đầu hoạt động
date_to	isoTimestamp		Ngày kết thúc hoạt động
location	jsonb (ILocation)		Địa chỉ vật lý và tọa độ
parent_id	text		FK merchant cha
organizer_id	text	NOT NULL	FK đến Organizer
+ các cột chung

Ràng buộc duy nhất: (slug, organizer_id)

MerchantIdentifier

Định danh bên ngoài cho merchant (ví dụ: ID merchant của nhà cung cấp thanh toán).

Cột	Kiểu	Ràng buộc	Mô tả
scheme	text	NOT NULL	Lược đồ định danh (SYSTEM, SLUG, VNPAY_QR_MMS, VNPAY_PHONE_POS, VNPAY_SMART_POS)
identifier	text	NOT NULL	Giá trị định danh
merchant_id	text	NOT NULL	FK đến Merchant
+ các cột chung

Ràng buộc duy nhất: (scheme, identifier)

Sản phẩm

Product

Thực thể sản phẩm chính.

Cột	Kiểu	Ràng buộc	Mô tả
slug	text	NOT NULL	Định danh thân thiện URL (duy nhất theo merchant)
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: P_20260216_...)
status	text	NOT NULL, DEFAULT ACTIVATED	Trạng thái sản phẩm
merchant_id	text	NOT NULL	FK đến Merchant
category_id	text		FK đến Category
parent_id	text		FK sản phẩm cha
+ các cột chung

Ràng buộc duy nhất: (slug, merchant_id)

ProductInfo

Chi tiết sản phẩm mở rộng sử dụng mẫu tham chiếu đa hình.

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID chủ sở hữu đa hình (Product hoặc ProductVariant ID)
principal_type	text		Loại chủ sở hữu đa hình
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
+ các cột chung

ProductIdentifier

Nhiều lược đồ định danh cho sản phẩm (SKU, mã vạch, mã QR).

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID chủ sở hữu đa hình
principal_type	text		Loại chủ sở hữu đa hình
scheme	text	NOT NULL	Lược đồ (SYSTEM, SLUG, SKU, BARCODE, QRCODE)
identifier	text	NOT NULL	Giá trị định danh
+ các cột chung

Ràng buộc duy nhất: (scheme, identifier)

ProductVariant

Các biến thể sản phẩm với hỗ trợ tính giá vốn và phân bổ.

Cột	Kiểu	Ràng buộc	Mô tả
slug	text	NOT NULL	Định danh thân thiện URL
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: PV_20260216_...)
status	text	NOT NULL, DEFAULT NEW	Trạng thái biến thể (NEW, ACTIVATED, DEACTIVATED, ARCHIVED)
date_from	isoTimestamp		Ngày bắt đầu khả dụng
date_to	isoTimestamp		Ngày kết thúc khả dụng
cost	decimal(15,4)		Giá vốn đơn vị
costing_methods	text	DEFAULT TIME_BASED	Phương pháp tính giá vốn (TIME_BASED, FIFO, LIFO, AVERAGE)
product_id	text	NOT NULL	FK đến Product
allocation_plan_id	text		FK đến AllocationPlan
allocation_layout_id	text		FK đến AllocationLayout
allocation_zone_id	text		FK đến AllocationZone
allocation_unit_id	text		FK đến AllocationUnit
+ các cột chung

ProductVariantMapping

Ánh xạ biến thể sản phẩm đến các thuộc tính biến thể sử dụng tham chiếu đa hình.

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID đa hình
principal_type	text		Loại đa hình
product_variant_id	text	NOT NULL	FK đến ProductVariant
+ các cột chung

Variant

Định nghĩa thuộc tính biến thể (ví dụ: Kích thước, Màu sắc).

Cột	Kiểu	Ràng buộc	Mô tả
principal_type	text		Loại chủ sở hữu
principal_id	text		ID chủ sở hữu
code	text	NOT NULL	Mã biến thể
+ các cột kiểu dữ liệu			dataType, tValue, nValue, boValue, bValue, jValue
+ các cột chung

Category

Phân loại sản phẩm với hỗ trợ đa ngôn ngữ.

Cột	Kiểu	Ràng buộc	Mô tả
status	text	NOT NULL, DEFAULT UNKNOWN	Trạng thái danh mục
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
is_addon	boolean	NOT NULL, DEFAULT false	Có phải danh mục addon hay không
merchant_id	text	NOT NULL	FK đến Merchant
+ các cột chung

Thương mại

Sơ đồ quan hệ thực thể sau đây thể hiện các liên kết giữa các model thương mại và hệ thống:

SaleChannel

Kênh bán hàng để phân phối sản phẩm.

Cột	Kiểu	Ràng buộc	Mô tả
slug	text	NOT NULL	Định danh thân thiện URL (duy nhất theo merchant)
status	text	NOT NULL, DEFAULT ACTIVATED	Trạng thái kênh
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: S_20260216_...)
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
merchant_id	text	NOT NULL	FK đến Merchant
parent_id	text		FK kênh cha
+ các cột chung

Ràng buộc duy nhất: (slug, merchant_id)

SaleChannelProduct

Bảng nối liên kết sản phẩm với kênh bán hàng.

Cột	Kiểu	Ràng buộc	Mô tả
product_id	text	NOT NULL	FK đến Product
sale_channel_id	text	NOT NULL	FK đến SaleChannel
+ các cột chung

Quota

Giới hạn số lượng cho chiến dịch.

Cột	Kiểu	Ràng buộc	Mô tả
quantity	integer	NOT NULL	Số lượng có sẵn
status	text	NOT NULL, DEFAULT UNKNOWN	Trạng thái quota
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
campaign_id	text	NOT NULL	FK đến Campaign
+ các cột chung

Campaign

Các chiến dịch khuyến mãi.

Cột	Kiểu	Ràng buộc	Mô tả
status	text	NOT NULL, DEFAULT UNKNOWN	Trạng thái chiến dịch
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
date_from	timestamptz		Ngày bắt đầu chiến dịch
date_to	timestamptz		Ngày kết thúc chiến dịch
merchant_id	text	NOT NULL	FK đến Merchant
+ các cột chung

Hệ thống

Configuration

Cấu hình hệ thống và tích hợp với hỗ trợ thông tin xác thực mã hóa.

Cột	Kiểu	Ràng buộc	Mô tả
code	text	NOT NULL	Mã cấu hình
name	text		Tên cấu hình
description	text		Mô tả
group	text	NOT NULL	Nhóm (SYSTEM, TABLE, INTEGRATION)
status	text	DEFAULT ACTIVATED	Trạng thái cấu hình
environment	text		Ngữ cảnh môi trường
credential	text		Thông tin xác thực mã hóa (ẩn, không bao giờ trả về)
principalId	text		ID thực thể chủ sở hữu
principalType	text		Loại thực thể chủ sở hữu
created_by	text		ID người dùng tạo
modified_by	text		ID người dùng sửa đổi cuối
+ các cột kiểu dữ liệu			dataType, tValue, nValue, boValue, bValue, jValue
+ các cột chung

Ràng buộc duy nhất: (group, code, principalId, principalType, environment, deletedAt)

Chỉ mục: (group, code, environment), (group, principalType), GIN trên metadata

Settings

Cài đặt khóa-giá trị sử dụng quyền sở hữu đa hình và lưu trữ kiểu dữ liệu.

Cột	Kiểu	Ràng buộc	Mô tả
principal_id	text		ID thực thể chủ sở hữu
principal_type	text		Loại thực thể chủ sở hữu
created_by	text		Người tạo
modified_by	text		Người sửa đổi cuối
+ các cột kiểu dữ liệu			dataType, tValue, nValue, boValue, bValue, jValue
+ các cột chung

Ràng buộc duy nhất: (principalId, principalType, deletedAt)

Device

Thiết bị POS và đầu cuối với thông tin phần cứng/phần mềm.

Cột	Kiểu	Ràng buộc	Mô tả
status	text	NOT NULL, DEFAULT NEW	Trạng thái thiết bị (NEW, ACTIVATED, DEACTIVATED, SUSPENDED, ARCHIVED)
name	jsonb (i18n)	NOT NULL	Tên đa ngôn ngữ
description	jsonb (i18n)		Mô tả đa ngôn ngữ
identifier	text	NOT NULL, UNIQUE	Tự động tạo (ví dụ: D_20260216_...)
code	text	UNIQUE	Mã ngắn
type	text	NOT NULL	Loại thiết bị (POS_TERMINAL, MOBILE_POS, TABLET, BARCODE_SCANNER, v.v.)
location	jsonb (ILocation)		Vị trí vật lý
organizer_id	text	NOT NULL	FK đến Organizer
merchant_id	text		FK đến Merchant
hardware_info	jsonb		IDeviceHardwareInfo (nhà sản xuất, model, serialNumber, v.v.)
software_info	jsonb		IDeviceSoftwareInfo (os, osVersion, appVersion, v.v.)
last_activity_at	isoTimestamp		Thời gian hoạt động cuối
activated_at	isoTimestamp		Thời gian kích hoạt
deactivated_at	isoTimestamp		Thời gian vô hiệu hóa
pin	text		Mã PIN thiết bị
purchase_date	isoTimestamp		Ngày mua
warranty_expires_at	isoTimestamp		Ngày hết bảo hành
last_maintenance_at	isoTimestamp		Bảo trì lần cuối
next_maintenance_at	isoTimestamp		Bảo trì dự kiến tiếp theo
maintenance_notes	text		Ghi chú bảo trì
vendor	text		Nhà cung cấp thiết bị
+ các cột chung

MetaLink

Metadata tệp/phương tiện cho tài sản lưu trữ trong Minio hoặc đĩa cục bộ.

Cột	Kiểu	Ràng buộc	Mô tả
id	text	PK	Snowflake ID
bucket_name	text	NOT NULL, indexed	Bucket lưu trữ
object_name	text	NOT NULL, indexed	Tên đối tượng trong lưu trữ
link	text	NOT NULL	URL truy cập (presigned)
mimetype	text	NOT NULL	Loại MIME
size	integer	NOT NULL	Kích thước tệp tính bằng byte
etag	text		Thẻ thực thể
metadata	jsonb		Metadata bổ sung
storage_type	text	NOT NULL, indexed	Loại lưu trữ (minio, disk)
is_synced	boolean	NOT NULL, DEFAULT false, indexed	Trạng thái đồng bộ
principal_type	text		Loại thực thể chủ sở hữu
principal_id	text		ID thực thể chủ sở hữu
created_at	timestamptz		Thời gian tạo
modified_at	timestamptz		Thời gian sửa đổi cuối

Lưu ý: MetaLink sử dụng generateIdColumnDefs + generateTzColumnDefs trực tiếp (không có deletedAt).

Migration

Theo dõi việc thực thi migration dữ liệu mẫu.

Cột	Kiểu	Ràng buộc	Mô tả
id	text/serial	PK	Tự động tăng hoặc ID được tạo
name	text	NOT NULL	Tên migration
status	text	NOT NULL	Trạng thái migration (từ MigrationStatuses)
created_at	timestamptz		Thời gian thực thi
modified_at	timestamptz		Cập nhật lần cuối

Lưu ý: Sử dụng generateIdColumnDefs() (không có tùy chọn string) và generateTzColumnDefs().

EmailVerification

Mã và token xác minh email với giới hạn tần suất.

Cột	Kiểu	Ràng buộc	Mô tả
verification_code	varchar	NOT NULL, indexed	Mã xác minh 6 chữ số
code_generated_at	timestamptz	NOT NULL	Thời gian tạo mã
code_expires_at	timestamptz	NOT NULL, indexed	Hết hạn mã (10 phút)
code_attempts	integer	NOT NULL, DEFAULT 0	Số lần thử thất bại (tối đa 3)
verification_token	varchar	NOT NULL, indexed	Token xác minh 32 byte
token_generated_at	timestamptz	NOT NULL	Thời gian tạo token
token_expires_at	timestamptz	NOT NULL, indexed	Hết hạn token (24 giờ)
last_code_sent_at	timestamptz	NOT NULL	Thời gian gửi mã lần cuối
resend_count	integer	NOT NULL, DEFAULT 0	Số lần gửi lại (tối đa 5/ngày)
daily_resend_reset_at	timestamptz	NOT NULL	Thời gian đặt lại hàng ngày
locked_until	timestamptz		Hết hạn khóa tài khoản (15 phút)
is_verified	boolean	NOT NULL, DEFAULT false	Trạng thái xác minh
verified_at	timestamptz		Thời gian xác minh
verification_method	varchar		Phương thức sử dụng (code hoặc token)
verification_ip	varchar		Địa chỉ IP sử dụng
user_identifier_id	text	NOT NULL, indexed	FK đến UserIdentifier
+ các cột chung

Định danh Tự động Tạo

Hầu hết các thực thể sử dụng định danh tự động tạo với định dạng {PREFIX}_{YYYYMMDD}_{SNOWFLAKE_ID}:

Thực thể	Tiền tố	Ví dụ
Organizer	O_	O_20260216_1234567890
Merchant	M_	M_20260216_1234567890
Product	P_	P_20260216_1234567890
ProductVariant	PV_	PV_20260216_1234567890
SaleChannel	S_	S_20260216_1234567890
Device	D_	D_20260216_1234567890

Tài liệu Liên quan

• Tổng quan Cơ sở dữ liệu -- Tóm tắt schema, cột chung, kiểu chia sẻ
• Sơ đồ Quan hệ Thực thể -- ERD toàn diện cho tất cả 55 model
• Pricing Schema -- 7 model định giá
• Allocation Schema -- 4 model phân bổ
• Sale Schema -- 2 model đơn hàng bán
• Inventory Schema -- 8 model tồn kho
• Finance Schema -- 3 model tài chính
• Payment Schema -- 1 model cấu hình webhook
• Migration -- DDL migration và framework dữ liệu mẫu