Shared Rules — Ecommerce Inventory Operations

1. Thuật ngữ chuẩn

Thuật ngữ	Nghĩa trong code hiện tại	Ghi chú
Inventory request	inventory_request	Intent layer cho check và transfer
Inventory document	inventory_document	Execution layer cho import/export
Shipping note	shipping_note	Chuyển hàng thực nhận, không đồng nghĩa với inventory document
Product supplying	product_supplying	Ledger movement tổng, không phải snapshot
Lot snapshot	product_lot_no_stock	Tồn theo product + branch + sku + lot_number
SKU snapshot	product_sku_stock	Aggregate snapshot theo SKU
Order transfer	order_kind = order_transfer	Host order sinh ra sau transfer request hoàn tất
Internal order	order_kind = order_material hoặc host layer nội bộ	Không đồng nhất hoàn toàn với inventory request

2. Boundary Matrix

Boundary	Engine chính	Mục đích
Product / warehouse master	product, warehouse, branch_product	Danh mục và phạm vi bán/tồn
Check / transfer request	inventory_request	Ghi nhận intent và approval runtime
Import / export execution	inventory_document	Phiếu thực thi tạo movement
Ship / receive vật lý	shipping_note	Giao nhận thực tế giữa kho
Movement ledger	product_supplying	Ghi nhận dòng nhập/xuất/hold/release/dispose
Snapshot vận hành	product_lot_no_stock, product_sku_stock	Đọc tồn hiện tại
Snapshot báo cáo	*_mv materialized views	Dashboard / reporting

3. Status Matrix

3.1 Inventory request

Family	Status chính
Check	inventory_request_check_new, inventory_request_check_balanced, inventory_request_check_canceled
Transfer	inventory_request_transfer_new, inventory_request_transfer_completed, inventory_request_transfer_canceled

3.2 Inventory document

Status	Ý nghĩa
inventory_new	Phiếu mới
inventory_released	Phiếu đã release, side effects chạy
inventory_canceled	Phiếu bị hủy

3.3 Shipping note

Status	Ý nghĩa
DRAFT	Draft note
APPROVED	Đã duyệt note
DELIVERY	Đang giao / đã ship
RECEIVED	Đã nhận
CANCEL	Hủy

4. Invariants quan trọng

SR-001: Ledger thật là product_supplying

• product_lot_no_stock và product_sku_stock đều là derived read model.
• Mọi phân tích movement phải bắt đầu từ product_supplying.

SR-002: inventory_request không phải document

• request chỉ là intent/approval container,
• execution thật thường bắt đầu khi event update-status chạy,
• phiếu thực thi cụ thể nằm ở inventory_document.

SR-003: shipping_note là boundary riêng

• không dùng inventory_document_id,
• movement bám theo shipping_note_code,
• có state model riêng cho ship/receive/cancel.

SR-004: Snapshot vận hành và reporting snapshot là hai tầng khác nhau

• product_lot_no_stock / product_sku_stock: read model vận hành,
• product_sku_stock_mv / product_sku_stock_product_mv: materialized view cho dashboard/report.

SR-005: Một transfer hoàn chỉnh đi qua nhiều lớp

inventory_request_transfer -> order_transfer -> export inventory_document -> shipping_note -> import inventory_document -> order_transfer_completed

5. Boundary Checklist

Khi phân tích bug hoặc thay đổi ở vùng kho, luôn hỏi:

1. Case này đang ở request layer, document layer hay shipping layer?
2. Dữ liệu đang đọc từ ledger, snapshot vận hành, hay materialized view report?
3. Đây là import/export trực tiếp, check balanced, hay transfer có order/shipping đi kèm?
4. Rule này nằm ở FE validation, Hasura mutate, backend event hay scheduler?
5. Permission đang do route/moduleId, runtime filter, hay Hasura role quyết định?

6. Rủi ro / Findings

ID	Finding
SR-F01	Từ “inventory” trong UI/route đang bao nhiều lớp dữ liệu khác nhau, nên rất dễ mô tả sai boundary.
SR-F02	Import/export/check/transfer/internal/shipping đang chia sẻ một phần engine nhưng không chia sẻ vocabulary rõ ràng.
SR-F03	Nếu không tách rõ ledger và snapshot, QA rất dễ viết test sai nguồn dữ liệu kỳ vọng.