Module Overview — Ecommerce Inventory Operations

1. Scope

Flow này không nằm gọn trong một route, một bảng hay một service. Nó cắt qua:

• frontend ecommerce routes cho product, inventory, import/export, check, transfer, shipping, internal order,
• backend ecommerce-api action/event/scheduler,
• Hasura metadata của domain ecommerce,
• nhiều lớp data model: product master, warehouse, request, document, shipping, ledger, snapshot, materialized views.

Mental model cần giữ từ đầu:

• inventory_request = request/intent layer,
• inventory_document = execution layer,
• shipping_note = physical ship/receive layer,
• product_supplying = movement ledger,
• product_lot_no_stock và product_sku_stock = derived read models.

2. Bức tranh kiến trúc

Product / Warehouse master
  -> Inventory request (check / transfer intent)
  -> Inventory document (import / export execution)
  -> Shipping note (physical delivery / receiving)
  -> product_supplying (ledger)
  -> product_lot_no_stock / product_sku_stock (operational snapshots)
  -> materialized views (dashboard / reporting)

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

3. Frontend Surface

3.1 Route families

Family	Route group	Boundary
Product master	/e/product*	Product, group, supplier, product form
Inventory read	/e/inventory*	Lot stock, in-stock snapshot, history
Import / Export	/e/import-list*, /e/export-request*, /e/inventory-import	inventory_document execution
Check / Transfer request	/e/check-list*, /e/transfer-list*	inventory_request intent
Transfer goods	/e/transfer-goods*	shipping_note / physical shipping
Internal / transfer order	/e/internal-list*, transfer-order*	order_kind = material/transfer host layer

3.2 Permission map thực tế

Boundary	Gate nổi bật
Product / inventory	product_list
Check request	inventory_check_sheet
Transfer request	transfer_request
Internal order	internal_order
Transfer goods	root route dùng transfer_goods, nhưng create/detail/submenu lại còn lệch về transfer_request
Import / export	import_request_sheet / export_request_sheet, nhưng ROUTE_INVENTORY_IMPORT đang gắn nhầm về export

4. Data Layer Map

Layer	Object chính	Vai trò
Product / branch / warehouse	product, branch_product, warehouse	Master data và khả năng bán/tồn theo kho/chi nhánh
Request	inventory_request	Ý định check hoặc transfer
Document	inventory_document	Phiếu thực thi import/export
Shipping	shipping_note, shipping_note_products, shipping_note_product_lot	Chuyển hàng thực nhận
Ledger	product_supplying	Movement import/export/hold/release/dispose
Operational snapshot	product_lot_no_stock, product_sku_stock	Tồn hiện tại để FE đọc
Reporting snapshot	product_sku_stock_mv, product_sku_stock_product_mv, product_supplying_hold_mv	Dashboard/reporting

5. Backend Boundary Map

Lớp	File chính	Vai trò
Action	change_inventory_document_status.go	Action hẹp để set released/canceled
Event	inventory_request_insert.go	Notification khi tạo request
Event	inventory_request_update_status.go	Check balanced, transfer complete/cancel
Event	inventory_document_update_status.go	Release/cancel side effects, transfer import auto-create
Event	shipping_note_insert_update.go	Movement ship/receive/cancel
Scheduler	product_sku_stock.go	Refresh materialized views cho dashboard/report

6. Semantic Rules Cần Nhớ

1. inventory_request chưa phải execution ledger; nhiều side effect thật chỉ chạy ở update-status event.
2. Import và export FE đang dùng cùng inventory_document engine; import list thậm chí còn reuse query của export.
3. transfer request không phải điểm cuối; sau đó flow còn đi qua order_transfer, inventory_document, rồi shipping_note.
4. shipping_note không đồng nghĩa với inventory_document; nó là boundary riêng cho ship/receive vật lý.
5. product_sku_stock không realtime tuyệt đối cho mọi use case reporting vì còn phụ thuộc materialized-view refresh ở vài nhánh.

7. Rủi ro / Findings

ID	Mức	Finding
F-01	P1	FE đang có drift thật về moduleId giữa transfer_goods, transfer_request, import_request_sheet, export_request_sheet.
F-02	P1	product_supplying ôm quá nhiều semantics nên rất dễ bị hiểu sai là snapshot.
F-03	P1	inventory_request, inventory_document, shipping_note là ba lớp khác nhau nhưng tên route/menu không luôn phản ánh boundary này.
F-04	P1	Backend action cho inventory document quá hẹp; nhiều invariant và side effect bị dồn sang FE hoặc event.
F-05	P1	shipping_note branch RECEIVED có dấu hiệu bug khi note có nhiều SKU/lot nhưng code dùng dữ liệu từ phần tử đầu tiên của product_supplying.
F-06	P2	Permission Hasura của inventory/shipping/ledger khá rộng, nên correctness hiện phụ thuộc nhiều vào FE và event logic.