URD: Kho

Module	CORE-06	Phiên bản	v0.6
Trạng thái	In-progress	Ngày	2026-06-15

Tài liệu nghiệp vụ. URD này chính là danh sách tính năng của Kho - mỗi tính năng bên dưới là một Vùng chức năng (<AREA>). Cùng mã <AREA> đó key cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

1. Mục đích

Định nghĩa yêu cầu hướng người dùng cho quản lý Kho - theo dõi tồn, địa điểm kho, đơn mua hàng, vendor, nguyên vật liệu (BOM), phiếu kho, và một audit trail đầy đủ, bất biến của mọi biến động tồn. Kết quả là một merchant luôn biết họ có gì, nó ở đâu, và nó đến đó như thế nào.

2. Phạm vi

Bao gồm	Loại trừ
Địa điểm kho với phân cấp	Báo giá bán / đặt giữ theo quota
Mục kho (biến thể/nguyên vật liệu liên kết với địa điểm)	BOM đa cấp / cụm lắp ráp con
Số lượng tồn (on-hand, reserved, available)	Phần trăm hao hụt và sản lượng công thức
Audit log tracking bất biến	Định giá tồn đa tiền tệ
Danh mục loại tracking (19 cái dựng sẵn)	Tích hợp quét barcode đầy đủ
Quản lý nhà cung cấp (vendor)	Bắt buộc tồn-âm tại POS
Đơn mua hàng với nhận hàng	Đặc tả API kỹ thuật
Phiếu kho (chuyển, điều chỉnh, kiểm kê, trả hàng, hủy bỏ)
Danh mục nguyên vật liệu với định danh
Công thức nguyên vật liệu (BOM) với phiên bản
Phân rã BOM lúc chạy trên phiếu bếp
Lệnh sản xuất, inventory rules, đơn vị đo lường

3. Định nghĩa

Thuật ngữ	Định nghĩa
Địa điểm kho (Inventory Location)	Một kho hoặc khu lưu trữ trong một merchant. Hỗ trợ phân cấp. Một mặc định mỗi merchant.
Mục kho (Inventory Item)	Một bản ghi liên kết một biến thể sản phẩm hoặc nguyên vật liệu với một merchant để theo dõi tồn.
Tồn kho (Inventory Stock)	Bản ghi số lượng - on-hand, reserved, available. Một bản ghi mỗi (mục, địa điểm, lot, serial).
Tracking kho (Inventory Tracking)	Một mục audit bất biến cho mọi biến động tồn với số lượng trước/sau.
Loại tracking kho (Inventory Tracking Type)	Phân loại hướng biến động (IN/OUT/NEUTRAL) và lý do. 19 cái dựng sẵn + 1 tùy chỉnh.
Phiếu kho (Inventory Ticket)	Một chứng từ cho thao tác tồn: chuyển, điều chỉnh, kiểm kê, trả hàng, hủy bỏ. Có line item.
Vendor	Một nhà cung cấp mà merchant mua hàng từ đó.
Đơn mua hàng (Purchase Order)	Một chứng từ nhận hàng từ một vendor, chứa line item với số lượng và giá.
Nguyên vật liệu (Material)	Một nguyên liệu thô hoặc bán thành phẩm được theo dõi tách biệt với sản phẩm bán được.
Công thức nguyên vật liệu (Material Recipe / BOM)	Một công thức có phiên bản khai báo nguyên vật liệu nào được tiêu thụ để sản xuất một biến thể sản phẩm.
Phân rã BOM (BOM Explosion)	Giảm nguyên vật liệu tự động kích hoạt bởi thay đổi trạng thái mục phiếu bếp.
Lệnh sản xuất (Production Order)	Một chứng từ sản xuất theo dõi số lượng kế hoạch/thực tế/hao hụt cho hàng được sản xuất.
Inventory Rule	Một quy tắc ngưỡng cấu hình được có thể kích hoạt cảnh báo, tạo PO, hoặc webhook.
Đơn vị đo lường (Unit of Measure)	Đơn vị đo với phạm vi 3 cấp: mặc định hệ thống → merchant → sản phẩm/nguyên vật liệu.

4. Mô hình Khái niệm

Chỉ là khái niệm - schema đầy đủ nằm trong mô hình miền lập trình viên.

5. Danh mục tính năng

Danh sách tính năng của module. Mỗi dòng là một tính năng (một Vùng chức năng). Chi tiết ở §6. Đối chiếu với danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
LOC	Địa điểm kho	P1	Built	High
ITM	Mục kho	P1	Built	High
STK	Mức tồn	P1	Built	High
TRK	Audit trail biến động	P1	Built	High
LSE	Định danh lô / serial & hạn dùng	P3	Built	High
TKT	Phiếu kho	P2	Built	High
VEN	Vendor	P1	Built	High
PO	Đơn mua hàng	P1	Built	High
POI	Mục đơn mua hàng	P1	Built	High
MAT	Nguyên vật liệu	P3	Built	High
REC	Công thức / BOM	P3	In-progress	High
PRO	Đơn sản xuất & Phân rã BOM	P3	In-progress	High
IOP	Vận hành kho - F&B & Bán lẻ	P2	Planned	High

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Một mục con cho mỗi tính năng, theo thứ tự danh mục. Mỗi tính năng giữ mô tả, yêu cầu, và nghiệm thu cùng nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

LOC - Địa điểm kho Built

Mã tính năng: inventory/LOC · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: merchant tổ chức tồn thành các kho/khu lưu trữ. Mỗi merchant tự có một địa điểm mặc định; merchant lớn hơn có thể thêm phân cấp địa điểm kèm địa chỉ và dữ liệu GPS.

Yêu cầu

ID	P	Yêu cầu
URD-LOC-001	M	Chủ có thể tạo một địa điểm kho với tên i18n.
URD-LOC-002	M	Một địa điểm mặc định được tự tạo cho mỗi merchant khi commerce init.
URD-LOC-003	M	Đúng một địa điểm mặc định tồn tại mỗi merchant; đặt mặc định mới xóa cái trước.
URD-LOC-004	S	Địa điểm hỗ trợ phân cấp cha-con.
URD-LOC-005	S	Một địa điểm có thể lưu dữ liệu địa chỉ và địa lý (GPS).
URD-LOC-006	M	Vòng đời địa điểm: NEW → ACTIVATED → DEACTIVATED → ARCHIVED (ARCHIVED là cuối).
URD-LOC-007	M	Mỗi địa điểm có một định danh do hệ thống sinh (LOC_YYYYMMDD_id), không sửa được bởi người dùng.
URD-LOC-008	M	Địa điểm dùng soft-delete; dữ liệu được giữ và admin lấy lại được.
URD-LOC-009	S	Chủ có thể liệt kê và lọc địa điểm theo trạng thái.
URD-LOC-010	M	Địa điểm được cô lập theo từng merchant.

Nghiệm thu

AC-LOC-01: Địa điểm Mặc định

Cho trước	Khi	Thì
Merchant mới	Commerce initialization	Địa điểm mặc định tự tạo
Đặt một mặc định mới	-	Mặc định trước bị xóa

ITM - Mục kho Built

Mã tính năng: inventory/ITM · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: một bản ghi theo dõi tồn được tạo tự động mỗi khi thêm một biến thể sản phẩm, liên kết vào địa điểm mặc định của merchant, kèm ngưỡng min/max tùy chọn.

Yêu cầu

ID	P	Yêu cầu
URD-ITM-001	M	Một mục kho được tự tạo khi một biến thể sản phẩm được tạo.
URD-ITM-002	M	Một mục mỗi tổ hợp (biến thể, địa điểm, đơn vị).
URD-ITM-003	S	Mục hỗ trợ ngưỡng mức tồn min/max; min ≤ max.
URD-ITM-004	M	Mỗi mục có một định danh do hệ thống sinh (SKU_YYYYMMDD_id), không sửa được bởi người dùng.
URD-ITM-005	M	Vòng đời mục: ACTIVATED → DEACTIVATED → ARCHIVED (ARCHIVED là cuối).
URD-ITM-006	M	Mục được liên kết với địa điểm mặc định của merchant khi tạo.

Nghiệm thu

AC-ITM-01: Tự tạo theo biến thể

Cho trước	Khi	Thì
Một biến thể sản phẩm mới	Biến thể được tạo	Một mục kho tự tạo tại địa điểm mặc định

STK - Mức tồn Built

Mã tính năng: inventory/STK · Phase: P1 · PRDs: Nhập tồn đầu kỳ · Dev: @nx/inventory

Làm gì cho người dùng: merchant thấy mình có bao nhiêu tồn - on-hand, reserved, available - theo từng mục từng địa điểm, với độ chính xác thập phân và cập nhật liền mạch.

Yêu cầu

ID	P	Yêu cầu
URD-STK-001	M	Một bản ghi tồn mỗi (mục, địa điểm, lot, serial).
URD-STK-002	M	Available = on-hand − reserved.
URD-STK-003	M	Mọi số lượng lưu với độ chính xác thập phân (4 chữ số).
URD-STK-004	M	Chủ có thể xem mức tồn hiện tại; biến động đầu tiên tự tạo bản ghi tồn.
URD-STK-005	S	Timestamp last-stocked / last-counted cập nhật tự động.
URD-STK-006	M	Cập nhật tồn diễn ra như một thao tác duy nhất - thất bại một phần sẽ rollback hoàn toàn.
URD-STK-007	C	Thay đổi mức tồn lịch sử xem được.

Nghiệm thu

AC-STK-01: Theo dõi Tồn

Cho trước	Khi	Thì
Mục có tồn	Xem	On-hand, reserved, available hiển thị
Available rớt dưới ngưỡng	-	Chỉ báo tồn thấp hiển thị

TRK - Audit trail biến động Built

Mã tính năng: inventory/TRK · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: mọi thay đổi tồn - nhận hàng, bán, chuyển, điều chỉnh - được ghi thành một mục bất biến với số lượng trước/thay đổi/sau, truy vết đầy đủ tới chứng từ nguồn.

Yêu cầu

ID	P	Yêu cầu
URD-TRK-001	M	Mọi biến động tồn tạo một mục tracking bất biến.
URD-TRK-002	M	Ghi số lượng trước, thay đổi, và sau.
URD-TRK-003	M	Mục từ chứng từ nghiệp vụ lưu loại tham chiếu và ID.
URD-TRK-004	M	Idempotent: cùng (referenceType, referenceId) chỉ sinh một mục.
URD-TRK-005	M	Mỗi mục có kiểu theo loại tracking (IN/OUT/NEUTRAL); 19 cái dựng sẵn + tùy chỉnh.
URD-TRK-006	S	Mục ghi người dùng thực hiện (createdBy / modifiedBy).
URD-TRK-007	M	Chủ có thể xem toàn bộ lịch sử tracking.
URD-TRK-008	S	Mục có thể ghi giá hiệu lực và multiplier.
URD-TRK-009	S	Mục thủ công có thể kèm một note/lý do.
URD-TRK-010	C	Lọc lịch sử theo ngày, loại, hoặc chứng từ tham chiếu.

Nghiệm thu

AC-TRK-01: Mục bất biến

Cho trước	Khi	Thì
Bất kỳ biến động tồn nào	Xảy ra	Một mục bất biến ghi trước/thay đổi/sau + tham chiếu
Cùng (referenceType, referenceId) chạy lại	-	Không tạo mục trùng (idempotent)

LSE - Định danh lô / serial & hạn dùng Built

Mã tính năng: inventory/LSE · Phase: P3 · PRDs: Định danh lô / serial & hạn dùng · Dev: @nx/inventory

Làm gì cho người dùng: tồn trở nên truy vết được ở dưới cấp mục. Cùng một mục ở một địa điểm tách thành các bucket riêng theo lô và theo serial, mỗi cái mang hạn dùng và ngày sản xuất riêng, trong khi một registry định danh biến một mã được quét (SKU / barcode / QR ở cấp mục, IMEI / serial ở cấp đơn vị) thành đúng một thực thể tồn.

Yêu cầu

ID	P	Yêu cầu
URD-LSE-001	M	Tồn được phân bucket theo (mục, địa điểm, lô, serial); các lô/serial khác nhau của một mục tại một địa điểm là các bản ghi tồn riêng.
URD-LSE-002	M	Mỗi bucket tồn mang một số lô, số serial, hạn dùng, và ngày sản xuất.
URD-LSE-003	M	Bucket không có lô/serial gộp thành một bản ghi (NULL bằng nhau coi là cùng bucket), nên mục không truy vết giữ một bản ghi duy nhất.
URD-LSE-004	M	Lô / serial / hạn dùng được bắt lúc nhận hàng trên line đơn mua hàng; một line theo serial ghi một serial mỗi đơn vị nhận.
URD-LSE-005	M	Line phiếu kho bắt lô / serial / hạn dùng cho stock-in và return-from-customer; một line serial phải có số lượng kế hoạch 1.
URD-LSE-006	M	Mọi biến động snapshot lô / serial / hạn dùng đã biến động vào mục tracking bất biến.
URD-LSE-007	M	Một registry định danh ghi SKU / BARCODE / QRCODE ở cấp mục và IMEI / SERIAL ở cấp đơn vị (tồn).
URD-LSE-008	M	Mỗi cặp (scheme, code) duy nhất toàn cục trên các bản ghi active - một mã phân giải về đúng một thực thể tồn.
URD-LSE-009	M	Scheme định danh mặc định UNKNOWN khi không nêu; chỉ SKU / BARCODE / QRCODE / IMEI / SERIAL được nhận diện.
URD-LSE-010	M	Định danh được scope theo merchant qua principal (mục hoặc tồn) và dùng soft-delete; soft-delete một mã giải phóng cặp (scheme, code) của nó.
URD-LSE-011	S	Hàng hết hạn được hủy qua một lý do biến động EXPIRED chuyên biệt giảm đúng lô.
URD-LSE-012	S	Một lần sản xuất có thể đóng dấu hàng thành phẩm đầu ra với số lô và hạn dùng để truy vết thu hồi.
URD-LSE-013	C	Hạn dùng và ngày sản xuất bắt theo lô hỗ trợ hiển thị sắp-hết-hạn và chọn FEFO (chỉ mô hình dữ liệu; UI vận hành xuất hiện với IOP).

Nghiệm thu

AC-LSE-01: Phân bucket lô

Given	When	Then
Hai lần nhận một mục với số lô khác nhau	Đã nhận	Tồn tại hai bucket tồn riêng, mỗi cái có hạn dùng riêng
Một mục không truy vết (không lô/serial)	Nhận hai lần	Một bucket cộng dồn - lô/serial NULL bằng nhau gộp

AC-LSE-02: Phân giải định danh duy nhất

Given	When	Then
Một (scheme, code) đã đăng ký	Được quét	Phân giải về đúng một thực thể tồn
Cùng (scheme, code) trên bản ghi khác	Lưu	Từ chối - cặp phải duy nhất trên các bản ghi active
Một mã đã đăng ký bị soft-delete	Cặp được đăng ký lại	Cho phép - soft-delete giải phóng cặp

AC-LSE-03: Biến động truy vết & hủy

Given	When	Then
Bất kỳ biến động nào của một bucket truy vết	Xảy ra	Mục tracking snapshot lô / serial / hạn dùng đã biến động
Một lô hết hạn	Hủy	Giảm qua lý do EXPIRED và ghi vào trail
Một line nhận theo serial với số lượng > 1	Lưu	Từ chối - một line serial phải đúng một đơn vị

TKT - Phiếu kho Built

Mã tính năng: inventory/TKT · Phase: P2 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: thao tác kho chạy qua phiếu - chuyển giữa các địa điểm, điều chỉnh tồn, kiểm kê, trả hàng, và hủy bỏ - mỗi phiếu qua một quy trình duyệt trước khi chạm vào tồn.

Yêu cầu

ID	P	Yêu cầu
URD-TKT-001	M	Phiếu hỗ trợ 6 loại thao tác: Chuyển, Điều chỉnh, Kiểm kê, Trả về Vendor, Trả từ Khách hàng, Hủy bỏ/Tiêu hủy.
URD-TKT-002	M	Vòng đời: DRAFT → SUBMITTED → APPROVED → IN_PROGRESS → COMPLETED / CANCELLED.
URD-TKT-003	M	Mỗi phiếu có line item với số lượng kế hoạch vs. thực tế.
URD-TKT-004	M	Hoàn tất một phiếu tạo mục tracking và cập nhật tồn.
URD-TKT-005	S	Line item hỗ trợ số lot/serial.
URD-TKT-006	S	Line item hỗ trợ override địa điểm theo từng mục.

Nghiệm thu

AC-TKT-01: Phiếu kho

Cho trước	Khi	Thì
Phiếu chuyển	COMPLETED	Nguồn giảm, đích tăng
Phiếu kiểm kê	COMPLETED	Chênh lệch được tính và áp
Phiếu điều chỉnh	COMPLETED	Tồn được sửa với mã lý do

VEN - Vendor Built

Mã tính năng: inventory/VEN · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: merchant giữ một danh bạ nhà cung cấp - thông tin liên hệ, địa chỉ, mã số thuế - được đơn mua hàng tham chiếu và giữ lại cho lịch sử kể cả sau khi xóa.

Yêu cầu

ID	P	Yêu cầu
URD-VEN-001	M	Chủ có thể tạo vendor trong một merchant.
URD-VEN-002	M	Vendor có tên, thông tin liên hệ (email, điện thoại), địa chỉ, và một định danh hệ thống (VEN_YYYYMMDD_id).
URD-VEN-003	S	Vendor có thể lưu một mã số thuế.
URD-VEN-004	M	Vendor dùng soft-delete; tham chiếu PO lịch sử được giữ.
URD-VEN-005	M	Vendor được cô lập theo từng merchant.

Nghiệm thu

AC-VEN-01: Vòng đời vendor

Cho trước	Khi	Thì
Chủ tạo một vendor	Lưu	Vendor nhận một định danh hệ thống và cô lập theo merchant
Vendor được PO tham chiếu bị xóa	Soft-delete	Tham chiếu PO lịch sử được giữ

PO - Đơn mua hàng Built

Mã tính năng: inventory/PO · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: chủ nhận hàng từ vendor qua quy trình đơn mua hàng; nhận hàng tăng tồn và ghi audit trail, với chế độ nhận OVERRIDE và ACCUMULATIVE.

Yêu cầu

ID	P	Yêu cầu
URD-PO-001	M	Chủ có thể tạo một PO chọn vendor + mục trong một thao tác; bắt buộc vendor.
URD-PO-002	M	Vòng đời: DRAFT → PROCESSING → RECEIVED → COMPLETED → CLOSED (chỉ chuyển hợp lệ).
URD-PO-003	M	Chủ có thể cancel một PO từ bất kỳ trạng thái không-cuối nào; tồn đã nhận không tự đảo ngược.
URD-PO-004	M	Chủ có thể revert PROCESSING → DRAFT.
URD-PO-005	M	Mục PO chỉ sửa được ở trạng thái DRAFT.
URD-PO-006	M	Một PO phải có ≥1 mục trước khi xác nhận.
URD-PO-007	M	Nhận hàng tăng tồn và tạo mục tracking.
URD-PO-008	M	Nhận hàng hỗ trợ chế độ OVERRIDE và ACCUMULATIVE.
URD-PO-009	M	PO mặc định về địa điểm mặc định của merchant trừ khi chỉ định một cái.
URD-PO-010	M	Tổng PO = subtotal − discount + tax.
URD-PO-011	S	Discount/tax thủ công vs. hệ thống được gắn cờ phân biệt rõ.
URD-PO-012	M	Mỗi PO có một số đơn mua hàng do hệ thống sinh.

Nghiệm thu

AC-PO-01: Nhận hàng Đơn mua hàng

Cho trước	Khi	Thì
PO ở PROCESSING	Nhận hàng	Tồn tăng, tracking được tạo
Chế độ OVERRIDE	-	Thay thế số lượng đã nhận
Chế độ ACCUMULATIVE	-	Cộng vào số lượng đã nhận

POI - Mục đơn mua hàng Built

Mã tính năng: inventory/POI · Phase: P1 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: mỗi dòng PO tự tính tổng từ giá, số lượng, multiplier, tax và discount; thêm cùng mục+đơn vị thì cộng dồn số lượng, và đưa dòng về 0 thì xóa dòng.

Yêu cầu

ID	P	Yêu cầu
URD-POI-001	M	Thêm cùng (itemType, itemId, uom) cộng dồn số lượng; uom khác tạo một line mới.
URD-POI-002	M	Tổng mục = (unitPrice × quantity × multiplier) + tax − discount.
URD-POI-003	M	Đặt số lượng mục ≤ 0 soft-delete line đó và tính lại tổng PO.
URD-POI-004	S	Đơn giá mặc định về giá vốn đang hoạt động của biến thể.
URD-POI-005	S	UOM mặc định về đơn vị cơ sở của mục kho.

Nghiệm thu

AC-POI-01: Cộng dồn dòng

Cho trước	Khi	Thì
Cùng (itemType, itemId, uom) thêm hai lần	Thêm	Số lượng cộng dồn trên một dòng
Số lượng dòng đặt về 0	Lưu	Dòng soft-delete và tổng PO tính lại

MAT - Nguyên vật liệu Built

Mã tính năng: inventory/MAT · Phase: P3 · PRDs: - · Dev: @nx/inventory

Làm gì cho người dùng: merchant F&B theo dõi nguyên liệu thô tách biệt với sản phẩm bán được, mỗi cái có tên i18n và nhiều lược đồ định danh (SKU, barcode, QR) cùng tìm kiếm theo barcode.

Yêu cầu

ID	P	Yêu cầu
URD-MAT-001	M	Chủ có thể tạo nguyên vật liệu trong một merchant.
URD-MAT-002	M	Nguyên vật liệu có một định danh hệ thống (MAT_YYYYMMDD_id) và một tên i18n.
URD-MAT-003	M	Tên nguyên vật liệu hỗ trợ nhiều locale.
URD-MAT-004	M	Mô tả nguyên vật liệu sửa được.
URD-MAT-005	M	Nguyên vật liệu có thể vô hiệu hóa.
URD-MAT-006	M	Nguyên vật liệu có thể lưu trữ (cuối, chỉ đọc).
URD-MAT-007	M	Định danh nguyên vật liệu là duy nhất.
URD-MAT-101	M	Chủ có thể đính một định danh BARCODE vào một nguyên vật liệu.
URD-MAT-102	M	Nguyên vật liệu hỗ trợ lược đồ định danh: SYSTEM, SLUG, SKU, BARCODE, QRCODE.
URD-MAT-103	M	Một cặp (scheme, code) là duy nhất xuyên các nguyên vật liệu.
URD-MAT-104	M	Lược đồ định danh mặc định về SYSTEM khi không chỉ định.
URD-MAT-105	S	Nhiều định danh của lược đồ khác nhau có thể cùng tồn tại trên một nguyên vật liệu.
URD-MAT-106	S	Nguyên vật liệu tìm được theo barcode đã đăng ký.

Nghiệm thu

AC-MAT-01: Định danh barcode

Cho trước	Khi	Thì
Chủ đính một BARCODE vào nguyên vật liệu	Tìm theo barcode đó	Nguyên vật liệu được tìm thấy
Cùng (scheme, code) trên nguyên vật liệu khác	Lưu	Bị từ chối - cặp phải duy nhất

REC - Công thức / BOM In-progress

Mã tính năng: inventory/REC · Phase: P3 · PRDs: - · Dev: @nx/inventory · ADR-0001

Làm gì cho người dùng: merchant F&B định nghĩa công thức có phiên bản (bill of materials) cho từng biến thể sản phẩm; khi một mục phiếu bếp tiến triển, công thức đang kích hoạt tự giảm nguyên vật liệu và ghi biến động.

Yêu cầu

ID	P	Yêu cầu
URD-REC-001	M	Chủ có thể tạo một công thức đính vào một biến thể sản phẩm.
URD-REC-002	M	Công thức có một phiên bản (mặc định 1.0).
URD-REC-003	M	(principal, version) là duy nhất mỗi công thức.
URD-REC-004	M	Mục công thức chỉ định một nguyên vật liệu, số lượng, và đơn vị.
URD-REC-005	M	Mục công thức có thể được thêm vào một công thức.
URD-REC-006	M	Cùng nguyên vật liệu xuất hiện tối đa một lần mỗi công thức.
URD-REC-007	M	Chủ có thể kích hoạt một công thức.
URD-REC-008	M	Chủ có thể vô hiệu hóa một công thức.
URD-REC-009	S	Sửa một công thức đã kích hoạt tạo một phiên bản mới; bản gốc được giữ.
URD-REC-010	S	Nhiều phiên bản công thức có thể được liệt kê mỗi principal.
URD-REC-011	M	Chỉ phiên bản công thức đã kích hoạt được dùng tại runtime.
URD-REC-101	M	Mục công thức tham chiếu một nguyên vật liệu hợp lệ.
URD-REC-102	M	Số lượng mục công thức lưu với độ chính xác thập phân (4 chữ số).
URD-REC-103	M	Mục công thức lưu một đơn vị.
URD-REC-104	M	Số lượng mục công thức sửa được.
URD-REC-105	M	Soft-delete mục công thức cho phép thêm lại cùng nguyên vật liệu.
URD-REC-201	M	Một thay đổi trạng thái mục phiếu bếp kích hoạt tra cứu công thức và chuẩn bị giảm tại địa điểm mặc định.
URD-REC-202	M	Mỗi thành phần công thức được giảm; một mục tracking (Used as Material) được tạo.
URD-REC-203	M	Giảm thành phần cập nhật tồn tại địa điểm mặc định.
URD-REC-204	M	Công thức đã kích hoạt cho biến thể là cái được phân rã.
URD-REC-205	M	Một event material.stock-changed được phát sau khi phân rã.
URD-REC-206	S	Không có địa điểm mặc định → log warning, bỏ qua (không lỗi cứng).
URD-REC-207	S	Không có công thức đã kích hoạt → no-op âm thầm.
URD-REC-208	C	Địa điểm bếp không-mặc-định được tôn trọng (đang chờ - code hiện tại dùng mặc định của merchant).

Nghiệm thu

AC-REC-01: Phân rã BOM Bếp

Cho trước	Khi	Thì
Biến thể với công thức đã kích hoạt	Mục bếp đổi trạng thái	Nguyên vật liệu được giảm theo từng mục công thức
Không có công thức đã kích hoạt	-	No-op âm thầm
Không có địa điểm mặc định	-	Warning được log, bỏ qua

IOP - Vận hành Kho cho F&B & Bán lẻ Planned

Mã tính năng: inventory/IOP · Phase: P2 (T7-T8) · PRDs: PRD-IOP-001 · Dev: @nx/inventory

Mang lại gì cho người dùng: merchant thực sự vận hành kho từ ứng dụng - phiếu, đơn mua, kiểm kê - rồi đi sâu theo ngành: F&B định mức tự trừ nguyên liệu kèm lô/HSD; bán lẻ nhập/xuất bằng barcode với tồn quầy realtime. (Backend phần lớn đã có; increment này làm cho dùng được end-to-end.)

Yêu cầu

ID	P	Yêu cầu
URD-IOP-001	M	Chủ quán ghi nhập/xuất kho bằng màn phiếu (mọi loại phiếu dùng được từ app)
URD-IOP-002	M	Đơn mua hàng quản lý end-to-end từ app (tạo → nhận)
URD-IOP-003	M	Kiểm kê & điều chỉnh tồn thực hiện từ app
URD-IOP-004	M	F&B: bán món có định mức tự trừ nguyên liệu (kiểm chứng e2e, kèm màn công thức)
URD-IOP-005	M	Bán lẻ: nhập/xuất kho bằng quét barcode
URD-IOP-006	S	Lô + HSD ghi nhận khi nhập; nhìn thấy hàng cận hạn
URD-IOP-007	S	Tồn realtime hiển thị tại quầy
URD-IOP-008	C	Tạp hoá: chia gói rút gọn (1 vật tư vào → 1 mặt hàng ra)

Nghiệm thu

AC-IOP-01: Vận hành kho từ app

Given	When	Then
Merchant có NCC	Tạo PO, nhận hàng, kiểm kê	Tồn khớp lịch sử phiếu; phiếu chi tự sinh khi nhận
Món F&B có định mức	Khách mua món	Tồn nguyên liệu giảm theo công thức

PRO - Đơn sản xuất & Phân rã BOM In-progress

Mã tính năng: inventory/PRO · Phase: P3 · PRDs: PRD-PRO-001 · Dev: @nx/inventory

Làm gì cho người dùng: merchant kiểu làm-vào-kho (tiệm bánh, bếp trung tâm, lắp ráp nhẹ) lên kế hoạch một lượt sản xuất như một chứng từ - thành phẩm nào, từ công thức nào, bao nhiêu, ở đâu - theo dõi kế hoạch vs. thực tế vs. hao hụt qua một vòng đời. Phía sau, một phân rã BOM đa cấp làm phẳng công thức gắn kèm qua các bán thành phẩm lồng nhau xuống tận nguyên vật liệu lá mà một lượt tiêu hao, với chốt chặn độ sâu và chu trình.

Yêu cầu

ID	P	Yêu cầu
URD-PRO-001	M	Chủ có thể tạo một đơn sản xuất nhắm tới thành phẩm (ProductVariant hoặc Material) trong merchant.
URD-PRO-002	M	Một đơn sản xuất gắn với một công thức nguyên vật liệu (BOM) dẫn dắt phân rã thành phần.
URD-PRO-003	M	Đơn sản xuất mang số lượng kế hoạch / thực tế / hao hụt theo đơn vị đo ở độ chính xác thập phân (4 chữ số).
URD-PRO-004	M	Vòng đời đơn sản xuất: DRAFT → IN_PROGRESS → DONE / CANCELLED (DONE và CANCELLED tận cùng); chỉ chuyển đổi hợp lệ được phép.
URD-PRO-005	M	Mỗi đơn sản xuất có một số sản xuất sinh tự động, duy nhất, không sửa bởi người dùng.
URD-PRO-006	M	Đơn sản xuất nêu địa điểm nơi thành phần được rút và thành phẩm được làm ra.
URD-PRO-007	S	Đơn sản xuất hỗ trợ cửa sổ lịch (lịch bắt đầu / kết thúc) cho hoạch định hàng đợi sản xuất.
URD-PRO-008	S	Đơn sản xuất ghi mốc thời gian bắt đầu / hoàn thành / huỷ.
URD-PRO-009	S	Đơn sản xuất có thể mang một số lô đầu ra và ngày hết hạn cho truy vết thu hồi.
URD-PRO-010	M	Đơn sản xuất cô lập theo merchant và dùng soft-delete.
URD-PRO-011	M	Một công thức gắn kèm được làm phẳng qua bán thành phẩm lồng nhau xuống nguyên vật liệu lá (BOM đa cấp).
URD-PRO-012	M	Phân rã dùng phiên bản công thức ĐÃ KÍCH HOẠT mới nhất cho mỗi principal.
URD-PRO-013	M	Phân rã bị chốt bởi độ sâu lồng tối đa và từ chối chuỗi công thức có chu trình.
URD-PRO-014	M	Mỗi số lượng thành phần lá là tích của các số lượng dọc đường đi phân rã của nó.
URD-PRO-015	M	Một thành phần biến thể không có công thức con đã kích hoạt bị bỏ qua; một nguyên vật liệu không có công thức con là một lá tiêu hao trực tiếp.
URD-PRO-016	M	Tiêu hao sản xuất và đầu ra thành phẩm được ghi như mục tracking bất biến tham chiếu tới đơn sản xuất, kiểu PRODUCTION_CONSUME / PRODUCTION_OUTPUT.

Nghiệm thu

AC-PRO-01: Tạo một đơn sản xuất

Cho trước	Khi	Thì
Một thành phẩm có công thức đã kích hoạt	Chủ tạo một đơn sản xuất với số lượng kế hoạch và địa điểm	Một số sản xuất duy nhất được gán và đơn mở ở DRAFT
Cùng merchant	Đơn được tạo	Đơn cô lập theo merchant và soft-delete được

AC-PRO-02: Chuyển đổi vòng đời

Cho trước	Khi	Thì
Đơn ở DRAFT	Bắt đầu / huỷ	Chuyển sang IN_PROGRESS / CANCELLED
Đơn ở IN_PROGRESS	Hoàn thành / huỷ	Chuyển sang DONE / CANCELLED
Đơn ở DONE hoặc CANCELLED	Bất kỳ chuyển đổi nào	Từ chối - trạng thái tận cùng

AC-PRO-03: Phân rã BOM đa cấp

Cho trước	Khi	Thì
Một công thức mà thành phần của nó tự là một bán thành phẩm	Phân rã chạy	Làm phẳng ra nguyên vật liệu lá với số lượng nhân dọc từng nhánh
Một chuỗi công thức tham chiếu chính nó	Phân rã chạy	Từ chối - phát hiện chu trình
Một cây công thức sâu hơn tối đa	Phân rã chạy	Từ chối - vượt độ sâu tối đa
Một thành phần biến thể không có công thức con đã kích hoạt	Phân rã chạy	Bỏ qua, không phát lá

AC-PRO-04: Từ vựng tracking sản xuất

Cho trước	Khi	Thì
Một biến động sản xuất	Được ghi	Một mục tracking bất biến kiểu PRODUCTION_CONSUME / PRODUCTION_OUTPUT tham chiếu tới đơn sản xuất

7. Ràng buộc & Không-mục-tiêu

Yêu cầu xuyên suốt (CON) áp cho mọi tính năng ở trên và được test là TC-CON-*.

Yêu cầu xuyên suốt (CON)

ID	P	Yêu cầu
URD-CON-001	M	Mọi endpoint kho yêu cầu xác thực (JWT hoặc basic auth).
URD-CON-002	M	Mọi bản ghi dùng soft-delete; bản ghi soft-delete bị loại khỏi listing chuẩn.
URD-CON-003	M	Số lượng available âm hiện được dung thứ (ràng buộc nghiệp vụ có ghi tài liệu, không phải bug).
URD-CON-004	M	Trừ tồn là idempotent mỗi (referenceType, referenceId).

Ràng buộc

ID	Ràng buộc
C-01	Một địa điểm mặc định mỗi merchant tại mọi thời điểm.
C-02	Một bản ghi tồn mỗi (mục, địa điểm, lot, serial).
C-03	Available = on-hand − reserved (âm hiện được dung thứ).
C-04	Bản ghi tracking là bất biến.
C-05	Biến động tồn là idempotent qua (referenceType, referenceId).
C-06	Mục PO chỉ sửa được ở DRAFT.
C-07	19 loại tracking dựng sẵn (+ 1 tùy chỉnh) lúc khởi động.
C-08	Mọi bản ghi dùng soft-delete.
C-09	Mọi số lượng dùng độ chính xác thập phân (4 chữ số).

Không-mục-tiêu

• BOM đa cấp (nguyên vật liệu làm principal cho cụm lắp ráp con)
• Phần trăm hao hụt và sản lượng công thức
• Phân rã BOM khi bán cho bán lẻ phi-F&B
• Bắt buộc tồn-âm tại POS
• Quét barcode đầy đủ cho kiểm kê
• Định giá tồn đa tiền tệ

8. Lịch sử Phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-28	Q. Do - QE	Khởi tạo từ phân tích code	v0.1
2026-04-15	Claude (AI pair)	Thêm yêu cầu Material và MaterialRecipe (BOM)	v0.2
2026-04-16	Q. Do - QE	Hợp nhất các lĩnh vực yêu cầu	v0.3
2026-05-30	Claude (AI pair)	Định dạng lại theo template module; điều hòa loại tracking về 19 (tài liệu dev)	v0.4
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine); mỗi tính năng tự mang yêu cầu + nghiệm thu; CON chuyển vào Ràng buộc	v0.5
2026-06-15	Claude (AI pair)	Thêm LSE - Định danh lô / serial & hạn dùng (bucket tồn truy vết + registry định danh)	v0.6