URD: Kho
| Module | CORE-06 | Phiên bản | v0.4 |
|---|---|---|---|
| Trạng thái | In-progress | Ngày | 2026-05-30 |
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 (warehouse) 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ệ |
| Catalog loại tracking (19 cái pre-seed) | Tích hợp quét barcode đầy đủ |
| Quản lý vendor (nhà cung cấp) | 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ỏ) | |
| Catalog 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 | |
| BOM explosion runtime 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 pre-seed + 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. |
| 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. Yêu cầu Chức năng
Mỗi bảng cho một lĩnh vực chức năng. Mã
<AREA>khớp với ID test-case. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).
5.1 Địa điểm kho (LOC)
| 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. |
5.2 Mục kho (ITM)
| 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. |
5.3 Tồn kho (STK)
| 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 là nguyên tử — thất bại một phần rollback hoàn toàn. |
| URD-STK-007 | C | Thay đổi mức tồn lịch sử xem được. |
5.4 Tracking kho (TRK)
| 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 pre-seed + 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. |
5.5 Phiếu kho (TKT)
| 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. |
5.6 Vendor (VEN)
| 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. |
5.7 Đơn mua hàng (PO)
| 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. |
5.8 Mục Đơn mua hàng (POI)
| 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. |
5.9 Nguyên vật liệu (MAT)
| 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ý. |
5.10 Công thức / BOM (REC)
| 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 explode. |
| URD-REC-205 | M | Một event material.stock-changed được phát sau explosion. |
| 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). |
5.11 Ràng buộc & 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). |
6. Tiêu chí Chấp nhận
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 |
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ị |
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 |
AC-BOM-01: 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 |
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 |
7. Ràng buộc & Không-mục-tiêu
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 pre-seed (+ 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
- BOM explode-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 |