PRD: Định danh lô / serial & hạn dùng
| Module | Kho (CORE-06) | PRD ID | PRD-LSE-001 |
| Trạng thái | Shipped | Chủ sở hữu | Inventory squad |
| Ngày | 2026-06-15 | Phiên bản | v1.0 |
| Packages | @nx/inventory · @nx/core · @nx/search | URD | LSE · STK · TRK |
TL;DR
Làm cho tồn truy vết được. Cùng một mục ở cùng một địa điểm tách thành các bucket tồn 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 - nên merchant có thể thu hồi một lô lỗi, hủy một lô hết hạn, và theo dõi một đơn vị theo serial từ đầu đến cuối. Một registry định danh đi kèm: mã SKU / barcode / QR phân giải ở cấp sản phẩm (mục), mã IMEI / serial ở cấp đơn vị (tồn), và mọi cặp
(scheme, code)đều duy nhất toàn cục nên một lần quét luôn phân giải về đúng một thực thể tồn. Lô và hạn dùng được bắt lúc nhận hàng và trên phiếu, snapshot bất biến trên mọi biến động, và hàng hết hạn rời kho qua một lý do hủy chuyên biệt.
1. Bối cảnh & Vấn đề
Mức tồn (STK) cho merchant biết họ giữ bao nhiêu, và audit trail biến động (TRK) cho biết nó đã thay đổi thế nào - nhưng riêng lẻ không cái nào cho biết một số lượng thuộc lô vật lý hay đơn vị nào. Một tiệm bánh biết một đợt giao bột bị nhiễm bẩn, một nhà thuốc phải rút mọi thứ hết hạn trong tháng, một cửa hàng điện tử bảo hành một máy theo IMEI - tất cả đều cần định danh tồn ở dưới cấp mục, và một cách biến mã quét trở lại bản ghi đúng.
Không có bucket lô/serial, mọi đơn vị của một mục gộp thành một đống không phân biệt: thu hồi nghĩa là bỏ tất cả, một hạn dùng không có gì để gắn vào, và một số serial không có chỗ để lưu. Không có registry định danh duy nhất, một barcode chỉ là một chuỗi không bảo đảm trỏ về một thứ. Increment này thêm cả hai: bucket tồn truy vết được keyed theo lô và serial với hạn dùng/ngày sản xuất, và một registry phân giải mã SKU / barcode / QR / IMEI / serial về đúng một thực thể tồn.
2. Mục tiêu & Không mục tiêu
Mục tiêu
- Phân bucket tồn theo (mục, địa điểm, lô, serial) để các lô và serial khác nhau của một mục được theo dõi riêng.
- Mang hạn dùng và ngày sản xuất trên mỗi bucket truy vết được.
- Bắt lô / serial / hạn dùng lúc nhận hàng (line đơn mua hàng) và trên phiếu kho.
- Snapshot lô / serial / hạn dùng đã biến động vào mục tracking bất biến trên mọi biến động.
- Một registry định danh ghi SKU / barcode / QR ở cấp mục và IMEI / serial ở cấp đơn vị, với cặp
(scheme, code)duy nhất toàn cục nên một lần quét phân giải về một thực thể. - Hủy hàng hết hạn qua một lý do biến động chuyên biệt giảm đúng lô.
Không mục tiêu
- Một dashboard sắp-hết-hạn chuyên biệt hay engine chọn FEFO tự động - các ngày được bắt và mô hình dữ liệu hỗ trợ điều đó (URD-LSE-013 vẫn là Could); UI vận hành xuất hiện với PRD-IOP-001.
- Định giá tồn theo lô (lot costing FIFO / LIFO) - cost trung bình mỗi bucket được ghi, nhưng báo cáo định giá cấp lô nằm ngoài phạm vi.
- Định giá tồn đa tiền tệ.
- Tích hợp phần cứng quét barcode đầy đủ cho kiểm kê (Phạm vi).
3. Chỉ số thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Tách lô | Hai lần nhận cùng một mục với lô khác nhau tạo hai bucket tồn riêng, không phải một con số gộp |
| Phân giải quét | Một (scheme, code) được quét phân giải về đúng một thực thể tồn, toàn hệ thống |
| Toàn vẹn định danh | Không hai bản ghi active nào chia sẻ cùng cặp (scheme, code) |
| Trọn vẹn truy vết | Mọi biến động của một bucket truy vết được mang lô / serial / hạn dùng đã biến động |
| Phạm vi thu hồi | Chủ có thể xác định mọi địa điểm giữ một lô nêu tên chỉ từ các bản ghi tồn |
4. Nhân vật & Tình huống
| Nhân vật | Mục tiêu trong tính năng này |
|---|---|
| Chủ / Quản lý | Thu hồi một lô lỗi, hủy hàng hết hạn, bảo hành một đơn vị theo serial |
| Nhân viên kho | Ghi lô / serial / hạn dùng khi nhận hàng hoặc chạy phiếu |
| Thu ngân | Quét một barcode và đến đúng mục cần |
| Tích hợp kênh | Tra một mục hoặc đơn vị theo một định danh đã đăng ký |
Tình huống cốt lõi: nhận hai đợt giao cùng một nguyên liệu với lô và hạn dùng khác nhau → mỗi cái thành bucket tồn riêng → một thông báo nhiễm bẩn đến → chủ tìm mọi địa điểm giữ lô đó → lô hết hạn được hủy qua lý do hết hạn và trail ghi lại lô đã rời. Song song, một cửa hàng điện tử đăng ký IMEI của mỗi máy với đơn vị tồn của nó; một lần quét IMEI đó phân giải về đúng một đơn vị.
5. User Stories
- Là một chủ, tôi muốn mỗi lô của một mục được theo dõi riêng, để tôi có thể thu hồi một đợt mà không bỏ phần còn lại.
- Là một chủ, tôi muốn một hạn dùng trên mỗi lô, để tôi có thể rút tồn trước khi nó hỏng.
- Là nhân viên kho, tôi muốn ghi lô, serial, và hạn dùng khi nhận hàng, để truy vết bắt đầu ngay tại cửa.
- Là một chủ, tôi muốn một đơn vị theo serial mang IMEI / serial của nó, để tôi có thể bảo hành và truy vết một đơn vị.
- Là một thu ngân, tôi muốn một barcode được quét phân giải về đúng một mục, để tôi không bao giờ tính nhầm sản phẩm.
- Là một chủ, tôi muốn hàng hết hạn được gỡ qua một lý do "hết hạn" rõ ràng, để audit trail giải thích phần xóa sổ.
6. Yêu cầu chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | 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 riêng | URD-LSE-001 · URD-STK-001 |
| FR-2 | Mỗi bucket mang số lô, số serial, hạn dùng, và ngày sản xuất | URD-LSE-002 |
| FR-3 | Bucket không có lô/serial gộp thành một bản ghi (NULL coi là bằng nhau), nên mục không truy vết giữ một bucket duy nhất | URD-LSE-003 |
| FR-4 | Lô / serial / hạn dùng được bắt lúc nhận hàng trên line PO; line theo serial ghi một serial mỗi đơn vị nhận | URD-LSE-004 |
| FR-5 | 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-005 |
| FR-6 | 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-006 · URD-TRK-001..002 |
| FR-7 | Một registry định danh ghi SKU / BARCODE / QRCODE ở cấp mục và IMEI / SERIAL ở cấp đơn vị (tồn) | URD-LSE-007 |
| FR-8 | 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-008 |
| FR-9 | 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-009 |
| FR-10 | Định danh được scope theo merchant qua principal (mục hoặc tồn) và dùng soft-delete | URD-LSE-010 |
| FR-11 | Hàng hết hạn được hủy qua lý do biến động EXPIRED chuyên biệt giảm đúng lô | URD-LSE-011 |
| FR-12 | 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 | URD-LSE-012 · URD-PRO-009 |
Toàn văn yêu cầu và tiêu chí nghiệm thu nằm trong URD Kho - LSE. PRD này tham chiếu thay vì lặp lại.
7. Yêu cầu phi chức năng
| Khía cạnh | Yêu cầu |
|---|---|
| Duy nhất định danh | Một cặp (scheme, code) duy nhất trên mọi bản ghi active toàn hệ thống; mã đã soft-delete giải phóng cặp để dùng lại |
| Toàn vẹn bucket | Khóa bucket (mục, địa điểm, lô, serial) được áp đặt để các NULL bằng nhau vẫn gộp thành một bản ghi - không có bucket trùng do sơ ý |
| Bất biến | Lô / serial / hạn dùng trên một mục biến động là một snapshot chỉ-thêm; sửa lỗi qua biến động mới |
| Tenancy & authz | Định danh phân giải merchant qua principal (mục hoặc tồn); mọi thao tác scope theo merchant (x-merchant-id) và gated bởi quyền kho |
| Khả năng tìm kiếm | Định danh đã đăng ký được denormalize cho tra cứu nên một lần quét phân giải nhanh không cần quét mọi bản ghi |
| i18n | Nhãn scheme định danh song ngữ ({ en, vi }) |
8. UX & Luồng
Các màn hình nhận hàng và phiếu (trong apps/client) cho phép nhân viên nhập lô, serial, hạn dùng, và ngày sản xuất mỗi line, và đăng ký một mã đơn vị hoặc mục với bản ghi kết quả. Một lần quét bất kỳ mã đã đăng ký nào đến đúng một thực thể tồn của nó.
9. Dữ liệu & Miền
| Thực thể | Vai trò trong truy vết |
|---|---|
InventoryStock | Một bucket số lượng theo (mục, địa điểm, lô, serial); mang hạn dùng và ngày sản xuất và một snapshot cost mỗi bucket |
InventoryTracking | Mục biến động bất biến; snapshot lô / serial / hạn dùng đã biến động |
InventoryIdentifier | Một mã quét đã đăng ký, neo đa hình vào một mục (SKU/BARCODE/QRCODE) hoặc một đơn vị tồn (IMEI/SERIAL); (scheme, code) duy nhất toàn cục |
Chỉ là khái niệm - schema đầy đủ và bất biến nằm trong mô hình miền kho. Principal của định danh là một soft reference phân giải lúc chạy, không phải khóa ngoại database.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Mức tồn (STK, PRD-STK-001) - lô/serial mở rộng khóa bucket tồn.
- Audit trail biến động (TRK) - mỗi biến động snapshot lô đã biến động.
- Nhận hàng & phiếu (PO, TKT) - các điểm bắt lô / serial / hạn dùng.
@nx/core- mô hình tồn, tracking, và định danh (schemes, principal types, khóa bucket).@nx/search- denormalize định danh đã đăng ký cho tra cứu quét nhanh.
Giả định
- Một merchant chọn mục nào theo lô hoặc serial; mục không truy vết giữ một bucket lô-NULL duy nhất.
- Một line nhận theo serial đại diện một đơn vị vật lý (số lượng kế hoạch 1).
- Lớp tồn và biến động (STK, TRK) đã có sẵn là các bản ghi mà lô/serial/hạn dùng gắn vào.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Cùng mục, cùng địa điểm, lô khác nhau gộp thành một con số | Khóa bucket gồm lô + serial, nên mỗi lô là bản ghi riêng |
| Hai bản ghi cùng đòi một barcode | (scheme, code) duy nhất toàn cục trên bản ghi active; trùng bị từ chối |
| Dùng lại một mã sau khi bản ghi bị gỡ | Duy nhất chỉ áp cho bản ghi active; soft-delete một mã giải phóng cặp |
| Chưa có màn hình sắp-hết-hạn | Các ngày được bắt và mô hình hỗ trợ; UI vận hành xuất hiện với PRD-IOP-001; URD-LSE-013 vẫn là Could |
| Một line serial nhận với số lượng > 1 | Bị từ chối - một line serial phải đại diện đúng một đơn vị |
12. Kế hoạch phát hành & Tiêu chí ra mắt
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P3 - truy vết cho F&B (lô/hạn) và retail (serial/IMEI), cùng STK và TRK trong danh mục tính năng URD |
| Triển khai | Mọi merchant; bắt lô/serial là opt-in mỗi mục, không feature flag |
| Migration | Thêm cột lô / serial / hạn dùng / sản xuất vào bản ghi tồn và tracking; registry định danh seed các scheme nhận diện |
| Tiêu chí ra mắt | Lô khác nhau tạo bucket khác nhau; một (scheme, code) được quét phân giải về một thực thể; trùng bị từ chối; mọi biến động snapshot lô của nó; hàng hết hạn rời qua lý do EXPIRED |
| Giám sát | Tỷ lệ từ chối định danh trùng, số bucket truy vết mỗi merchant, biến động hủy-hết-hạn |
13. FAQ
Điều gì khiến hai con số tồn là "lô khác nhau"? Khóa bucket là (mục, địa điểm, lô, serial). Nhận cùng một mục dưới một số lô mới thì nó thành bản ghi riêng với hạn dùng riêng - lô cũ không bị động đến.
Barcode và serial sống ở đâu? Trong registry định danh. Mã SKU / barcode / QR gắn ở cấp mục (sản phẩm); mã IMEI / serial gắn ở cấp đơn vị (tồn). Mọi cặp (scheme, code) duy nhất toàn hệ thống, nên một lần quét phân giải về một thực thể.
Hai sản phẩm có thể chung một barcode không? Không - một (scheme, code) trùng bị từ chối cho bản ghi active. Gỡ một mã (soft-delete) giải phóng cặp để dùng lại.
Có báo cáo sắp-hết-hạn không? Hạn dùng và ngày sản xuất được bắt trên mọi lô, và mô hình dữ liệu hỗ trợ FEFO và hiển thị sắp-hết-hạn (URD-LSE-013, một Could); màn hình hướng-vận-hành xuất hiện với PRD-IOP-001.
Hàng hết hạn được gỡ thế nào? Qua một lý do biến động EXPIRED chuyên biệt giảm đúng lô và ghi phần xóa sổ vào trail bất biến - nó không bao giờ biến mất âm thầm.
Mục không truy vết có một bucket cho mỗi thứ không? Không - mục không có lô/serial giữ một bucket duy nhất (NULL bằng nhau gộp), nên tồn retail đơn giản giữ đơn giản.
Tham khảo
- URD: Kho - LSE · STK · TRK
- PRD liên quan: Stock, items & movement tracking · Stock operations F&B & Retail · Đơn sản xuất & phân rã BOM
- Module: Kho - tổng quan + truy vết
- Dev: @nx/inventory · mô hình miền