Sản phẩm & Kho — Business Rules

Tổng quan

Domain này bao phủ hai lớp khác nhau nhưng gắn chặt với nhau:

• Product master: sản phẩm, danh mục, nhóm, loại, đơn vị, nguồn gốc, nhà cung cấp.
• Inventory operations: tồn kho, phiếu nhập/xuất, phiếu chuyển, kiểm kho, nội bộ, shipping note.

Điểm khó nhất của domain này là dữ liệu tồn kho không nằm ở một bảng duy nhất. Source of truth thực tế là:

• product_supplying cho movement/ledger,
• product_sku_stock và product_lot_no_stock cho số dư đọc nhanh.

Product master

Thành phần chính

Thành phần	Vai trò
product	Bản ghi sản phẩm/DV gốc
product_contents	Nội dung đa ngôn ngữ
product_category_reference	Gắn category nhiều-nhiều
supplier / product_supplying	Nhà cung cấp + lịch sử nhập/xuất theo supplier
product_group, product_type, product_unit, product_origin	Master data bổ trợ
branch_product	Khả năng bán/cấu hình theo chi nhánh

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-001	Product master là đa ngôn ngữ qua product_contents, không phải chỉ một cột name duy nhất.
BR-PI-002	Category của sản phẩm là many-to-many qua product_category_reference.
BR-PI-003	Supplier không phải quan hệ 1-1 đơn giản; một sản phẩm có thể gắn nhiều supplier/movement khác nhau.
BR-PI-004	Cùng một product có thể chạy ở nhiều chi nhánh với cấu hình riêng qua branch_product.

Mô hình tồn kho

Ledger vs Snapshot

Product
  -> ProductSupplying (mọi movement: nhập, xuất, hold, release, transfer ship/receive)
  -> ProductSkuStock (snapshot theo SKU/kho)
  -> ProductLotNoStock (snapshot theo lot/kho)

Ý nghĩa nghiệp vụ

Bảng / view	Vai trò
product_supplying	Sổ cái tồn kho theo movement
product_sku_stock	Số dư hiện tại theo SKU/kho
product_lot_no_stock	Số dư hiện tại theo lot/kho

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-005	Tồn kho thực tế để xem list/detail lấy từ product_sku_stock hoặc product_lot_no_stock, không lấy trực tiếp từ ledger.
BR-PI-006	Ledger product_supplying ghi nhiều loại movement khác nhau; muốn đọc đúng phải biết source document.
BR-PI-007	Snapshot tồn kho phụ thuộc scheduler refresh materialized view, nên có thể lệch nhẹ so với real-time event.

Nhập kho từ supplier

Tạo import request
  -> chọn kho nhận
  -> nhập SKU / supplier / lot / expiry / quantity / discount
  -> validate file hoặc form
  -> release / complete document
  -> sinh movement nhập kho

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-008	SKU phải hợp lệ, supplier code phải thuộc đúng product.
BR-PI-009	quantity > 0, expiry phải lớn hơn hiện tại.
BR-PI-010	Discount không được vượt giá nhập hoặc vượt 100%.
BR-PI-011	Kho nhận nhập từ supplier bị filter: kho không phải sales, hoặc là sales nhưng imported_product = true.

Xuất kho / phiếu xuất

Tạo export request
  -> chọn loại xuất, kho xuất, danh sách item
  -> duyệt / release
  -> inventory_document update status
  -> cập nhật order / notification / movement

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-012	changeInventoryDocumentStatus hiện chỉ xử lý rõ 2 nhánh inventory_released và inventory_canceled.
BR-PI-013	Nhiều side effect của phiếu xuất nằm ở event update status, không nằm trong mutation FE.

Kiểm kho

Tạo check sheet
  -> đếm thực tế theo lot/SKU
  -> submit chênh lệch
  -> chuyển balanced
  -> hệ thống tự sinh phiếu nhập hoặc xuất bù chênh lệch

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-014	Khi check sheet balanced, hệ thống tự sinh phiếu nhập/xuất phần chênh ngay trên cùng kho kiểm.
BR-PI-015	UI chặn đổi trạng thái nếu còn item chưa gán lot_number.

Chuyển kho / chuyển hàng / nội bộ

Domain này có ít nhất 2 lớp dễ nhầm:

Luồng	Mô tả
inventory_request / order_transfer	Request và order vận hành cho luồng chuyển
shipping_note / transfer_goods	Chuyển hàng thực nhận, tạo movement ship/receive

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PI-016	Transfer request khi complete sẽ sinh order_transfer; luồng không dừng ở request.
BR-PI-017	shipping_note ở trạng thái delivered tạo xuất âm; received tạo nhập dương; canceled xóa movement liên quan.
BR-PI-018	Complete internal/transfer order bị chặn nếu còn inventory document ở trạng thái inventory_new.

Rủi ro / Findings

Mức	Mô tả
P1	product_supplying ôm quá nhiều nghĩa, rất dễ bị hiểu nhầm là bảng snapshot.
P1	Có hai lớp transfer song song (inventory_request/order_transfer và shipping_note/transfer_goods) nên tài liệu cũ dễ mô tả sai.
P2	List import đang reuse hook/query của export và phân biệt bằng type_id = import, làm semantics FE khó đọc.
P2	Route/menu naming của transfer/internal chưa sát nghĩa business, dễ gây hiểu nhầm cho người mới.
P2	Snapshot tồn kho phụ thuộc scheduler refresh product_sku_stock, nên số liệu không hẳn realtime tuyệt đối.