Sale Schema

Schema sale chứa 2 model quản lý vòng đời đơn hàng bán. Đơn hàng tiến triển qua một máy trạng thái xác định từ bản nháp đến hoàn thành hoặc hủy bỏ.

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

Tổng quan Model

Model	Tên Bảng	Mô tả
SaleOrder	sale.SaleOrder	Đơn hàng bán với vòng đời trạng thái và tổng giá
SaleOrderItem	sale.SaleOrderItem	Mục hàng trong đơn hàng bán

SaleOrder

Vòng đời Trạng thái

Giá trị Trạng thái (từ SaleOrderStatuses):

Trạng thái	Giá trị	Kết thúc	Sửa đổi Mục	Thanh toán	Hủy
DRAFT	001_DRAFT	Không	Có	Có	Có
PROCESSING	203_PROCESSING	Không	Không	Không	Có
PARTIAL	300_PARTIAL	Không	Không	Không	Có
COMPLETED	303_COMPLETED	Có	Không	Không	Không
CANCELLED	505_CANCELLED	Có	Không	Không	Không

Các phương thức helper trên SaleOrderStatuses:

• isValid(status) -- kiểm tra trạng thái có trong tập hợp hợp lệ
• isTerminal(status) -- trả về true cho COMPLETED hoặc CANCELLED
• canModifyItems(status) -- trả về true chỉ cho DRAFT
• canCheckout(status) -- trả về true chỉ cho DRAFT
• canRevertToCart(status) -- trả về true chỉ cho PROCESSING
• canCancel(status) -- trả về true cho bất kỳ trạng thái đang hoạt động (DRAFT, PROCESSING, PARTIAL)

Các Cột

Cột	Kiểu	Ràng buộc	Mô tả
order_number	text	NOT NULL, UNIQUE	Số đơn hàng duy nhất tự động tạo
name	text		Tên đơn hàng
slug	text	UNIQUE	Định danh thân thiện URL
validity	jsonb		{ from: string, to: string } thời hạn hiệu lực
status	text	NOT NULL, DEFAULT 001_DRAFT, indexed	Trạng thái đơn hàng
draft_at	timestamptz		Thời gian đơn hàng vào trạng thái DRAFT
processing_at	timestamptz		Thời gian đơn hàng vào trạng thái PROCESSING
partial_at	timestamptz		Thời gian đơn hàng vào trạng thái PARTIAL
completed_at	timestamptz		Thời gian đơn hàng COMPLETED
cancelled_at	timestamptz		Thời gian đơn hàng CANCELLED
cancellation_reason	text		Lý do hủy
merchant_id	text	NOT NULL, indexed	FK đến Merchant
sale_channel_id	text	NOT NULL, indexed	FK đến SaleChannel
currency	text	NOT NULL, DEFAULT 'VND'	Mã tiền tệ
exchange_rate	decimal(12,6)	DEFAULT '1'	Tỷ giá hối đoái
subtotal	decimal(15,4)	NOT NULL, DEFAULT '0'	Tổng phụ trước thuế/giảm giá
tax	decimal(15,4)	NOT NULL, DEFAULT '0'	Tổng số tiền thuế
discount	decimal(15,4)	NOT NULL, DEFAULT '0'	Tổng số tiền giảm giá
total	decimal(15,4)	NOT NULL, DEFAULT '0'	Tổng cuối cùng
counter	jsonb		Bộ đếm thanh toán { paid: number, paidItemIds: string[], total: number }
metadata	jsonb		Kiểu TSaleOrderMetadata
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			id, createdAt, modifiedAt, deletedAt

TSaleOrderMetadata

type TSaleOrderMetadata = {
  note?: string;
  merchantId: string;
  finance:
    | { use: false }
    | {
        use: true;
        walletId: string;
        categoryId: string;
      };
};

Trường finance kiểm soát việc giao dịch tài chính có được tự động tạo khi đơn hàng hoàn thành hay không:

• { use: false } -- không tích hợp tài chính
• { use: true, walletId, categoryId } -- tự động tạo giao dịch thu nhập trong ví và danh mục được chỉ định

Quan hệ

Quan hệ	Kiểu	Đích	Mô tả
creator	Một	User	Người dùng tạo
modifier	Một	User	Người dùng sửa đổi cuối
saleChannel	Một	SaleChannel	Kênh bán hàng liên kết
items	Nhiều	SaleOrderItem	Các mục hàng trong đơn hàng

SaleOrderItem

Chế độ Mục

Chế độ	Giá trị	Mô tả
PRODUCT	000_PRODUCT	Mục sản phẩm tiêu chuẩn liên kết với ProductVariant
CUSTOM	100_CUSTOM	Mục tùy chỉnh/thủ công không liên kết sản phẩm

Các Cột

Cột	Kiểu	Ràng buộc	Mô tả
sale_order_id	text	NOT NULL, indexed, FK	FK đến SaleOrder
mode	text	NOT NULL, DEFAULT 000_PRODUCT	Chế độ mục (PRODUCT hoặc CUSTOM)
lead_item_id	text		Mục dẫn đầu cho mục nhóm/addon
item_type	text		Loại thực thể đa hình (mặc định: ProductVariant)
item_id	text		ID thực thể đa hình
currency	text	NOT NULL, DEFAULT 'VND'	Mã tiền tệ
base_price	decimal(15,4)	NOT NULL, DEFAULT '0'	Giá gốc cơ bản
unit_price	decimal(15,4)	NOT NULL, DEFAULT '0'	Giá mỗi đơn vị (sau điều chỉnh)
discount	decimal(15,4)	NOT NULL, DEFAULT '0'	Số tiền giảm giá
quantity	decimal(15,4)	NOT NULL, DEFAULT '1'	Số lượng
tax	decimal(15,4)	NOT NULL, DEFAULT '0'	Số tiền thuế
total	decimal(15,4)	NOT NULL, GENERATED	Tính toán: (unit_price * quantity + tax)
fare_id	text		Tham chiếu đến Fare sử dụng cho định giá
fare_provider	text		Nhà cung cấp cung cấp giá vé
price_metadata	jsonb		TPriceMetadata với chi tiết nguồn giá vé
metadata	jsonb		TProductMetadata với snapshot sản phẩm
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			id, createdAt, modifiedAt, deletedAt

Chỉ mục: (saleOrderId), (itemType, itemId)

Khóa ngoại: saleOrderId tham chiếu SaleOrder.id

TProductMetadata

Snapshot sản phẩm được lưu tại thời điểm bán:

type TProductMetadata = {
  name: { default: string; vi?: string; en?: string };
  description?: string;
  sku?: string;
  barcode?: string;
  imageUrl?: string;
  category?: string;
  subcategory?: string;
  brand?: string;
  attributes?: Record<string, string | number | boolean>;
  taxRate?: number;
  externalId?: string;
  externalSource?: string;
  customData?: Record<string, unknown>;
};

TFareSource (Union Phân biệt)

Theo dõi cách xác định giá:

// Manual pricing (operator-entered)
type TFareSourceManual = {
  type: 'MANUAL';
  unitPrice: number;
  basePrice: number;
  tax: { mode: 'AMOUNT'; value: number } | { mode: 'PERCENTAGE'; value: number };
};

// System pricing (from fare engine)
type TFareSourceSystem = {
  type: 'SYSTEM';
  fareId: string;
  unitPrice: number;
  basePrice: number;
  originalPrice?: number;
  provider?: string;
  appliedRules?: Array<{ fareRuleId: string; code: string }>;
  validUntil?: string;
  metadata?: Record<string, unknown>;
};

type TFareSource = TFareSourceManual | TFareSourceSystem;

Quan hệ Thực thể

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
• Public Schema -- 30 model trong public schema
• Pricing Schema -- 7 model định giá
• Allocation Schema -- 4 model phân bổ
• 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
• Gói Sale -- Dịch vụ đơn hàng bán, thanh toán và tích hợp payment