PRD: Tồn kho, items & movement tracking
| Module | Kho (CORE-06) | PRD ID | PRD-STK-001 |
| Status | Shipped | Owner | Inventory squad |
| Date | 2026-05-28 | Version | v1.0 |
| Packages | @nx/inventory · @nx/core · apps/client | URD | STK · ITM · TRK |
TL;DR
Cho merchant một góc nhìn duy nhất, có thể chỉnh sửa, về những gì họ thực sự đang giữ - on-hand, reserved, và available theo từng item theo từng location, với độ chính xác thập phân - được hỗ trợ bởi một endpoint danh sách tồn dạng aggregate và một audit trail bất biến của biến động. Ngưỡng low-stock và một tín hiệu cần chú ý làm nổi bật những item cần nhập thêm, để chủ nhìn và sửa tồn trong nháy mắt thay vì phải suy luận từ tầng biến động.
1. Context & Problem
Kho đã tự tạo một item cho mỗi biến thể sản phẩm (ITM) và ghi mọi biến động một cách bất biến (TRK), nhưng merchant không có một bề mặt hợp nhất, có thể chỉnh sửa cho những gì họ thực sự đang giữ. Các con số tồn nằm sát tầng biến động, và cờ oversell nằm trên item thay vì trên bản ghi tồn - nên một góc nhìn rõ ràng "còn bao nhiêu on-hand / reserved / available theo từng location", và một endpoint danh sách để dựng nó lên, đều đang thiếu.
Không có bề mặt đó, merchant không thể trả lời câu hỏi tồn kho cơ bản nhất trong nháy mắt, không thể phát hiện item sắp hết, và không thể sửa một con số mà không phải suy luận từ các bản ghi biến động thô. PRD này lấp khoảng trống đó trên nền các primitive item và tracking sẵn có, đem lại cho chủ một màn hình quản lý tồn đúng nghĩa.
2. Goals & Non-Goals
Goals
- Trình bày on-hand / reserved / available theo từng item theo từng location với độ chính xác thập phân (
STK). - Biến động đầu tiên tự tạo bản ghi tồn; cờ oversell chuyển từ item → bản ghi tồn.
- Một endpoint danh sách inventory-items dạng aggregate với rollup tồn, cùng một endpoint overview.
- Mang ngưỡng low-stock (min/max) xuyên qua danh sách và gắn cờ item cần chú ý.
- Một màn hình tồn ở client: danh sách, panel sửa đầy đủ field, sửa theo từng location, xác nhận khi lưu, làm nổi bật mục cần chú ý.
- Giữ audit trail bất biến của biến động (
TRK) làm nguồn sự thật phía sau mọi thay đổi tồn.
Non-Goals
- Cưỡng chế chặn tồn âm tại POS - available âm được chấp nhận (URD-CON-003).
- Định giá tồn đa tiền tệ.
- Một UI duyệt lịch sử mức tồn riêng - lịch sử được ghi qua
TRK;URD-STK-007vẫn là Could. - Các luồng phiếu kho và nhận hàng đơn mua (TKT, PO) - các increment riêng.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Khả năng thấy tồn | Chủ đọc được on-hand / reserved / available theo từng item theo từng location từ một màn hình |
| Toàn vẹn audit | Không có dòng tồn nào thiếu bản ghi biến động bất biến tương ứng |
| Độ chính xác available | available = on-hand − reserved đúng trên toàn danh sách ở độ chính xác thập phân |
| Tín hiệu chú ý | Item dưới ngưỡng low-stock được gắn cờ và làm nổi bật trong danh sách |
4. Personas & Use Cases
| Persona | Goal trong tính năng này |
|---|---|
| Chủ | Thấy tồn thực theo từng location, phát hiện tồn thấp, sửa các con số |
| Nhân viên kho | Sửa các field tồn và số lượng theo từng location với một bước xác nhận |
| Thu ngân | Đọc tình trạng còn hàng tại điểm bán |
Core scenarios: mở màn hình tồn → thấy on-hand/reserved/available theo từng item theo từng location với item low-stock được làm nổi bật → sửa một bản ghi tồn (đầy đủ field, theo từng location) → xác nhận khi lưu → thao tác sửa ghi một bản ghi biến động và con số available được tính lại.
5. User Stories
- Là một chủ, tôi muốn thấy on-hand, reserved, và available theo từng item theo từng location trên một màn hình, để tôi luôn biết mình giữ gì và ở đâu.
- Là một chủ, tôi muốn item dưới ngưỡng được gắn cờ và làm nổi bật, để tôi nhập thêm trước khi hết hàng.
- Là nhân viên kho, tôi muốn sửa đầy đủ field của một bản ghi tồn theo từng location, để tôi sửa con số chính xác.
- Là nhân viên kho, tôi muốn một bước xác nhận khi lưu trên các thao tác sửa tồn, để tôi không commit một con số sai.
- Là một chủ, tôi muốn mọi thay đổi tồn được hỗ trợ bởi một bản ghi biến động bất biến, để con số luôn có thể audit.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Một bản ghi tồn cho mỗi (item, location, lot, serial); available = on-hand − reserved | URD-STK-001..002 |
| FR-2 | Mọi số lượng lưu ở độ chính xác thập phân (4 chữ số) | URD-STK-003 |
| FR-3 | Biến động đầu tiên tự tạo bản ghi tồn; chủ xem được mức hiện tại | URD-STK-004 |
| FR-4 | Mốc thời gian last-stocked / last-counted tự cập nhật | URD-STK-005 |
| FR-5 | Cập nhật tồn là một thao tác duy nhất - lỗi một phần rollback toàn bộ | URD-STK-006 |
| FR-6 | Cờ oversell nằm trên bản ghi inventory-stock (chuyển từ item) | URD-STK-001..004 |
| FR-7 | Endpoint danh sách inventory-items dạng aggregate với rollup tồn, cùng một endpoint overview | URD-STK-004 · URD-ITM-001..006 |
| FR-8 | Ngưỡng low-stock (min/max, min ≤ max) mang xuyên qua danh sách và gắn cờ chú ý | URD-ITM-003 |
| FR-9 | Item tự tạo theo từng biến thể, liên kết với location mặc định của merchant | URD-ITM-001..006 |
| FR-10 | Mọi thay đổi tồn ghi một entry tracking bất biến (before/change/after, reference, idempotent) | URD-TRK-001..007 |
Toàn văn requirement và tiêu chí chấp nhận nằm trong URD Kho. PRD này tham chiếu chúng thay vì lặp lại.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Toàn vẹn dữ liệu | Một thay đổi tồn và bản ghi biến động của nó được ghi cùng nhau - không có dòng tồn nào thiếu entry audit bất biến tương ứng |
| Bất biến | Bản ghi biến động chỉ ghi thêm; sửa sai thực hiện qua entry mới, không bao giờ sửa tại chỗ |
| Tenancy & authz | Mọi thao tác scope theo từng merchant (x-merchant-id); kiểm soát bằng permission của inventory |
| Độ chính xác | Tính toán số lượng dùng float(value, 4) |
| Nhất quán | Cập nhật tồn là một thao tác duy nhất; lỗi một phần rollback toàn bộ |
| Hiệu năng | Danh sách aggregate đọc rollup tồn + ngưỡng trong một call, không phải N lượt tra cứu theo từng item |
| i18n | Nhãn/trạng thái hướng người dùng là song ngữ ({ en, vi }) |
8. UX & Flows
Các màn hình chính (trong apps/client): danh sách tồn và bảng items, panel sửa tồn đầy đủ field với sửa theo từng location, dialog xác nhận khi lưu, và các chỉ báo chú ý/nổi bật cho low-stock.
9. Data & Domain
| Entity | Role |
|---|---|
InventoryStock | Bản ghi số lượng - on-hand, reserved, available theo (item, location, lot, serial); mang cờ oversell |
InventoryItem | Bản ghi tồn theo từng biến thể, liên kết với location mặc định; mang ngưỡng min/max |
InventoryTracking | Entry biến động bất biến (before/change/after, reference type/ID, tracking type) phía sau mọi thay đổi |
Chỉ ở mức khái niệm - schema và bất biến đầy đủ trong domain model của inventory.
10. Dependencies & Assumptions
Phụ thuộc vào
- Inventory items (URD-ITM) - tồn gắn vào một item tự tạo theo từng biến thể.
- Movement audit trail (URD-TRK) - mọi thay đổi tồn ghi một entry bất biến.
- Inventory locations (URD-LOC) - tồn được giữ theo từng location; phải tồn tại một location mặc định của merchant.
@nx/core- model và schema của item (ngưỡng, vị trí cờ oversell).
Giả định
- Mỗi merchant có một location mặc định và ít nhất một biến thể sản phẩm (do đó có một item).
- Tầng biến động (
TRK) đã có sẵn làm nguồn sự thật audit.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Sửa tồn và bản ghi biến động có thể lệch nhau khi lỗi một phần | Cập nhật là một thao tác duy nhất; không có dòng tồn nào thiếu entry biến động tương ứng |
| Available âm được chấp nhận | Ràng buộc nghiệp vụ có ghi nhận (URD-CON-003), không phải bug; cưỡng chế ở POS ngoài phạm vi |
| Giá trị ngưỡng low-stock mặc định | Đã giải quyết - áp một mặc định hợp lý; input ngưỡng được kiểm tra min ≤ max |
| Chưa có trình xem lịch sử tồn riêng | Lịch sử ghi qua TRK; URD-STK-007 vẫn là Could, UI riêng để sau |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 (nền tảng) - STK, ITM, TRK trong feature catalog của URD |
| Rollout | Mọi merchant; không feature flag |
| Migration | Cờ oversell dời item → bản ghi tồn; thêm ngưỡng trên model item |
| Launch criteria | Danh sách hiển thị on-hand/reserved/available theo location; thao tác sửa ghi một bản ghi biến động; available = on-hand − reserved đúng; low-stock được gắn cờ |
| Monitoring | Kiểm tra nhất quán tồn-vs-biến động, số lượng low-stock theo từng merchant, tỷ lệ lỗi sửa tồn |
13. FAQ
Cờ oversell giờ nằm ở đâu? Trên bản ghi inventory-stock, không phải item - nên oversell được quyết định theo từng dòng tồn, cạnh các số lượng mà nó chi phối.
Điều gì khiến một item hiện "cần chú ý"? Available rớt xuống dưới ngưỡng low-stock (min) của item sẽ gắn cờ và làm nổi bật dòng đó trong danh sách.
Tôi có duyệt được lịch sử mức tồn không? Không qua một trình xem riêng trong increment này - mọi thay đổi được ghi bất biến qua TRK; một UI lịch sử (URD-STK-007) là Could, để sau.
Available âm có phải bug không? Không - available âm là một ràng buộc nghiệp vụ có ghi nhận và được chấp nhận (URD-CON-003); cưỡng chế chặn tồn âm ở mức POS ngoài phạm vi.
Sửa tồn có bỏ qua audit trail không? Không - mọi thay đổi tồn, kể cả một thao tác sửa thủ công, ghi một bản ghi biến động bất biến.
References
- URD: Kho - STK · ITM · TRK
- Related PRD: Opening Balance Import · Purchase Orders
- Module: Kho - overview + traceability
- Developer: @nx/inventory · inventory-stock · domain model