PRD: Nguyên vật liệu

Module	Kho	PRD ID	PRD-MAT-001
Trạng thái	Đã thay thế	FEAT	MAT
Epic	—	Plane	—
Ngày	2026-07-13	Phiên bản	v1.0
Gói	@nx/inventory	URD	MAT
Surface	Client · Chủ/QL
Phụ trách	Phát Nguyễn

Nguyên vật liệu là gì

Nguyên vật liệu (Material) là thứ dùng để làm ra món khác và không bán trực tiếp: sữa, trà, trân châu, ly nhựa. Chủ quán khai nguyên liệu tại màn Nguyên vật liệu trên trang Client, và chọn nó là nguyên liệu thô, bán thành phẩm hay vật tư tiêu hao.

Nguyên liệu là danh mục thứ hai của Kho, đứng ngang hàng với biến thể sản phẩm. Nó có tồn tại từng kho (InventoryLocation) của một chi nhánh (Merchant), nhập bằng đơn mua hàng, và bị trừ bằng công thức hoặc bằng một phiếu kho.

Bốn chỉ số trong tồn kho

Trích từ Kho & mức tồn để khỏi phải mở PRD khác. Mỗi mặt hàng ở mỗi kho mang bốn con số:

Con số	Hệ thống gọi	Nghĩa
Thực có	on-hand	Hàng đang nằm trong kho
Đang giữ	reserved	Đã hứa cho một chứng từ khác, không bán cho ai được nữa
Khả dụng	available	Phần còn bán được
Đang về	incoming	Đã rời kho gửi, chưa tới kho nhận

Bất biến, đúng ở mọi thời điểm:

Khả dụng = Thực có - Đang giữ

Vì sao nguyên liệu cần một danh mục riêng

Quán F&B không bán sữa, quán bán trà sữa. Thứ hết trong kho lại là sữa, là trân châu, là ly nhựa. Một hệ thống chỉ biết tới sản phẩm bán ra thì không trả lời được câu "tối nay còn pha được bao nhiêu ly", và cũng không biết thùng sữa nào sắp hết hạn.

Chỗ nguyên liệu khác sản phẩm là cách quản không đồng nhất. Sữa cần theo dõi tồn, cần chia lô, cần hạn dùng. Đá viên đếm không bao giờ chính xác. Ly nhựa chỉ cần biết sắp hết để đặt thêm. Vì vậy bộ cờ cấu hình kho gắn vào từng nguyên liệu, thay vì cả kho chạy chung một chính sách.

Khác biệt thứ hai là nhà cung cấp. Một quán mua sữa từ ba nơi, mỗi nơi một giá, một số lượng đặt tối thiểu, một thời gian giao. Tên nhà cung cấp vì thế không nằm trên nguyên liệu. Nó nằm ở bảng giá nhà cung cấp, nơi mỗi cặp nhà cung cấp và nguyên liệu là một dòng riêng.

Một nguyên liệu từ đầu tới cuối

Sữa tươi, đơn vị gốc là lít, ngưỡng tồn thấp 5 lít, hạn dùng 7 ngày. Công thức trà sữa cần 50ml sữa cho một ly.

Việc xảy ra	Thực có	Đang giữ	Khả dụng	Giá vốn
Khai nguyên liệu, tồn ban đầu 20 lít tại kho Bếp	20	0	20	25.000 đ/lít, khai tay
Nhận 10 lít bằng đơn mua hàng, giá 30.000 đ/lít	30	0	30	tính lại theo giá nhập thật
Thu ngân bấm 1 ly trà sữa vào đơn	30	0,05	29,95	không đổi
Khách thanh toán, đơn hoàn tất	29,95	0	29,95	không đổi
Kiểm kê cuối ngày đếm được 29,5 lít	29,5	0	29,5	không đổi

• Giá mua khai tay chỉ sống tới lần nhận hàng đầu tiên. Từ đó trở đi giá vốn chạy theo giá nhập thật.
• Bấm món vào đơn là giữ sữa, chưa trừ sữa. Sữa rời kho thật lúc đơn hoàn tất.
• Tồn còn 4 lít thì dòng sữa bị đánh dấu tồn thấp, vì ngưỡng của nó là 5 lít.

Chỗ dễ sai nhất

Số lượng tồn không bao giờ được gõ tay ở màn nguyên liệu

Màn sửa nguyên liệu cho đổi tên, đổi danh mục, đổi đơn vị, đổi cờ cấu hình kho, đổi danh sách nhà cung cấp. Nó không có ô nào để gõ lại số lượng tồn.

Số lượng chỉ đổi qua bốn đường: nhận hàng, bán hàng, chuyển kho, kiểm kê. Mỗi con số tồn vì thế luôn truy được về một chứng từ. Ngoại lệ duy nhất là lần khai tồn ban đầu lúc tạo nguyên liệu.

Hệ quả: sổ sai thì lập một phiếu kiểm kê để đếm lại, không sửa đè lên con số cũ.

1. Mục tiêu & Loại trừ

Mục tiêu

• Cho merchant khai và quản danh mục nguyên vật liệu tại trang Client, phân theo ba loại: nguyên liệu thô, bán thành phẩm, vật tư tiêu hao.
• Cho từng nguyên liệu mang bộ cờ cấu hình kho riêng: theo dõi tồn, theo lô, có hạn dùng, số ngày hạn dùng, cho bán âm, ngưỡng tồn thấp.
• Cho một nguyên liệu mang ba vai đơn vị (gốc, mua, bán) và quy đổi qua engine đơn vị chung của Kho.
• Giữ liên kết nhà cung cấp chỉ ở bảng giá nhà cung cấp, không có trường nhà cung cấp trên chính nguyên liệu.
• Gộp việc tạo nguyên liệu, khai tồn ban đầu ở nhiều địa điểm, và gán nhà cung cấp vào đúng một lần lưu.

Loại trừ

• Định lượng công thức (một ly trà sữa cần bao nhiêu ml sữa) thuộc Công thức, không thuộc PRD này.
• Cơ chế trừ kho khi bán và thời điểm trừ sổ thuộc Công thức và Giữ tồn.
• Cách một lô được sinh ra khi nhận hàng, chiến lược xuất FEFO/FIFO thuộc Lô, hạn dùng & chiến lược xuất. PRD này chỉ khai cờ bật/tắt trên nguyên liệu.
• Cách tính giá vốn bình quân gia quyền thuộc Giá vốn.
• Bảng giá nhà cung cấp (giá, số lượng đặt tối thiểu, thời gian giao) được định nghĩa đầy đủ ở Nhà cung cấp. PRD này chỉ nói về phía nguyên liệu của liên kết đó.
• Điểm đặt hàng lại và tồn an toàn thuộc Bổ sung hàng. Ngưỡng tồn thấp trong PRD này chỉ là một cảnh báo đơn giản, không phải điểm đặt hàng lại.

2. Thước đo thành công

Thước đo	Mục tiêu / tín hiệu
Độ phủ danh mục nguyên liệu	Merchant F&B khai được toàn bộ nguyên liệu thường dùng của quán mà không phải nhờ đội vận hành nhập hộ
Một lần lưu	Tỉ lệ nguyên liệu được tạo kèm cả tồn ban đầu và nhà cung cấp ngay trong lần lưu đầu tiên tăng dần
Chất lượng cấu hình kho	Nguyên liệu có hạn dùng đều được khai số ngày hạn dùng, không để trống rồi phải sửa lại sau
Cảnh báo tồn thấp	Số lần chủ quán phát hiện hết nguyên liệu ngay tại quầy (thay vì được báo trước) giảm dần

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Chủ quán (Owner)	Khai nguyên liệu của quán một lần, chọn cách quản cho từng thứ, biết mua ở đâu
Quản lý (Manager)	Xem danh mục nguyên liệu, sửa cấu hình kho, theo dõi nguyên liệu chạm ngưỡng tồn thấp
Thu ngân / Bếp (Cashier, Kitchen)	Không thao tác trực tiếp, nhưng chịu hệ quả: hết nguyên liệu thì món báo hết ngay tại quầy
Đội vận hành	Hỗ trợ merchant dựng danh mục nguyên liệu ban đầu khi mở quán

Kịch bản cốt lõi: chủ quán mở màn Nguyên vật liệu tại trang Client → bấm Tạo mới → khai tên "Sữa tươi", chọn loại nguyên liệu thô, chọn danh mục, chọn đơn vị gốc là lít → bật theo dõi tồn, bật hạn dùng và khai 7 ngày, đặt ngưỡng tồn thấp 5 lít → khai tồn ban đầu 20 lít tại kho Bếp và 10 lít tại kho Quầy → chọn hai nhà cung cấp → bấm Lưu một lần → nguyên liệu, hai dòng tồn và hai liên kết nhà cung cấp cùng được ghi.

4. User Stories

#	Là một	Tôi muốn	Để
01	chủ quán	khai nguyên liệu của quán và chọn nó là nguyên liệu thô, bán thành phẩm hay vật tư tiêu hao	danh mục sắp xếp đúng cách tôi nghĩ về nó
02	chủ quán	bật theo dõi tồn cho sữa nhưng để đá viên đứng ngoài kho	tôi không phải kiểm kê những thứ không đếm chính xác được
03	chủ quán	khai hạn dùng 7 ngày cho sữa tươi	hệ thống tự biết lô sữa nhập hôm nay hết hạn ngày nào mà không cần tôi nhớ
04	chủ quán	cho bán âm với đá và ống hút	quầy không bị chặn bán chỉ vì số đếm trên hệ thống lệch một chút
05	chủ quán	một nguyên liệu gắn được với nhiều nhà cung cấp, mỗi nơi một giá	tôi biết nên đặt hàng ở đâu
06	chủ quán	khai nguyên liệu, tồn ban đầu ở nhiều kho và nhà cung cấp trong một lần bấm Lưu	dựng xong một dòng nguyên liệu không phải chạy qua ba màn hình
07	quản lý	mở danh sách nguyên liệu và thấy ngay mặt hàng nào đang chạm ngưỡng tồn thấp	tôi đặt hàng trước khi quán hết hàng

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Một nguyên liệu được khai bằng các trường sau tại màn Nguyên vật liệu. • Tên hiển thị song ngữ, bắt buộc. • Mã nguyên liệu, bắt buộc và duy nhất trong phạm vi chi nhánh (Merchant). Chủ quán tự đặt, hệ thống không sinh hộ. • Danh mục nguyên liệu, là tùy chọn. • Mô tả, là tùy chọn. • Đơn vị gốc, bắt buộc: đơn vị nhỏ nhất mà nguyên liệu này được đếm. • Kích thước, bắt buộc: dài, rộng, cao kèm đơn vị đo. • Khối lượng, là tùy chọn: con số kèm đơn vị đo.	🔶	URD-MAT-001 · URD-MAT-003
FR-002	Mỗi nguyên liệu mang một loại, chọn trong ba giá trị. • Nguyên liệu thô: mua về dùng thẳng (sữa, trà, bột mì). Đây là giá trị mặc định. • Bán thành phẩm: quán tự làm ra rồi dùng tiếp làm nguyên liệu cho món khác, ví dụ trân châu đã luộc. • Vật tư tiêu hao: dùng kèm nhưng không nằm trong món (ly, ống hút, túi giấy). • Bán thành phẩm có bật theo dõi tồn là điểm dừng của nổ định mức (xem Công thức). Bán một món là trừ thẳng trên tồn bán thành phẩm, hệ thống không đi tiếp xuống các nguyên liệu đã dùng để nấu ra nó. Nồi nước dùng và trân châu tự nấu là hai ví dụ. • Bán thành phẩm chỉ có tồn khi một lệnh sản xuất khai nó ra (xem Lệnh sản xuất).	🔶	URD-MAT-001
FR-003	Mỗi nguyên liệu mang bộ cờ cấu hình kho riêng của nó. • Có theo dõi tồn hay không. Tắt thì nguyên liệu này không đụng tới kho. • Có chia theo lô hay không. • Có theo dõi theo serial hay không, mặc định tắt. Cách sinh và quét serial thuộc Lô, hạn dùng & chiến lược xuất; ở đây chỉ giữ cờ bật tắt. • Có hạn dùng hay không, và số ngày hạn dùng kể từ lúc nhập. • Cho bán âm hay không, mặc định tắt. Bật thì nguyên liệu này vẫn bán được cả khi tồn về 0. • Ngưỡng tồn thấp riêng cho nguyên liệu này.	🔶	URD-MAT-002
FR-004	Nguyên liệu mang ba vai đơn vị cùng lúc, kèm hệ số quy đổi riêng của chính nó. • Đơn vị gốc: tồn luôn được lưu theo đơn vị này. • Đơn vị mua: đơn vị hiện sẵn khi lập đơn mua hàng cho nguyên liệu này. • Đơn vị bán: đơn vị dùng khi khai định lượng công thức. • Hệ số quy đổi khai riêng cho từng nguyên liệu và ghi đè hệ số chung của danh mục đơn vị. Chủ quán gõ thẳng "một thùng sữa của tôi là 24 lon", con số đó chỉ áp cho nguyên liệu này. Ba vai quy đổi qua engine đơn vị chung của Kho. Ngoài con số ghi đè nói trên, chủ quán không phải tự nhân chia hệ số.	🔶	URD-MAT-003
FR-005	Nguyên liệu không có trường nhà cung cấp trên chính nó. • Ai bán nguyên liệu này thì tra ở bảng giá nhà cung cấp. • Một nguyên liệu gắn được với nhiều nhà cung cấp, mỗi nhà cung cấp một giá, một số lượng đặt tối thiểu và một thời gian giao riêng. • Gỡ một nhà cung cấp khỏi bảng giá không làm nguyên liệu mất thông tin nào của chính nó.	🔶	URD-MAT-004
FR-006	Tạo một nguyên liệu mới xong trong một lần bấm Lưu, gồm cả tồn và nhà cung cấp. • Khai thông tin nguyên liệu và bộ cờ cấu hình kho. • Khai tồn ban đầu tại nhiều kho cùng lúc, mỗi kho một dòng số lượng. • Chọn một hoặc nhiều nhà cung cấp cho nguyên liệu này. • Hỏng ở bất kỳ phần nào thì cả lần lưu không ghi gì, form giữ nguyên dữ liệu đang nhập.	🔶	URD-MAT-005
FR-007	Sửa một nguyên liệu cũng làm trong một lần lưu, nhưng số lượng tồn không sửa được ở đây. • Sửa được: tên, mô tả, danh mục, đơn vị, bộ cờ cấu hình kho, danh sách nhà cung cấp. • Số lượng tồn chỉ đổi qua nhận hàng, bán hàng, chuyển kho hoặc kiểm kê. • Tắt cờ theo dõi tồn của một nguyên liệu đang có tồn thì hệ thống hỏi lại trước khi bỏ phần tồn kho khỏi nguyên liệu đó.	🔶	URD-MAT-006
FR-008	Khai giá mua khởi tạo cùng lúc với tồn ban đầu. • Con số này là giá vốn xuất phát của nguyên liệu tại lúc khai danh mục. • Từ lần nhận hàng đầu tiên trở đi, Kho tính lại giá vốn theo giá nhập thật. Con số khai tay không còn được dùng nữa.	🔶	URD-MAT-005
FR-009	Ngưỡng tồn thấp phân giải theo thứ tự từ riêng tới chung. • Dòng tồn của nguyên liệu tại một kho có khai ngưỡng riêng thì dùng ngưỡng của kho đó. Kho Bếp cần 10 lít sữa, kho Quầy chỉ cần 2 lít. • Kho không khai thì lùi về ngưỡng khai trên chính nguyên liệu. • Không khai ở đâu cả thì dùng ngưỡng mặc định chung của hệ thống là 5 đơn vị gốc.	🔶	URD-MAT-007
FR-010	Màn Nguyên vật liệu liệt kê toàn bộ nguyên liệu của chi nhánh. • Cột hiển thị: mã, tên, danh mục, đơn vị gốc, giá vốn, tồn hiện tại, trạng thái. • Tìm theo tên hoặc mã. Lọc theo danh mục, theo loại nguyên liệu và theo trạng thái. • Nguyên liệu chạm ngưỡng tồn thấp được đánh dấu ngay trên dòng của nó. • Đầu màn hiện bốn thẻ số liệu: tổng số nguyên liệu, số đang bật theo dõi tồn, số tồn thấp, số hết hàng.	🔶	URD-MAT-001 · URD-MAT-007
FR-011	Nguyên liệu bật theo dõi tồn trở thành một mục kho, đứng ngang hàng với biến thể sản phẩm. • Nó mang đủ bốn con số tồn tại từng kho: thực có, đang giữ, khả dụng, đang về. • Nó nhận hàng bằng đơn mua hàng, bị công thức giữ rồi trừ, và được đếm lại bằng phiếu kiểm kê, đúng như một mặt hàng thường.	🔶	URD-MAT-002
FR-012	Nguyên liệu đi qua ba trạng thái: đang dùng, ngừng dùng, lưu trữ. • Ngừng dùng: không còn hiện trong danh sách chọn khi khai công thức hay lập đơn mua hàng. Tồn và lịch sử vẫn giữ nguyên. • Lưu trữ: khóa hẳn, không sửa được thông tin lẫn cấu hình kho. Muốn sửa thì kích hoạt lại nguyên liệu trước.	🚧	URD-MAT-008
FR-013	Một nguyên liệu được đồng bộ sang các chi nhánh khác trong cùng tổ chức (Organizer), ngay trên form nguyên liệu. • Chủ quán chọn một hoặc nhiều chi nhánh khác, hệ thống nhân bản nguyên liệu sang từng chi nhánh được chọn. • Bỏ một chi nhánh khỏi danh sách đồng bộ thì phải xác nhận lại, vì bản sao bên đó không còn được giữ đồng bộ nữa. • Nguyên liệu ở mỗi chi nhánh là một dòng độc lập: tồn, bảng giá nhà cung cấp và cấu hình kho của bản sao không dính vào bản gốc.	🔶	URD-MAT-001 · URD-MAT-005

5.1 Tiêu chí nghiệm thu

• Mở màn Nguyên vật liệu từ menu Kho tại trang Client → thấy danh sách nguyên liệu của merchant, kèm bốn thẻ ở đầu màn: tổng số nguyên liệu, số đang bật theo dõi tồn, số tồn thấp, số hết hàng.
• Bấm Tạo mới, khai tên "Sữa tươi", bỏ trống ô mã, chọn đơn vị gốc là lít, bấm Lưu → lần lưu bị từ chối và ô mã báo lỗi bắt buộc; điền mã "SUA-TUOI" rồi lưu lại → nguyên liệu được tạo.
• Tạo một nguyên liệu thứ hai cũng mang mã "SUA-TUOI" trong cùng merchant → lần lưu bị từ chối vì mã đã tồn tại.
• Tạo nguyên liệu và chọn loại "vật tư tiêu hao" cho "Ly nhựa 500ml" → lưu xong, mở lại nguyên liệu thấy đúng loại vật tư tiêu hao, và lọc danh sách theo loại này thì "Ly nhựa 500ml" xuất hiện.
• Bật cờ hạn dùng cho "Sữa tươi" và khai 7 ngày → nhận một lô sữa hôm nay → lô đó mang ngày hết hạn là 7 ngày sau ngày nhận.
• Bật cờ cho bán âm cho "Đá viên", để tắt cho "Sữa tươi" → bán một món hết cả hai nguyên liệu khi tồn đã về 0 → đá viên cho qua và ghi tồn âm, sữa tươi bị chặn và báo ngay tại quầy.
• Tắt cờ theo dõi tồn cho "Ống hút" đang có tồn 200 cái → hệ thống hỏi lại trước khi bỏ phần tồn kho → xác nhận → "Ống hút" không còn xuất hiện trong màn tồn kho nữa.
• Khai "Sữa tươi" với đơn vị gốc lít, đơn vị mua thùng, đơn vị bán ml → lập đơn mua hàng cho sữa → ô đơn vị hiện sẵn thùng; khai công thức trà sữa → ô đơn vị hiện sẵn ml.
• Khai hệ số quy đổi riêng cho "Sữa lon": một thùng bằng 24 lon → nhận 2 thùng bằng đơn mua hàng → tồn tăng 48 lon; nguyên liệu khác dùng cùng cặp đơn vị thùng và lon nhưng không khai hệ số riêng thì vẫn quy đổi theo hệ số chung của danh mục đơn vị.
• Nhận 10 lít "Sữa tươi" bằng đơn mua hàng → thực có tăng 10, khả dụng tăng 10, đang giữ không đổi, đang về giảm về 0; bấm một món có công thức gọi sữa vào đơn → đang giữ tăng, khả dụng giảm, thực có chưa đổi cho tới lúc trừ sổ; chạy một phiếu kiểm kê đếm lại còn 8 lít → thực có về đúng 8.
• Tạo "Sữa tươi", khai tồn ban đầu 20 lít tại kho Bếp và 10 lít tại kho Quầy, chọn 2 nhà cung cấp, bấm Lưu một lần → nguyên liệu, hai dòng tồn theo địa điểm và hai liên kết nhà cung cấp cùng được ghi; không phải mở thêm màn nào.
• Cùng form đó, cố tình chọn một địa điểm kho đã ngừng hoạt động rồi bấm Lưu → lần lưu bị từ chối, không có nguyên liệu nào được tạo, form giữ nguyên mọi thứ đang nhập.
• Tạo "Sữa tươi" kèm giá mua khởi tạo 25.000 đ/lít → mở màn giá vốn thấy 25.000 đ/lít; nhận 10 lít giá 30.000 đ/lít → giá vốn được tính lại theo giá nhập thật, không còn giữ con số khai tay.
• Gỡ nhà cung cấp A khỏi bảng giá của "Trà" → "Trà" vẫn còn nguyên mọi thông tin của nó, chỉ mất đúng dòng bảng giá của nhà cung cấp A.
• Mở màn sửa "Sữa tươi" → không có ô nào cho phép gõ lại số lượng tồn; đổi tên, đổi danh mục, thêm một nhà cung cấp rồi bấm Lưu → cả ba thay đổi cùng được ghi trong một lần.
• Đặt ngưỡng tồn thấp 5 lít cho "Sữa tươi", không đặt ngưỡng cho "Trà" → tồn sữa còn 4 lít và tồn trà còn 4 đơn vị → cả hai đều bị đánh dấu tồn thấp trên danh sách, sữa theo ngưỡng riêng 5 và trà theo ngưỡng mặc định 5.
• Đặt riêng ngưỡng 10 lít cho dòng tồn "Sữa tươi" tại kho Bếp, trong khi ngưỡng trên chính nguyên liệu là 5 → tồn Bếp còn 8 lít và tồn Quầy còn 8 lít → Bếp bị đánh dấu tồn thấp theo ngưỡng 10 của địa điểm, Quầy không bị đánh dấu vì vẫn trên ngưỡng 5 của nguyên liệu.
• Mở màn Nguyên vật liệu, chọn merchant thứ hai trong org ở phần đồng bộ của "Sữa tươi" rồi Lưu → merchant đó có một nguyên liệu "Sữa tươi" của riêng nó; bỏ merchant đó khỏi danh sách đồng bộ → hệ thống hỏi lại trước khi gỡ, xác nhận xong thì bản gốc vẫn còn nguyên tồn và bảng giá nhà cung cấp của nó.
• Chuyển "Bột nếp" sang trạng thái ngừng dùng → mở màn khai công thức, tìm "Bột nếp" → không còn thấy trong danh sách chọn; mở màn tồn kho → tồn của "Bột nếp" vẫn còn nguyên.
• Chuyển "Bột nếp" sang trạng thái lưu trữ rồi thử sửa ngưỡng tồn thấp của nó → hệ thống từ chối và yêu cầu kích hoạt lại nguyên liệu trước khi sửa.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Phân quyền theo merchant	Nguyên liệu, bảng giá nhà cung cấp và tồn của chúng đều nằm trong phạm vi merchant của người dùng; người của merchant khác không đọc và không sửa được
Toàn vẹn dữ liệu	Một lần lưu gồm nguyên liệu, tồn nhiều địa điểm và nhà cung cấp là trọn gói: hỏng một phần thì không phần nào được ghi
Xóa mềm	Xóa một nguyên liệu là xóa mềm, khôi phục được; lịch sử biến động tồn của nó vẫn giữ nguyên
Ràng buộc dữ liệu	Mã nguyên liệu là duy nhất trong phạm vi merchant; số lượng và giá dùng độ chính xác 4 chữ số thập phân
i18n	Tên và mô tả nguyên liệu là song ngữ Việt - Anh
Quy mô	Một merchant F&B thường khai từ 50 tới 300 nguyên liệu; danh sách phân trang và tìm kiếm phải chạy được ở quy mô này

7. UX & Luồng

Luồng tạo một nguyên liệu, từ lúc mở màn tới lúc lưu xong:

Cách một nguyên liệu bước vào các nghiệp vụ khác của Kho sau khi được khai:

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò
Nguyên vật liệu	Thứ dùng để làm ra món khác, không bán trực tiếp; mang tên, mã, danh mục, loại và bộ cờ cấu hình kho
Loại nguyên liệu	Nguyên liệu thô, bán thành phẩm, hoặc vật tư tiêu hao; dùng để phân nhóm danh mục
Bộ cờ cấu hình kho	Theo dõi tồn, theo lô, theo serial, có hạn dùng, số ngày hạn dùng, cho bán âm, ngưỡng tồn thấp - khai theo từng nguyên liệu
Ba vai đơn vị	Đơn vị gốc (lưu tồn), đơn vị mua (đặt hàng), đơn vị bán (định lượng công thức), kèm hệ số quy đổi ghi đè khai riêng cho từng nguyên liệu
Mục kho	Cầu nối đưa một nguyên liệu vào thế giới tồn kho, cùng một cách với biến thể sản phẩm
Bảng giá nhà cung cấp	Nơi duy nhất giữ liên kết giữa một nguyên liệu và các nhà cung cấp bán nó, kèm giá, số lượng đặt tối thiểu, thời gian giao
Danh mục nguyên liệu	Nhóm do merchant tự đặt để sắp xếp danh sách nguyên liệu

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong inventory domain model.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	LOC Địa điểm kho	tồn ban đầu của một nguyên liệu phải gắn vào một địa điểm có thật và đang hoạt động.
02	UOM Đơn vị tính & quy đổi	ba vai đơn vị của nguyên liệu lấy từ danh mục đơn vị, và engine quy đổi lo phần nhân chia hệ số.
03	VEN Nhà cung cấp	bảng giá nhà cung cấp là nơi duy nhất giữ liên kết giữa nguyên liệu và người bán nó.
04	STK Mục kho & mức tồn	nguyên liệu bật theo dõi tồn dùng chung bốn con số tồn với biến thể sản phẩm.
05	BOM Công thức	nguyên liệu chỉ thật sự bị trừ khi có một công thức gọi tới nó.

Giả định

#	Giả định	Sai thì sao
01	Merchant F&B chấp nhận bỏ công khai danh mục nguyên liệu một lần khi mở quán, đổi lại biết được còn pha được bao nhiêu ly.	Danh mục khai dở dang thì công thức không có thành phần để gọi, và toàn bộ phần trừ kho theo nguyên liệu ngừng có nghĩa.
02	Không phải nguyên liệu nào cũng cần theo dõi tồn, và chủ quán là người quyết định thứ nào cần.	Ép theo dõi tồn cho mọi nguyên liệu thì quán phải kiểm kê cả đá viên và ống hút, và số liệu kho sẽ đầy những dòng không ai tin.
03	Một nguyên liệu mua được từ nhiều nhà cung cấp là chuyện bình thường, không phải ngoại lệ.	Nếu thực tế là một nguyên liệu chỉ một nhà cung cấp thì bảng giá riêng thành thừa, và một trường nhà cung cấp ngay trên nguyên liệu sẽ đơn giản hơn.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P2 (Kho) - xem danh mục feature URD
Rollout	Merchant F&B trước, sau đó mở cho mọi merchant; không feature flag
Migration	Không có nguyên liệu nào cần chuyển đổi dữ liệu; danh mục nguyên liệu do merchant tự khai từ đầu
Tiêu chí phát hành	Merchant mở màn Nguyên vật liệu từ menu Kho, tạo được một nguyên liệu kèm tồn nhiều địa điểm và nhà cung cấp trong một lần lưu, và nguyên liệu đó bị trừ đúng khi bán một món có công thức gọi tới nó
Theo dõi	Số nguyên liệu được khai trên mỗi merchant, tỉ lệ nguyên liệu bật theo dõi tồn, số lần cảnh báo tồn thấp được kích hoạt

Tham chiếu

• URD: Kho - Nguyên vật liệu
• Liên quan: Mục kho & mức tồn · Đơn vị tính & quy đổi · Nhà cung cấp · Công thức · Lô, hạn dùng & chiến lược xuất
• Module: Kho - URD
• Developer: @nx/inventory · domain model

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Khai danh mục nguyên liệu tốn công, chủ quán bỏ dở giữa chừng	Gộp nguyên liệu, tồn nhiều địa điểm và nhà cung cấp vào một lần lưu (FR-006); đội vận hành hỗ trợ dựng danh mục ban đầu khi mở quán
02	Chủ quán bật cho bán âm cho mọi nguyên liệu cho tiện, làm số tồn mất ý nghĩa	Cờ mặc định tắt, bật theo từng nguyên liệu chứ không bật cả kho (FR-003)
03	Bật theo lô cho nguyên liệu không cần lô làm việc nhập hàng nặng thêm	Cờ theo lô mặc định tắt, chỉ bật cho nguyên liệu thật sự cần truy vết (FR-003)
04	Tắt theo dõi tồn cho một nguyên liệu đang có tồn làm mất số tồn đang có	Hệ thống hỏi lại trước khi bỏ phần tồn kho khỏi nguyên liệu (FR-007)
05	Sửa cấu hình kho của một nguyên liệu đã lưu trữ làm sai lệch số liệu lịch sử	Nguyên liệu lưu trữ bị khóa sửa, muốn sửa phải kích hoạt lại trước (FR-012)
06	Ngưỡng tồn thấp mặc định 5 đơn vị gốc không hợp với mọi nguyên liệu (5 lít sữa khác 5 gam trà)	Mở: cho merchant đặt ngưỡng mặc định chung của riêng mình, thay vì con số cứng của hệ thống
07	Giá mua khởi tạo khai tay có thể sai lệch nhiều so với giá nhập thật	Con số này chỉ dùng làm giá vốn xuất phát, bị thay bằng giá nhập thật ngay từ lần nhận hàng đầu tiên (FR-008)

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Nguyên vật liệu khác gì sản phẩm?	Sản phẩm là thứ bán cho khách. Nguyên vật liệu là thứ dùng để làm ra sản phẩm và không bán trực tiếp. Về mặt kho thì cả hai giống nhau: đều là mục kho, đều có bốn con số tồn, đều nhập bằng đơn mua hàng.
02	Có bắt buộc phải theo dõi tồn cho mọi nguyên liệu không?	Không. Mỗi nguyên liệu tự mang cờ theo dõi tồn của nó. Tắt cờ thì nguyên liệu vẫn nằm trong danh mục và vẫn dùng được trong công thức, chỉ là bán món không trừ tồn của nó.
03	Tại sao nguyên liệu không có ô "nhà cung cấp"?	Vì một nguyên liệu thường mua được từ nhiều nơi, mỗi nơi một giá và một số lượng đặt tối thiểu. Một ô duy nhất trên nguyên liệu không chứa nổi chuyện đó. Liên kết nằm ở bảng giá nhà cung cấp, mỗi cặp nhà cung cấp và nguyên liệu là một dòng.
04	Khai "số ngày hạn dùng" để làm gì?	Để hệ thống tự tính ngày hết hạn cho lô hàng khi nhận về. Khai 7 ngày cho sữa tươi thì lô sữa nhận hôm nay tự mang hạn dùng 7 ngày sau, chủ quán không phải gõ tay từng lô.
05	Bật "cho bán âm" thì tồn âm có sao không?	Về phía bán hàng thì không, quầy vẫn bán được. Nhưng tồn âm nghĩa là số trên hệ thống đã lệch thực tế, và kỳ kiểm kê tới kéo nó về đúng.
06	Ba vai đơn vị dùng lúc nào?	Đơn vị gốc dùng để lưu tồn, luôn luôn. Đơn vị mua hiện sẵn khi lập đơn mua hàng. Đơn vị bán hiện sẵn khi khai định lượng công thức. Mua một thùng sữa 24 lon, tồn vẫn được lưu theo lon, và công thức vẫn tính theo ml.
07	Sửa được số lượng tồn ở màn nguyên liệu không?	Không. Số lượng chỉ đổi qua nhận hàng, bán hàng, chuyển kho hoặc kiểm kê, để mọi con số tồn đều truy được về một chứng từ. Riêng lần khai tồn ban đầu lúc tạo nguyên liệu là ngoại lệ được phép.