PRD: Kiểm kê

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

Kiểm kê là gì

Phiếu kiểm kê (Stock Count) là chứng từ ghi lại một lần merchant đối chiếu sổ sách với hàng thật trên kệ: đếm được bao nhiêu, lệch bao nhiêu so với sổ, và lệch vì lý do gì.

Người vận hành mở phiếu cho đúng một kho (InventoryLocation) tại trang Client. Phiếu thuộc về chi nhánh (Merchant) đang làm việc; các chi nhánh khác trong cùng tổ chức (Organizer) không thấy phiếu đó. Kiểm kê là một trong chín loại phiếu kho và dùng chung vòng đời của khung phiếu: Nháp → Đang thực hiện → Hoàn tất, hiển thị bằng chữ của nghề là Nháp, Đang đếm, Đã áp.

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ữ

Kiểm kê chỉ đụng tới thực có. Mốc chụp lúc mở phiếu là số thực có, và chênh lệch được cộng vào thực có lúc áp.

Vì sao không lấy số đếm ghi đè thẳng lên tồn

Merchant không đóng cửa để đếm được. Khách vẫn tới, đơn vẫn chạy, hàng vẫn về. Người kiểm bắt đầu đếm lúc 8 giờ sáng, xong lúc 11 giờ trưa, và trong ba tiếng đó quán đã bán ra vài chục món.

Cách làm phổ biến trên thị trường là lấy số đếm ghi đè thẳng lên tồn. Cách đó chỉ đúng khi merchant đóng cửa. Khi vẫn bán song song, nó nuốt phần hàng đã bán hợp lệ vào con số hao hụt, hoặc ngược lại, dựng lại tồn cho hàng vừa mới bán ra. Hầu hết phần mềm giải bằng cách nói với người dùng: có phát sinh giao dịch thì kiểm kê lại từ đầu.

BANA giải bài này ở tầng phần mềm. Lúc mở phiếu, hệ thống chụp một mốc số sổ. Việc bán hàng tiếp tục chạy trên tồn thật. Lúc áp kết quả, hệ thống chỉ áp phần chênh lệch giữa số đếm và mốc, lên tồn hiện tại.

Một phiếu kiểm, từ đầu tới cuối

Mặt hàng đang có 100 hộp trên sổ. Mở phiếu kiểm, quán vẫn bán trong lúc đếm, và người kiểm đếm được 80.

Việc xảy ra	Mốc số sổ	Thực có kho	Số đếm	Chênh lệch
Mở phiếu kiểm cho kho A	100	100	chưa đếm	-
Thu ngân bán 5 hộp trên POS	100	95	chưa đếm	-
Người kiểm đếm được 80, nhập vào phiếu	100	95	80	-20
Áp kết quả	100	75	80	đã áp

• Chênh lệch là 80 trừ 100, bằng -20. So với mốc, không so với tồn hiện tại.
• -20 được cộng vào tồn tại thời điểm áp là 95, ra 75.
• 5 hộp bán hợp lệ được giữ nguyên. Chỉ 20 hộp thất thoát thật đi vào sổ biến động, kèm lý do người duyệt chọn.
• Ghi đè thẳng tồn thành 80 thì 5 hộp đã bán sẽ được dựng lại trong kho, và con số hao hụt sai đúng 5 hộp.
• Mặt hàng này có giao dịch phát sinh giữa lúc chụp mốc và lúc áp, nên dòng của nó mang cờ "Có biến động trong lúc đếm" để người duyệt nhìn kỹ trước khi bấm.

Chỗ dễ sai nhất

Kiểm kê áp CHÊNH LỆCH, không bao giờ ghi đè con số tồn

Số đếm của người kiểm không phải là số tồn mới. Nó là số hàng có trên kệ tại lúc họ đếm.

Hệ thống lấy số đếm trừ mốc ra chênh lệch, rồi cộng chênh lệch đó vào tồn tại thời điểm áp. Đặt thẳng tồn bằng số đếm là xóa mất mọi giao dịch đã xảy ra trong lúc đếm.

Phiếu đã áp là chốt: không sửa, không xóa. Đếm sai thì mở một phiếu kiểm mới, chụp mốc mới, và ghi một dòng điều chỉnh mới. Đúng theo luật chỉ-ghi-thêm của khung phiếu kho.

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

Mục tiêu

• Mở phiếu kiểm kê cho một kho với phạm vi chọn được, và chụp mốc số sổ của từng mặt hàng trong phạm vi ngay tại thời điểm mở.
• Chạy phiếu kiểm kê trên đúng vòng đời của khung phiếu kho, chỉ đi phần mình cần và đổi chữ hiển thị cho hợp nghề.
• Giữ cho việc bán hàng, nhập hàng và chuyển kho chạy bình thường trong suốt lúc phiếu kiểm còn mở.
• Cho merchant một cờ chặn bán bật theo từng phiếu, mặc định tắt, dùng cho hàng giá trị cao.
• Áp kết quả kiểm kê theo chênh lệch so với mốc, lên tồn tại thời điểm áp, không ghi đè số đếm lên tồn.
• Đánh dấu những mặt hàng có biến động trong lúc đếm để người duyệt xem lại trước khi áp.
• Ghi mỗi chênh lệch vào sổ biến động thành một dòng điều chỉnh có lý do, làm nguồn cho báo cáo hao hụt.
• Hỗ trợ kiểm luân phiên theo nhóm phân loại ABC.
• Giữ phiếu đã áp là chốt, đúng luật chỉ-ghi-thêm của khung phiếu kho.

Loại trừ

• Cách tính phân loại ABC (cơ sở usage value, ngưỡng 80/15/5 cấu hình được) thuộc Bổ sung hàng. PRD này chỉ dùng nhóm ABC do feature đó cung cấp làm bộ lọc phạm vi.
• Khung vòng đời chung của phiếu kho, quan hệ cha-con và luật chỉ-ghi-thêm ở mức chung, thuộc Phiếu kho.
• Cấu trúc dòng sổ biến động và bộ mã lý do, thuộc Sổ biến động.
• Giá vốn của phần chênh lệch và ảnh hưởng tiền, thuộc Giá vốn.
• Đếm bằng máy quét mã vạch cầm tay và nhập số đếm ngoại tuyến.
• Kiểm kê tài sản cố định, dụng cụ và những thứ không nằm trong danh mục mục kho.

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

Thước đo	Mục tiêu / tín hiệu
Kiểm kê không cần đóng cửa	Merchant hoàn tất một phiếu kiểm kê trong giờ mở cửa mà không phải tạm ngưng POS
Độ đúng của tồn sau khi áp	Tồn sau khi áp bằng tồn hiện tại cộng chênh lệch; hàng bán ra trong lúc đếm không xuất hiện trong con số hao hụt
Không phải đếm lại	Số phiếu kiểm bị hủy giữa chừng vì có giao dịch phát sinh giảm dần về 0
Chất lượng dữ liệu hao hụt	Mọi chênh lệch đều có lý do được chọn; báo cáo hao hụt đọc thẳng từ sổ biến động
Kiểm luân phiên	Tần suất kiểm nhóm A tăng dần so với kiểu kiểm toàn kho một lần mỗi năm

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Owner / Manager	Mở phiếu kiểm, chọn phạm vi, xem chênh lệch, chọn lý do cho phần lệch rồi áp kết quả
Nhân viên kho	Cầm phiếu đi một vòng kệ, nhập số đếm thực tế cho từng dòng
Cashier	Tiếp tục bán hàng bình thường trong lúc kho đang kiểm, không thấy gì khác lạ

Kịch bản cốt lõi: quản lý mở phiếu kiểm cho kho A giới hạn ở nhóm hàng A → hệ thống chụp mốc số sổ của từng mặt hàng trong phạm vi → nhân viên kho đếm và nhập số đếm trong khi quầy vẫn bán → quản lý mở phiếu xem lại, thấy vài dòng có cờ biến động, đối chiếu → chọn lý do cho các dòng lệch rồi bấm áp kết quả → tồn được cộng trừ đúng phần chênh lệch, và sổ biến động có thêm một dòng điều chỉnh cho mỗi mặt hàng lệch.

4. User Stories

#	Là một	Tôi muốn	Để
01	quản lý	mở phiếu kiểm kê mà không phải ngưng bán	quán vẫn kiếm được tiền trong lúc kiểm
02	quản lý	kết quả kiểm kê chỉ ghi nhận phần chênh lệch thật	hàng tôi bán ra trong lúc đếm không bị tính thành mất hàng
03	quản lý	khóa bán một nhóm hàng giá trị cao trong lúc đếm	số đếm của nhóm đó chắc chắn không đổi giữa chừng
04	quản lý	nhìn thấy mặt hàng nào có giao dịch phát sinh trong lúc đếm	tôi biết dòng nào cần nhìn kỹ trước khi áp
05	nhân viên kho	chỉ phải nhập số tôi đếm được	không phải tự tính chênh lệch trên giấy
06	quản lý	mỗi phần lệch đều có lý do	cuối tháng tôi biết mình mất hàng vì hỏng, vì hết hạn, hay vì đếm sai
07	quản lý	kiểm luân phiên nhóm hàng quan trọng nhiều lần trong năm	không phải đóng kho đếm tất cả một lần
08	quản lý	biết chắc không ai sửa lại một phiếu kiểm đã áp	lịch sử hao hụt của tôi không bị viết lại

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Người dùng tạo một phiếu kiểm kê cho đúng một kho (InventoryLocation) tại trang Client. • Form tạo phiếu có các ô: kho (bắt buộc), tên phiếu (tùy chọn, để trống thì lấy theo ngày), phạm vi kiểm (bắt buộc), ghi chú (tùy chọn). • Phạm vi kiểm chọn một trong ba kiểu: Toàn bộ kho, Theo nhóm ABC, Chọn tay danh sách mặt hàng. • Phiếu tạo xong sinh sẵn các dòng kiểm, mỗi mặt hàng trong phạm vi một dòng.	🚧	URD-CNT-001 · URD-CNT-011
FR-002	Ngay tại thời điểm tạo phiếu, hệ thống chụp số thực có hiện tại của từng mặt hàng trong phạm vi và ghi vào dòng kiểm làm mốc. • Mốc được ghi kèm thời điểm chụp và không đổi trong suốt vòng đời phiếu. • Trên mỗi dòng, người dùng thấy hai con số tách bạch: Số sổ lúc chụp và Số đếm thực tế.	🚧	URD-CNT-001
FR-003	Mở phiếu kiểm kê không chặn bất kỳ nghiệp vụ nào. • Bán hàng, nhập hàng và chuyển kho vẫn chạy bình thường suốt lúc phiếu kiểm còn mở. • Chặn bán chỉ xảy ra khi merchant chủ động bật cờ chặn bán ở FR-004.	🚧	URD-CNT-002
FR-004	Mỗi phiếu kiểm có một cờ chặn bán riêng, hiển thị trên form tạo phiếu, mặc định TẮT. • Bật cờ này thì mọi mặt hàng trong phạm vi phiếu bị chặn bán tại POS cho tới khi phiếu được áp hoặc hủy. • Thu ngân bấm phải mặt hàng đang bị chặn thì thấy thông báo "Mặt hàng đang kiểm kê, tạm ngưng bán". • Cờ chỉ đổi được khi phiếu chưa áp kết quả.	🚧	URD-CNT-003
FR-005	Người kiểm nhập số đếm thực tế cho từng dòng của phiếu, một dòng một mặt hàng. • Số đếm nhập theo đơn vị gốc của mặt hàng, không âm. • Dòng chưa nhập số đếm được đánh dấu Chưa đếm và không tính vào chênh lệch khi áp. • Hệ thống hiện ngay cột Chênh lệch bằng số đếm trừ số sổ lúc chụp, để người kiểm thấy dòng nào lệch.	🚧	URD-CNT-004
FR-006	Phiếu kiểm kê dùng chung vòng đời của khung phiếu kho, chỉ đi phần mình cần và đổi chữ hiển thị. • Ba bước: Nháp → Đang thực hiện → Hoàn tất. Không có bước duyệt riêng và không có trạng thái nào nằm ngoài vòng đời chung. • Trên màn hình, Đang thực hiện hiện là "Đang đếm" và Hoàn tất hiện là "Đã áp". • Tồn kho chỉ thay đổi ở bước cuối; hai bước trước không đụng tới tồn. • Hủy phiếu ở bất kỳ bước nào trước bước cuối thì không để lại thay đổi tồn nào, và cờ chặn bán được gỡ.	🚧	URD-CNT-009 · URD-TKT-003 · URD-TKT-004
FR-007	Áp kết quả tính theo chênh lệch so với mốc, không ghi đè số đếm lên tồn. • Chênh lệch của một dòng bằng số đếm trừ số sổ đã chụp lúc tạo phiếu. • Chênh lệch được cộng vào thực có tại đúng thời điểm áp kết quả, không phải tồn tại thời điểm chụp mốc. • Dòng có chênh lệch bằng 0 không sinh thay đổi tồn nào.	🚧	URD-CNT-005
FR-008	Mỗi dòng có chênh lệch khác 0 được ghi vào sổ biến động thành một dòng điều chỉnh riêng. • Dòng sổ ghi rõ trước bao nhiêu, đổi bao nhiêu, sau bao nhiêu, và trỏ ngược về phiếu kiểm là chứng từ nguồn. • Người duyệt chọn lý do cho phần lệch từ danh sách: Hàng hỏng, Hàng hết hạn, Mất hàng, Đếm sai kỳ trước, Lý do khác. • Chọn Lý do khác thì bắt buộc điền ghi chú.	🚧	URD-CNT-006
FR-009	Mặt hàng có bán, nhập hoặc chuyển kho phát sinh trong khoảng từ lúc chụp mốc tới lúc áp kết quả được đánh cờ biến động. • Dòng có cờ hiện nhãn "Có biến động trong lúc đếm" ngay trên phiếu. • Người duyệt bung được dòng đó ra xem những giao dịch nào đã phát sinh, để đối chiếu trước khi áp. • Cờ biến động là cảnh báo để nhìn, không chặn việc áp kết quả.	🚧	URD-CNT-007
FR-010	Phiếu kiểm giới hạn phạm vi theo nhóm phân loại ABC, phục vụ kiểm luân phiên. • Chọn phạm vi Theo nhóm ABC rồi tick một hoặc nhiều nhóm A, B, C. Phiếu chỉ sinh dòng cho mặt hàng thuộc các nhóm đã chọn. • Màn danh sách phiếu kiểm hiện lần kiểm gần nhất của từng nhóm, để merchant biết nhóm nào tới hạn kiểm.	🚧	URD-CNT-008
FR-011	Một mặt hàng xuất hiện trong nhiều phiếu kiểm khác nhau theo thời gian, mỗi phiếu chụp mốc độc lập. • Mốc của phiếu này không phụ thuộc kết quả của phiếu trước. • Một mặt hàng đang nằm trong một phiếu kiểm chưa áp mà bị đưa vào phiếu kiểm thứ hai thì hệ thống cảnh báo trùng phạm vi ngay lúc tạo phiếu, và người dùng chọn tiếp tục hoặc bỏ mặt hàng đó ra.	🚧	URD-CNT-010 · URD-CNT-012
FR-012	Phiếu kiểm đã áp là chốt, đúng luật chỉ-ghi-thêm của khung phiếu kho. • Mọi ô nhập bị khóa: không sửa lại số đếm, không sửa lý do, không có nút xóa phiếu. • Đếm sai thì mở một phiếu kiểm mới cho mặt hàng đó. Phiếu mới chụp mốc mới theo tồn hiện tại và ghi một dòng điều chỉnh mới vào sổ.	🚧	URD-CNT-014 · URD-TKT-008
FR-013	Phiếu kiểm kê là dữ liệu riêng của từng chi nhánh (Merchant) và tra cứu được bằng bộ lọc. • Người dùng chỉ thấy và thao tác trên phiếu kiểm thuộc chi nhánh mình đang làm việc. • Danh sách phiếu kiểm lọc được theo kho, trạng thái phiếu và khoảng ngày tạo.	🚧	URD-CNT-013 · URD-TKT-017

5.1 Tiêu chí nghiệm thu

• Mở màn Kiểm kê tại trang Client, bấm Tạo phiếu, chọn kho A và phạm vi Toàn bộ kho → phiếu được tạo với đầy đủ dòng kiểm, mỗi mặt hàng của kho A một dòng, cột Số sổ lúc chụp đã điền sẵn.
• Tạo phiếu kiểm với phạm vi Chọn tay và tick đúng 3 mặt hàng → phiếu sinh đúng 3 dòng kiểm, không có mặt hàng nào khác của kho.
• Tạo phiếu kiểm mà để trống ô tên phiếu → phiếu vẫn tạo được và tên phiếu tự lấy theo ngày tạo.
• Ngay sau khi tạo phiếu, bán ra 5 đơn vị một mặt hàng trên POS → tồn giảm còn 95, nhưng cột Số sổ lúc chụp trên dòng kiểm vẫn giữ nguyên 100.
• Với phiếu kiểm đang mở và cờ chặn bán TẮT, bán một mặt hàng trong phạm vi phiếu trên POS → đơn hàng đi qua bình thường, không có thông báo chặn nào.
• Nhập một chuyến hàng và chuyển kho một mặt hàng đang nằm trong phạm vi phiếu kiểm → cả hai nghiệp vụ chạy bình thường, phiếu kiểm không chặn gì.
• Tạo một phiếu kiểm mới và bật cờ chặn bán, rồi bấm mặt hàng trong phạm vi phiếu vào giỏ trên POS → thấy thông báo "Mặt hàng đang kiểm kê, tạm ngưng bán" và món không vào được giỏ; hủy phiếu kiểm → bán lại được ngay.
• Nhập số đếm 80 cho một dòng có Số sổ lúc chụp là 100 → cột Chênh lệch trên dòng đó hiện -20 ngay lập tức.
• Để trống số đếm của một dòng rồi áp kết quả → dòng đó giữ nhãn Chưa đếm, tồn của mặt hàng đó không thay đổi.
• Mở một phiếu kiểm bất kỳ → màn hình có nút Bắt đầu đếm rồi tới nút Áp kết quả, không có bước duyệt riêng và không có nút nào nằm ngoài vòng đời phiếu kho.
• Mở danh sách phiếu → phiếu đang đếm hiện chữ "Đang đếm", phiếu đã áp hiện chữ "Đã áp".
• Phiếu đang ở bước Đang đếm, kiểm tra tồn của một mặt hàng trong phạm vi → tồn chưa đổi vì kết quả chưa được áp.
• Mốc chụp 100, trong lúc đếm bán ra 5 (tồn hiện tại 95), số đếm nhập 80 → áp kết quả → tồn của mặt hàng thành 75, không phải 80.
• Sau khi áp phiếu ở bước trên, mở sổ biến động của mặt hàng đó → thấy một dòng điều chỉnh mới ghi trước 95, đổi -20, sau 75, kèm lý do đã chọn và trỏ về đúng mã phiếu kiểm.
• Chọn lý do Lý do khác cho một dòng lệch mà bỏ trống ghi chú rồi bấm áp → hệ thống chặn và yêu cầu điền ghi chú.
• Bán một mặt hàng trong phạm vi sau khi phiếu kiểm đã mở, rồi mở lại phiếu để xem trước khi áp → dòng của mặt hàng đó hiện nhãn "Có biến động trong lúc đếm"; bấm bung dòng → thấy danh sách giao dịch đã phát sinh kể từ lúc chụp mốc.
• Một mặt hàng không có giao dịch nào phát sinh kể từ lúc chụp mốc → dòng của nó không hiện nhãn biến động.
• Một dòng có cờ biến động → nút Áp kết quả vẫn bấm được, cờ không chặn.
• Tạo phiếu kiểm với phạm vi Theo nhóm ABC và tick nhóm A → phiếu chỉ sinh dòng cho các mặt hàng nhóm A, không có mặt hàng nhóm B hay C.
• Ở màn danh sách phiếu kiểm, xem cột lần kiểm gần nhất theo nhóm → thấy ngày áp phiếu gần nhất của từng nhóm A, B, C.
• Đưa một mặt hàng đang nằm trong phiếu kiểm chưa áp vào một phiếu kiểm thứ hai → thấy cảnh báo trùng phạm vi kèm mã phiếu đang mở, và có hai lựa chọn tiếp tục hoặc bỏ mặt hàng đó ra khỏi phiếu mới.
• Chọn tiếp tục → phiếu thứ hai chụp mốc riêng theo tồn hiện tại, không phụ thuộc mốc của phiếu thứ nhất.
• Hủy một phiếu kiểm đang ở bước Đang đếm → tồn của mọi mặt hàng trong phạm vi giữ nguyên, sổ biến động không có dòng nào mới, và cờ chặn bán được gỡ.
• Mở phiếu kiểm đã áp → mọi ô nhập bị khóa, không sửa được số đếm hay lý do, và không có nút xóa phiếu.
• Phát hiện đếm nhầm sau khi đã áp → mở một phiếu kiểm mới cho mặt hàng đó, phiếu mới chụp mốc mới và sinh một dòng điều chỉnh mới; phiếu cũ giữ nguyên.
• Ở màn danh sách phiếu kiểm, lọc theo kho A, trạng thái Đang đếm và khoảng ngày của tuần này → danh sách chỉ hiện đúng các phiếu khớp cả ba điều kiện.
• Đăng nhập bằng tài khoản của merchant khác → không thấy phiếu kiểm nào của merchant đầu tiên trong danh sách.

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

Khía cạnh	Yêu cầu
Toàn vẹn dữ liệu	Mốc số sổ ghi trên dòng kiểm là bất biến sau khi phiếu được tạo; việc áp kết quả cho toàn phiếu là một lần ghi trọn gói - hoặc mọi dòng lệch đều vào sổ, hoặc không dòng nào vào sổ
Tính đúng dưới đồng thời	Việc cộng chênh lệch vào tồn chạy đồng thời với luồng bán hàng mà không mất số: hai luồng cùng đụng một mặt hàng thì kết quả cuối bằng tổng đại số của cả hai, không phải giá trị của luồng ghi sau
Chống ghi trùng	Bấm áp kết quả hai lần cho cùng một phiếu chỉ ghi sổ một lần
Chỉ ghi thêm	Không có đường nào trong nghiệp vụ sửa hoặc xóa một phiếu kiểm đã áp
Phân quyền theo merchant	Mọi phiếu kiểm và dòng kiểm được giới hạn trong chi nhánh của chính người dùng
Hiệu năng / quy mô	Một phiếu kiểm chứa tới 5.000 dòng; việc chụp mốc lúc tạo phiếu và việc áp kết quả đều chạy theo lô, không phải một lượt gọi cho mỗi dòng
Truy vết	Mỗi dòng điều chỉnh trong sổ biến động trỏ ngược về đúng mã phiếu kiểm, người áp và thời điểm áp
i18n	Nhãn trạng thái phiếu, nhãn lý do và thông báo chặn bán là song ngữ

7. UX & Luồng

Vòng đời một phiếu kiểm và chỗ tồn kho thực sự thay đổi:

Vì sao bán song song không bị nuốt thành hao hụt:

Toàn bộ màn hình kiểm kê nằm ở trang Client, trong mục Kho. Một màn danh sách phiếu kiểm có bộ lọc theo kho, trạng thái và khoảng ngày. Một màn chi tiết phiếu dạng bảng, mỗi dòng một mặt hàng, các cột Mặt hàng, Đơn vị gốc, Số sổ lúc chụp, Số đếm thực tế, Chênh lệch, Lý do, cùng nhãn biến động khi có. Nút Áp kết quả nằm ở đầu màn chi tiết và chỉ bật khi phiếu đang ở bước Đang đếm.

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

Khái niệm	Vai trò
Phiếu kiểm kê	Một loại phiếu kho: một kho, một phạm vi, một cờ chặn bán, ba bước của vòng đời chung
Dòng kiểm	Một mặt hàng trong phiếu, mang số sổ lúc chụp, số đếm thực tế, chênh lệch, lý do và cờ biến động
Mốc số sổ	Số thực có của mặt hàng tại thời điểm mở phiếu, bất biến, dùng làm gốc so sánh
Chênh lệch	Số đếm thực tế trừ mốc số sổ; đây là con số duy nhất được áp lên tồn
Cờ chặn bán	Thuộc tính của phiếu, mặc định tắt; bật thì mặt hàng trong phạm vi phiếu tạm ngưng bán
Cờ biến động	Dấu trên dòng kiểm khi mặt hàng có giao dịch phát sinh kể từ lúc chụp mốc
Dòng điều chỉnh	Bản ghi trong sổ biến động sinh ra khi áp kết quả, mang lý do và trỏ về phiếu kiểm
Nhóm ABC	Phân loại mặt hàng theo mức độ quan trọng, dùng làm bộ lọc phạm vi cho kiểm luân phiên

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	TKT Phiếu kho	vòng đời chung, nhãn trạng thái theo loại phiếu, và luật chỉ-ghi-thêm.
02	LOC Địa điểm kho	phiếu kiểm luôn gắn với đúng một kho.
03	STK Mục kho & mức tồn	nguồn của số thực có lúc chụp mốc, và là nơi chênh lệch được áp vào.
04	LDG Sổ biến động	nơi dòng điều chỉnh được ghi, và là nguồn để phát hiện mặt hàng có biến động trong lúc đếm.
05	RSV Giữ tồn	cờ chặn bán của phiếu tác động lên đường giữ tồn tại POS.
06	RPL Bổ sung hàng	cung cấp nhóm phân loại ABC dùng làm bộ lọc phạm vi.
07	UOM Đơn vị tính & quy đổi	định nghĩa đơn vị gốc mà người kiểm nhập số đếm theo.

Giả định

#	Giả định	Sai thì sao
01	Người kiểm đếm theo đơn vị gốc của mặt hàng. Việc quy đổi từ đơn vị đóng gói sang đơn vị gốc do người kiểm tự làm trước khi nhập số.	Người kiểm gõ số thùng vào ô đang chờ số lon thì chênh lệch sai theo bội số quy đổi, và một phiếu kiểm sai làm hỏng tồn của cả kho.
02	Chênh lệch kiểm kê là hao hụt hoặc thừa thật, không phải sai sót do đơn vị tính. Số lệch bất thường thì người áp đối chiếu trước khi bấm.	Người áp bấm không nhìn thì mọi sai sót nhập liệu đi thẳng vào sổ biến động dưới nhãn hao hụt, và báo cáo hao hụt mất hết giá trị.
03	Một mặt hàng chỉ nên nằm trong một phiếu kiểm chưa áp tại một thời điểm. Hệ thống cảnh báo khi trùng nhưng không cấm.	Hai phiếu cùng phủ một mặt hàng và cả hai cùng áp thì tồn bị kéo hai lần theo hai mốc khác nhau, và người dùng không lần ra được phiếu nào gây ra con số cuối.
04	Nhóm phân loại ABC đã được tính sẵn trước khi merchant dùng phạm vi kiểm theo nhóm.	Nhóm ABC chưa được tính thì phạm vi Theo nhóm ABC sinh ra phiếu trống hoặc phiếu thiếu mặt hàng, và kiểm luân phiên không dùng được.

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

Khía cạnh	Kế hoạch
Phase	P2 (Kho v2) - xem danh mục feature URD
Rollout	Mọi merchant; không feature flag. Cờ chặn bán là lựa chọn của từng phiếu, không phải cấu hình cấp merchant
Migration	Không có dữ liệu kiểm kê cũ để chuyển; phiếu kiểm đầu tiên của mỗi merchant chụp mốc từ tồn hiện tại
Tiêu chí phát hành	Phiếu kiểm chạy đúng ba bước của vòng đời phiếu kho với đúng chữ hiển thị; kịch bản mốc 100 - bán 5 - đếm 80 ra tồn 75 chạy đúng; cờ chặn bán bật tắt đúng ở POS; mọi chênh lệch có lý do và có dòng trong sổ biến động; phiếu đã áp không sửa được; phiếu 5.000 dòng tạo và áp được
Theo dõi	Số phiếu kiểm hoàn tất mỗi tháng, tỉ lệ dòng có cờ biến động, tổng giá trị chênh lệch theo lý do, số phiếu bị hủy giữa chừng

Tham chiếu

• URD: Kiểm kê
• Liên quan: Phiếu kho · Mục kho & mức tồn · Sổ biến động · Chuyển kho · Bổ sung hàng
• 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	Ghi đè số đếm lên tồn sẽ nuốt phần hàng bán ra trong lúc đếm thành hao hụt giả	Áp kết quả tính theo chênh lệch so với mốc, lên tồn hiện tại (FR-007)
02	Người áp bấm mà không biết mặt hàng vừa có giao dịch phát sinh	Cờ biến động hiện ngay trên dòng, bung ra xem được danh sách giao dịch (FR-009)
03	Phiếu kiểm mở quá lâu thì chênh lệch càng khó giải thích vì càng nhiều giao dịch chen vào	Mở: cân nhắc cảnh báo khi phiếu mở quá một số ngày cấu hình được, hoặc gợi ý chốt phiếu trong ngày
04	Cờ chặn bán bị bỏ quên bật khiến merchant không bán được hàng	Hủy hoặc áp phiếu là gỡ cờ ngay (FR-006); màn danh sách phiếu hiện rõ phiếu nào đang chặn bán
05	Hai phiếu kiểm cùng phủ một mặt hàng thì phần chênh lệch có thể bị áp hai lần	Cảnh báo trùng phạm vi ngay lúc tạo phiếu (FR-011); mỗi phiếu vẫn tính theo mốc riêng nên chênh lệch không nhân đôi, nhưng đây là tình huống cần người dùng xác nhận
06	Mặt hàng có bật cho bán âm thì tồn có thể âm và số đếm không bao giờ khớp mốc	Chênh lệch vẫn tính bình thường; phần âm được kéo về đúng con số đếm được sau khi áp
07	Giá trị tiền của phần chênh lệch chưa được nêu trong phiếu	Mở: quyết định có hiển thị giá trị hao hụt theo giá vốn ngay trên phiếu kiểm hay để dành cho báo cáo hao hụt

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

#	Câu hỏi	Trả lời
01	Đang kiểm kê thì merchant có phải ngưng bán không?	Không. Mở phiếu kiểm không chặn gì cả: quầy vẫn bán, hàng vẫn nhập, kho vẫn chuyển. Chặn bán chỉ xảy ra khi merchant chủ động bật cờ chặn bán trên phiếu, và cờ đó mặc định tắt.
02	Vậy chụp mốc số sổ để làm gì, nếu không phải để đóng băng tồn?	Chụp mốc là để có một gốc so sánh. Số đếm của người kiểm phản ánh kệ hàng tại thời điểm họ đếm, còn tồn trong hệ thống thì vẫn chạy. Có mốc thì hệ thống mới tách được đâu là phần thất thoát thật, đâu là phần đã bán ra hợp lệ.
03	Tôi đếm được 80, sao áp xong tồn lại là 75?	Vì lúc mở phiếu số sổ là 100, và trong lúc đếm quán bán ra 5 đơn vị. Chênh lệch là 80 trừ 100 bằng -20, đó là phần thất thoát. Tồn hiện tại lúc áp là 95, trừ đi 20, còn 75. Nếu hệ thống đặt thẳng tồn thành 80 thì 5 đơn vị đã bán sẽ được dựng lại trong kho.
04	Kiểm kê có phải là một loại phiếu kho không?	Có. Nó dùng đúng vòng đời của khung phiếu kho, chỉ đi ba bước và đổi chữ hiển thị cho hợp nghề: bước Đang thực hiện gọi là "Đang đếm", bước Hoàn tất gọi là "Đã áp". Không có vòng đời riêng nào cả.
05	Khi nào nên bật cờ chặn bán?	Khi kiểm nhóm hàng giá trị cao mà merchant muốn con số đếm chắc chắn không đổi giữa chừng, ví dụ tủ rượu hoặc hàng điện tử. Với hàng chạy nhanh thì không nên bật, vì chặn bán là mất doanh thu.
06	Kiểm luân phiên theo nhóm ABC nghĩa là gì?	Thay vì đóng kho đếm toàn bộ mỗi năm một lần, merchant kiểm nhóm A (hàng quan trọng nhất) thường xuyên, nhóm B thưa hơn, nhóm C hiếm. Phiếu kiểm cho phép chọn phạm vi theo nhóm, nên mỗi lần chỉ đếm một phần kho.
07	Cờ "Có biến động trong lúc đếm" có chặn tôi áp kết quả không?	Không. Nó chỉ là dấu nhắc nhìn kỹ dòng đó, vì con số của dòng đó chịu ảnh hưởng của giao dịch phát sinh. Bấm bung dòng ra là thấy đúng những giao dịch nào đã chạy.
08	Áp kết quả xong tôi phát hiện đếm sai thì sao?	Phiếu đã áp là chốt: không sửa, không xóa. Sửa sai bằng cách mở một phiếu kiểm mới cho mặt hàng đó. Phiếu mới chụp mốc mới, và chênh lệch mới lại được ghi thành một dòng điều chỉnh riêng trong sổ. Đây đúng là luật chỉ-ghi-thêm của cả module Kho.