Ecommerce Inventory Operations Deep Dive

Bộ tài liệu này đào sâu flow ecommerce-inventory-operations theo code thực tế hiện tại. Đây là package reverse-engineer trong docs/modules, không phải PRD/spec delivery. Mục tiêu là chốt một mental model rõ ràng cho 5 lớp rất dễ bị lẫn:

• inventory_request là request/intent layer,
• inventory_document là execution layer,
• shipping_note là physical shipping/receiving layer,
• product_supplying là movement ledger,
• product_lot_no_stock và product_sku_stock là snapshot/read models.

Đọc file nào?

Bạn là ai?	Nên đọc trước	Mục tiêu
PO / BA	shared-rules.md	Chốt thuật ngữ, boundary, state model, coupling
FE Dev	type-approval-and-adjustment-flows.md	Hiểu route, page, GraphQL, runtime drift
BE Dev	type-stock-movement-engine.md	Hiểu action/event/scheduler và side effects
QA	type-stock-snapshot-vs-ledger.md, type-approval-and-adjustment-flows.md	Thiết kế test theo request/document/shipping/snapshot
Người mới vào hệ thống	module-overview.md	Có bản đồ tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: route families, data layers, backend boundaries, risks
shared-rules.md	Thuật ngữ chuẩn, state matrix, boundary checklist, invariants
type-stock-movement-engine.md	Deep dive cho request/document/shipping và movement ledger
type-stock-snapshot-vs-ledger.md	Deep dive cho product_supplying, product_lot_no_stock, product_sku_stock, MV/reporting
type-approval-and-adjustment-flows.md	Deep dive cho import/export/check/transfer/internal/shipping từ góc nhìn runtime

Kết luận ngắn

1. Inventory không phải một flow duy nhất; nó là chồng của request, document, shipping, order transfer và snapshot.
2. product_supplying là ledger thật nhưng bị overloaded mạnh, nên rất dễ bị hiểu nhầm là “bảng nhập hàng”.
3. product_lot_no_stock và product_sku_stock chỉ là derived read models, không phải source-of-truth movement.
4. FE đang có nhiều drift thật về moduleId, route guard và reuse query giữa import/export/transfer.

Liên kết tài liệu liên quan

• docs/modules/ecommerce/overview.md
• docs/modules/ecommerce/inventory.md
• docs/modules/ecommerce/inventory.technical.md
• docs/modules/ecommerce/deep-dives/refund-withdraw/README.md
• docs/modules/phase-2-backlog.md

Phạm vi của bộ docs này

• Bám theo code hiện tại của diva-admin, ecommerce-api, Hasura metadata và migrations của DB ecommerce.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì flow lý tưởng.
• Chủ động ghi ra các drift hoặc dấu hiệu bug ở FE, backend và DB/read-model.