ADR-0001. InventoryItem đa hình (itemType + itemId)

Trường	Giá trị
Trạng thái	Accepted
Ngày	2026-01-15
Người quyết định	Phat Nguyen
Thay thế	-

Bối cảnh

• BANA có hai loại đối tượng riêng biệt cần theo dõi tồn kho: Material (nguyên liệu thô) và ProductVariant (SKU bán được).
• Cả hai dùng chung mô hình tồn kho phía dưới (InventoryStock, InventoryTracking, vị trí kho, định danh, danh mục vendor).
• Cần đúng một ngăn chứa cho mỗi (merchant × principal × vị trí × lô × serial) bất kể loại principal.

Quyết định

Dùng một bản ghi InventoryItem duy nhất, khóa theo (merchantId, itemType, itemId) với itemType ∈ {MATERIAL, PRODUCT_VARIANT} (sinh qua generatePrincipalColumnDefs({ discriminator: 'item' })). InventoryStock tham chiếu inventoryItemId; InventoryTracking tham chiếu inventoryStockId (và qua đó tới item). Principal (Material, ProductVariant) không bao giờ được tham chiếu trực tiếp từ mô hình tồn kho.

Hệ quả

Ưu điểm	Nhược điểm
Một mô hình ngăn chứa tồn kho cho mọi loại principal	Không có FK ở cấp DB tới principal - service phải tự kiểm tra itemType + itemId
Dễ thêm BUNDLE, KIT, v.v. mà không cần migration schema	Truy vấn đa hình không thể dùng một index FK duy nhất
InventoryStockRepository.adjustStock hoạt động đồng nhất	Upsert idempotent (ensureInventoryItem) cần tra cứu ở tầng service
Luồng Sale + PO không phụ thuộc loại principal	Cần ép kiểu/phân biệt loại ở tầng service

Phương án thay thế đã cân nhắc

Phương án	Ưu điểm	Nhược điểm	Lý do từ chối
Tách bảng MaterialStock + ProductVariantStock	FK chặt ở cấp DB	Hai cài đặt song song của adjustStock, tracking, định danh	Chi phí bảo trì; nhân đôi mỗi khi mô hình tồn kho thay đổi
InventoryStock tham chiếu trực tiếp cả materialId + productVariantId (nullable)	Một bảng	Ràng buộc XOR phức tạp; truy vấn luôn phải lọc theo loại	Pattern nửa vời, không dùng trong hệ Drizzle
Gói vào Product chung với kiểu con	Thân thiện hướng đối tượng	Trộn lẫn danh mục (Product) với tồn kho (Inventory) - sai tầng	Lẫn lộn mối quan tâm

Tham chiếu

• core/src/models/schemas/inventory/inventory-item/schema.ts
• inventory/src/services/inventory.service.ts:96-110 (loadPrincipalRefs)